marketing.generations.create

Turn a scanned website into a marketing project

POST/marketing/generations

Operation: marketing.generations.create
MCP tool: marketing_generations_create

Build a marketing video from a scanned website: the scan is turned into planned scenes and words, and the result is a project with a first revision to edit and export. Send assist: true with assetUseConsent: true to have the words written for you, or a review block to use words a person already approved. Generating costs no video time — the EXPORT charges — but the account must be able to afford the film. Answers 202 with a Location; poll until state is terminal, then read projectId. One generation at a time.

curl -X POST "https://api.gogoscreen.com/api/v1/marketing/generations" \
  -H "Authorization: Bearer $GOGOSCREEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "durationSeconds": 7, "format": "portrait", "source": { "kind": "website", "sourceId": "<sourceId>", "version": 1 }, "templateId": "<templateId>" }'

A request to this operation.

At a glance

Fact	Detail
Scopes	`marketing:write`
Credentials	a signed in dashboard session or an API key.
Rate limit	20 requests a minute per credential, in the `expensive` class.
Idempotency	Required. Send an `Idempotency-Key` header; a retry with the same key and the same body returns the stored answer with `Idempotent-Replayed: true`. The key is also written to the record this creates, so a retry cannot leave two behind. How idempotency works.
Long work	Answers `202` and queues a `marketing.generation`. Poll `/marketing/generations/{id}` until `state` is terminal, or subscribe to a webhook. This kind can be cancelled while it runs. Jobs and polling.
MCP tool	`marketing_generations_create`
Always sets	`Cache-Control: private, no-store`
Verified email	Required. An account whose email address is not verified meets `403 email_unverified` before the operation runs.
Marketing videos	Required. An account without marketing videos enabled meets `403 feature_disabled` before the operation runs.

Request body

A JSON body is required. Unknown fields are refused rather than ignored, so a typo is a 400 validation_failed rather than a setting that silently did nothing.

Name	Type	Required	Description
durationSeconds	integer	Required	One the design offers at this format, from `catalog.marketing.templates.list`. The six-second edition is retired and is refused here.7–600
format	string	Required	one of: portrait, landscape, square, four-five
source	object	Required	Which scanned website and which manifest version this is made from.
kind	string	Required	Always `website`. The only source kind this field takes.always "website"
manifestHash	string	Optional	The manifest's sha256, as `marketing.sources.get` answers it. Pins the exact scan this was planned against.pattern: ^[a-f0-9]{64}$
sourceId	string	Required	The `id` of a scanned source from `marketing.sources.list`.format: uuid
version	integer	Required	Which manifest version of that source — `marketing.sources.get` answers the current one.1–100000
templateId	string	Required	A design id from catalog.marketing.templates.list (family=website).1–64 characters
assetUseConsent	boolean	Optional	Your consent to use the pictures the scan found on your own site.always true
assist	boolean	Optional	Have the words written for you. Requires `assetUseConsent`.always true
audioMode	string	Optional	one of: music, silent, voice, voice-music
brandChoice	string	Optional	one of: saved, website
brandName	string	Optional	1–40 characters
brief	object	Optional	{ audience, objective, mustSay } — what the words should aim at.any keys
expectedRevisionId	string	Optional	format: uuid
music	object	Optional	{ trackId } from the design's own catalogue.any keys
narration	object \| null	Optional	The voice the words are written FOR: { voiceId, language, cadence, synthesisSpeed? }. Absent means no spoken narration.any keys
projectId	string	Optional	Re-generate INTO an existing project; requires `expectedRevisionId`.format: uuid
review	object	Optional	The approved copy and scene choices. Judged by the campaign contract's own schema.any keys
templateVersion	string	Optional	max 16 characters
title	string	Optional	1–200 characters

Response

This operation documents 2 success statuses. A first call answers 202. Every answer also carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset, and every error body carries a requestId.

200 OK

The work was already known — the service recognised this key on its own record and queued nothing new. Answered when the 24-hour idempotency claim has expired but the work has not.

200 OK body

Name

Type

Description

created

boolean

generation

object

10 fields inside generation

Name	Type	Description
assisted	boolean
errorCode	string \| null
id	string
projectId	string \| null
retryable	boolean
revisionId	string \| null
stage	string \| null
stageUpdatedAt	string \| null	format: date-time
state	string	one of: queued, running, succeeded, failed, cancelled
status	string

resource

object

any keys

200 OK headers
Header	Meaning
`Cache-Control`	Always `private, no-store`.
`Idempotent-Replayed`	Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.

202 Accepted

The work was queued. Poll the resource at Location. A retry with the same Idempotency-Key answers this again, with the same body and the same Location, plus Idempotent-Replayed: true.

202 Accepted body

Name

Type

Description

created

boolean

generation

object

10 fields inside generation

Name	Type	Description
assisted	boolean
errorCode	string \| null
id	string
projectId	string \| null
retryable	boolean
revisionId	string \| null
stage	string \| null
stageUpdatedAt	string \| null	format: date-time
state	string	one of: queued, running, succeeded, failed, cancelled
status	string

resource

object

any keys

202 Accepted headers
Header	Meaning
`Cache-Control`	Always `private, no-store`.
`Idempotent-Replayed`	Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.
`Location`	Where to read this marketing.generation, e.g. `/api/v1/marketing/generations/{id}`. Present on the replay too.

Errors

Every refusal is { error: { code, message, details?, requestId } }. Branch on code, never on the sentence. The full catalogue is at Errors.

Code	Status	When it happens	What to do
brand_logo_source_mismatch	400	The logo choice names a source other than the one the generation is being built from.	Choose a logo from the source this generation reads, or use the brand kit's own.
idempotency_key_required	400	A mutating operation arrived over HTTP with no `Idempotency-Key` header. It is refused before the body is parsed, so a caller missing both learns about both at once.	Add an `Idempotency-Key` header of up to 128 characters, unique to this request. Over MCP the same value goes in the `idempotencyKey` tool argument.
unsupported_duration	400	The design does not offer that length.	`details.durations` lists what it does offer. Pick one of those.
validation_failed	400	The merged path, query and body did not match the operation's schema. The schemas are strict, so an unknown field is a failure rather than something ignored, and a string carrying half of a character is refused before it can be stored.	Read `details.issues`. Each entry carries a `path`, a `message` and a machine readable `code`. Fix every named field and send the request again; the same body always fails the same way.
unauthorized	401	No credential was presented, or the key is unknown, revoked or expired, or an `X-API-Key` header carried something that is not an API key. `details.reason` says which.	Send `Authorization: Bearer gsk_live_…`. A revoked or expired key never starts working again, so issue a new one in the developer console. Put a dashboard session token in `Authorization`, never in `X-API-Key`.
insufficient_seconds	402	The account's seconds wallet does not hold enough time for the video that was asked for. It is the only refusal on this surface that is a 402.	`details.needed` and `details.available` are the two numbers. Buy more time, or ask for a shorter video. Retrying without changing either fails the same way.
forbidden_scope	403	The credential does not carry every scope the operation declares, or it is the wrong kind of credential for it. `keys.` and `assistant.` are user only and can never be called by a key.	`details.requiredScopes` and `details.missingScopes` name what is missing. A key's scopes cannot be changed after it is issued, so create a new key with them. When `details.allowedActors` is present, no key can call this operation at all.
generation_not_found	404	No generation of that id belongs to this account.	Check the id. A generation belonging to another account answers the same way.
not_found	404	No resource of that id belongs to this account. A resource that belongs to somebody else answers 404 as well, never 403.	Check the id. Do not treat this as a permissions problem.
project_not_found	404	No marketing project of that id belongs to this account.	Check the id. A project belonging to another account answers the same way.
source_not_found	404	No website source of that id belongs to this account.	Check the id. A source belonging to another account answers the same way.
source_version_not_found	404	No such version of that website source.	Read the source to see which versions exist, then name one of those.
brand_kit_required	409	The generation needs a brand kit and the account has never saved one.	Save one with `PUT /marketing/brand-kit` first. `name` and `accent` are the two required fields.
brand_logo_not_retained	409	The generation asked for a logo the account no longer holds, because retention took it.	Pick a different logo choice, or scan the source again so a logo is held.
conflict	409	The request conflicts with the state the resource is in, and no more specific code applies.	Re-read the resource and decide from its current state. Retrying the same request unchanged will not help.
generation_busy	409	Another generation is already running for this source. One at a time per account.	Poll the running one until its state is terminal, or cancel it, then start the new one.
generation_idempotency_conflict	409	That idempotency key was already used on this account with a different generation request.	Use a fresh key for a different request. One key stands for one intent.
generation_not_retryable	409	A retry was asked for on a failure that a retry cannot change, for example a design that cannot fit the words.	Read `retryable` on the generation before asking. When it is false, fix the request and start a new generation.
idempotency_conflict	409	That idempotency key has already been used on this operation with a different request body.	Use a fresh key for a different request. A key stands for one intent, not for one attempt.
idempotency_in_progress	409	The first request under that key is still being worked. Two concurrent identical requests both reach the store and one of them is told this.	Wait the `Retry-After` seconds, which is 2, and send exactly the same request again with the same key. Do not change the body and do not mint a new key.
source_kind_mismatch	409	The project was made from a different kind of source than the one being used, for example a walkthrough render where a scanned website is expected.	Use the source the project was built from, or start a new project of the right kind.
source_owner_unavailable	409	The account cannot start new work, because it is blocked or scheduled for deletion.	Resolve the account's state, then retry.
source_version_mismatch	409	The version named belongs to a different website source.	Send a version number from the source you are naming.
source_deleted	410	The website source has been deleted. It still reads `state: "cancelled"`.	Scan the site again with `marketing.sources.create`.
source_expired	410	The website source is past its retention window.	Scan the site again. Projects already built from it keep the version they were built from.
source_version_expired	410	That manifest version has been cleaned up.	Scan the site again and build from the new version.
payload_too_large	413	The request body is over the transport's limit: 256 kb over HTTP, 1 mb over MCP.	Send less. `details.limit` carries the limit. Version 1 has no upload operations, so a body this size is usually a mistake.
unsupported_media_type	415	The request carried a body whose `Content-Type` is not `application/json`, whose charset is not utf-8, or whose `Content-Encoding` this API does not decode. A body nobody can read would otherwise be silently discarded.	Send `Content-Type: application/json` and utf-8 bytes. `details` names the charset, encoding or content type that was objected to.
campaign_copy_overflow	422	Words sent for a marketing scene do not fit the frame the design draws them in. The fit is measured, not guessed.	Shorten the fields `details.fields` names, then send the revision again. `marketing.generations.preflight` answers the same refusal before anything is created.
campaign_logo_aspect_unsupported	422	The logo's aspect ratio is not one any design can place.	Supply a logo closer to square or to a standard wordmark shape.
campaign_unsupported_claim	422	A statement sent for the film is not supported by anything the scanned website says.	Reword the claim so it repeats something the source actually says, or drop it.
campaign_visuals_insufficient	422	The design needs more pictures than the scanned source has.	`details` says how many are needed and which scenes are short. Scan a richer page, refresh the source, or choose a design with fewer picture slots.
invalid_campaign_narration	422	The narration request for a marketing film is not a valid shape.	Send narration as the operation's schema declares it, or omit it and let the design's default stand.
rate_limited	429	The credential's per minute budget, the account's per minute ceiling, or a daily cap was exceeded. `details.scope` is `minute`, `day` or `account`, or `global` when the product's own daily cap on voice previews is spent.	Wait the `Retry-After` seconds and retry. `details.limit` and `details.resetAt` say what was hit and when it reopens. The `RateLimit-*` headers on every answer let a client pace itself before it gets here.
internal_error	500	An unhandled failure inside this API. The original message is logged and never answered.	Retry once, then quote `requestId` to support. A 5xx deletes the idempotency claim rather than storing it, so retrying under the same key is safe.