{"openapi":"3.1.0","info":{"title":"Market4Me API","version":"1.0.0","summary":"Generate on-brand marketing video, images, voice and copy.","description":"Market4Me turns a business into marketing assets. Point it at a website, it builds a structured\nunderstanding of the brand (tone, audience, products, USP, content pillars), and every generation\nafter that is on-brand automatically — you do not re-describe the brand in each prompt.\n\n## Getting started\n1. `GET /me` — confirms the key works and tells you the plan, credit balance and available brands.\n2. `POST /videos` with `{ \"prompt\": \"...\" }` — the simplest useful call; returns a finished video URL.\n3. `POST /estimate` — price ANY operation before running it. Always cheaper than finding out via a 402.\n\n## Sync vs async\nShort generations (video clips, images, speech, avatars) answer synchronously with the asset URL.\nLong ones (`/brand-videos`, `/films`) answer `202` with a job; poll `GET /jobs/{id}`, or call\n`POST /jobs/{id}/wait` to block until it finishes, or register a webhook and be told.\n\nIf a synchronous render outlives the request window you get `202` with `status: \"processing\"` —\nthat is NOT a failure and the credits are NOT refunded. Do not resubmit; the asset lands in\n`GET /assets`.\n\n## Credits and safety\nEvery generation costs credits, deducted up front and **refunded automatically if it fails**.\nSend an `Idempotency-Key` header on any POST so a network retry cannot charge twice.","contact":{"name":"Market4Me Support","url":"https://market4me.ai"}},"servers":[{"url":"http://localhost:3501/api/v1","description":"Production"}],"security":[{"BearerAuth":[]},{"ApiKeyHeader":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Send your key as `Authorization: Bearer m4m_live_...`. Create keys in the dashboard under Developer."},"ApiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Alternative to the Bearer header, for clients that only support an API-key header."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}},"Job":{"type":"object","description":"A unified async job. Every long-running operation in the API returns this exact shape, whichever engine is doing the work.","properties":{"id":{"type":"string","example":"job_9f2c1a..."},"object":{"type":"string","const":"job"},"kind":{"type":"string","description":"brand_video | film | generation | studio | director_run"},"status":{"type":"string","enum":["queued","running","succeeded","failed","cancelled"],"description":"queued and running are non-terminal; the other three are final."},"progress":{"type":"integer","minimum":0,"maximum":100},"credits":{"type":"integer","description":"Credits charged for this job."},"output":{"type":["object","null"],"description":"Present once status is succeeded. `url` is the finished asset.","properties":{"type":{"type":"string","example":"video"},"url":{"type":"string","description":"Stable, shareable URL for the finished asset."},"download_url":{"type":"string","description":"Time-limited direct download (24h)."},"thumbnail_url":{"type":["string","null"]}}},"error":{"type":["string","null"],"description":"Why it failed. Credits are refunded automatically on failure."},"metadata":{"type":"object","description":"Whatever you passed as `metadata` at creation, echoed back."},"poll_url":{"type":"string"},"is_terminal":{"type":"boolean","description":"True when no further polling is needed."},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"}}},"Brand":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"brand"},"name":{"type":"string"},"website_url":{"type":["string","null"]},"niche":{"type":["string","null"]},"description":{"type":["string","null"]},"analysis_status":{"type":"string","enum":["pending","running","complete","failed"],"description":"Some generation endpoints require this to be \"complete\". Poll GET /v1/brands/{id} after starting an analysis."},"analysed_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}}}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"A unique string per logical operation. Replaying it returns the original response instead of charging again. Strongly recommended on every POST."}}},"x-scopes":{"brands:read":"Read brands and their brand intelligence","brands:write":"Create and update brands, trigger analysis","generate:video":"Generate video (charges credits)","generate:image":"Generate and edit images (charges credits)","generate:audio":"Generate voiceover and clone voices (charges credits)","generate:content":"Generate scripts, captions, carousels, strategy","jobs:read":"Read job status and results","assets:read":"List generated assets and available models","assets:write":"Mint upload URLs to put your own media into the account","credits:read":"Read credit balance, pricing and usage","analytics:read":"Read performance analytics","webhooks:read":"List webhook endpoints and their delivery health","webhooks:write":"Create and delete webhook endpoints"},"x-webhook-events":{"job.running":"A job started processing","job.succeeded":"A job finished successfully and its output is ready","job.failed":"A job failed (credits are refunded automatically)","brand.analysis.completed":"Brand analysis finished and brand intelligence is available"},"paths":{"/me":{"get":{"operationId":"getAccount","summary":"Who am I — account, plan, credit balance, brands, key scopes","description":"Call this FIRST. It verifies the key and returns everything needed to plan work: credit balance, subscription plan, which brands exist (with their analysis status), what this key is allowed to do, and which endpoints are gated behind a subscription.","tags":["Account"],"responses":{"200":{"description":"Account context."},"400":{"description":"Invalid request — a parameter is missing or malformed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"401":{"description":"Missing, malformed, revoked or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"402":{"description":"Not enough credits, or the endpoint needs a subscription. `error.code` distinguishes insufficient_credits from subscription_required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"403":{"description":"The API key lacks the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"404":{"description":"Not found (or not visible to this key).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"429":{"description":"Rate limit exceeded. Respect the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}}}}},"/credits":{"get":{"operationId":"getCredits","summary":"Credit balance and recent transactions","tags":["Account"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"Balance and ledger."},"400":{"description":"Invalid request — a parameter is missing or malformed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"401":{"description":"Missing, malformed, revoked or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"402":{"description":"Not enough credits, or the endpoint needs a subscription. `error.code` distinguishes insufficient_credits from subscription_required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"403":{"description":"The API key lacks the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"404":{"description":"Not found (or not visible to this key).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"429":{"description":"Rate limit exceeded. Respect the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}}}}},"/estimate":{"post":{"operationId":"estimateCost","summary":"Price an operation without running it","description":"Returns the exact credit cost of an operation and whether the account can afford it. Use this before any generation you have not priced before, and to compare options (a 1080p 10s clip vs a 720p 5s one) without spending anything. Free.","tags":["Account"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"operation":{"type":"string","enum":["video","image","speech","avatar","motion_sync","ugc","brand_video","content"]},"duration_s":{"type":"number"},"quality":{"type":"string"},"model":{"type":"string"},"mode":{"type":"string"},"text":{"type":"string","description":"For operation=speech — cost scales with length."},"operations":{"type":"array","description":"Price several at once and get a total. Use this to budget a whole campaign in one call.","items":{"type":"object"}}}}}}},"responses":{"200":{"description":"Priced operations and total."},"400":{"description":"Invalid request — a parameter is missing or malformed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"401":{"description":"Missing, malformed, revoked or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"402":{"description":"Not enough credits, or the endpoint needs a subscription. `error.code` distinguishes insufficient_credits from subscription_required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"403":{"description":"The API key lacks the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"404":{"description":"Not found (or not visible to this key).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"429":{"description":"Rate limit exceeded. Respect the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}}}}},"/usage":{"get":{"operationId":"getUsage","summary":"API usage and spend, grouped by endpoint","tags":["Account"],"parameters":[{"name":"days","in":"query","schema":{"type":"integer","default":7,"maximum":90}}],"responses":{"200":{"description":"Usage summary."},"400":{"description":"Invalid request — a parameter is missing or malformed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"401":{"description":"Missing, malformed, revoked or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"402":{"description":"Not enough credits, or the endpoint needs a subscription. `error.code` distinguishes insufficient_credits from subscription_required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"403":{"description":"The API key lacks the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"404":{"description":"Not found (or not visible to this key).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"429":{"description":"Rate limit exceeded. Respect the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}}}}},"/brands":{"get":{"operationId":"listBrands","summary":"List brands","tags":["Brands"],"responses":{"200":{"description":"Brands."},"400":{"description":"Invalid request — a parameter is missing or malformed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"401":{"description":"Missing, malformed, revoked or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"402":{"description":"Not enough credits, or the endpoint needs a subscription. `error.code` distinguishes insufficient_credits from subscription_required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"403":{"description":"The API key lacks the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"404":{"description":"Not found (or not visible to this key).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"429":{"description":"Rate limit exceeded. Respect the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}}}},"post":{"operationId":"createBrand","summary":"Create a brand (and analyse its website)","description":"Creates a brand. If `website_url` is given, brand analysis starts immediately — it crawls the site and builds the brand brain that makes later generations on-brand. Analysis takes 30–90s; poll GET /v1/brands/{id} until analysis_status is \"complete\".","tags":["Brands"],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":120},"website_url":{"type":"string","description":"Strongly recommended — this is what makes generations on-brand."},"niche":{"type":"string"},"description":{"type":"string"}}}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"brand"},"name":{"type":"string"},"website_url":{"type":["string","null"]},"niche":{"type":["string","null"]},"description":{"type":["string","null"]},"analysis_status":{"type":"string","enum":["pending","running","complete","failed"],"description":"Some generation endpoints require this to be \"complete\". Poll GET /v1/brands/{id} after starting an analysis."},"analysed_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Invalid request — a parameter is missing or malformed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"401":{"description":"Missing, malformed, revoked or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"402":{"description":"Not enough credits, or the endpoint needs a subscription. `error.code` distinguishes insufficient_credits from subscription_required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"403":{"description":"The API key lacks the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"404":{"description":"Not found (or not visible to this key).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"429":{"description":"Rate limit exceeded. Respect the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}}}}},"/brands/{brand_id}":{"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getBrand","summary":"Get one brand","tags":["Brands"],"responses":{"200":{"description":"Brand.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"brand"},"name":{"type":"string"},"website_url":{"type":["string","null"]},"niche":{"type":["string","null"]},"description":{"type":["string","null"]},"analysis_status":{"type":"string","enum":["pending","running","complete","failed"],"description":"Some generation endpoints require this to be \"complete\". Poll GET /v1/brands/{id} after starting an analysis."},"analysed_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Invalid request — a parameter is missing or malformed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"401":{"description":"Missing, malformed, revoked or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"402":{"description":"Not enough credits, or the endpoint needs a subscription. `error.code` distinguishes insufficient_credits from subscription_required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"403":{"description":"The API key lacks the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"404":{"description":"Not found (or not visible to this key).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"429":{"description":"Rate limit exceeded. Respect the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}}}},"patch":{"operationId":"updateBrand","summary":"Update a brand","tags":["Brands"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"website_url":{"type":"string"},"niche":{"type":"string"},"description":{"type":"string"},"tone_guidelines":{"type":"string"},"target_audience":{"type":"string"},"products_services":{"type":"string"}}}}}},"responses":{"200":{"description":"Updated."},"400":{"description":"Invalid request — a parameter is missing or malformed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"401":{"description":"Missing, malformed, revoked or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"402":{"description":"Not enough credits, or the endpoint needs a subscription. `error.code` distinguishes insufficient_credits from subscription_required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"403":{"description":"The API key lacks the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"404":{"description":"Not found (or not visible to this key).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"429":{"description":"Rate limit exceeded. Respect the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}}}}},"/brands/{brand_id}/analyze":{"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"analyzeBrand","summary":"Re-run brand analysis","description":"Re-crawls the brand website and rebuilds the brand brain. Use after the site changes, or if analysis_status is \"failed\". Runs in the background — poll GET /v1/brands/{id}.","tags":["Brands"],"responses":{"200":{"description":"Analysis started."},"400":{"description":"Invalid request — a parameter is missing or malformed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"401":{"description":"Missing, malformed, revoked or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"402":{"description":"Not enough credits, or the endpoint needs a subscription. `error.code` distinguishes insufficient_credits from subscription_required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"403":{"description":"The API key lacks the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"404":{"description":"Not found (or not visible to this key).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"429":{"description":"Rate limit exceeded. Respect the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}}}}},"/brands/{brand_id}/intelligence":{"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getBrandIntelligence","summary":"Read the brand brain","description":"The structured understanding of the business: tone of voice, audience, products, USP, brand story, key messages, content pillars and themes. Useful when you want to reason about the brand yourself (writing copy, planning a campaign) rather than relying on automatic grounding.","tags":["Brands"],"responses":{"200":{"description":"Brand intelligence."},"400":{"description":"Invalid request — a parameter is missing or malformed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"401":{"description":"Missing, malformed, revoked or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"402":{"description":"Not enough credits, or the endpoint needs a subscription. `error.code` distinguishes insufficient_credits from subscription_required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"403":{"description":"The API key lacks the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"404":{"description":"Not found (or not visible to this key).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"429":{"description":"Rate limit exceeded. Respect the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}}}}},"/videos":{"post":{"operationId":"createVideo","summary":"Generate a video from a text prompt","description":"The simplest useful call in the API. Returns the finished video URL synchronously — no polling. Automatically grounded in the brand (set use_brand:false to opt out). For a multi-scene narrated film use POST /films; for the full brand pipeline with scripted voiceover and captions use POST /brand-videos.","tags":["Generation"],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string","maxLength":2400,"description":"What should happen on screen. Describe the shot, not the marketing goal."},"brand_id":{"type":"string","description":"Omit to use the default workspace brand."},"duration_s":{"type":"number","default":5,"minimum":1,"maximum":60,"description":"Cost scales with this."},"aspect_ratio":{"type":"string","enum":["9:16","16:9","1:1","4:5","3:4","4:3"],"default":"9:16"},"quality":{"type":"string","enum":["480p","720p","1080p","4k"],"default":"1080p"},"model":{"type":"string","enum":["economy","fast","standard","premium","ultra","max"],"description":"Quality/price tier. Omit for the default. GET /models lists them with prices."},"image_url":{"type":"string","description":"Animate this image instead of generating from scratch."},"image_urls":{"type":"array","items":{"type":"string"},"description":"Up to 9 reference images."},"use_brand":{"type":"boolean","default":true},"metadata":{"type":"object"}}}}}},"responses":{"200":{"description":"Finished video."},"202":{"description":"Still rendering — collect from GET /assets. Credits charged; not a failure."},"400":{"description":"Invalid request — a parameter is missing or malformed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"401":{"description":"Missing, malformed, revoked or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"402":{"description":"Not enough credits, or the endpoint needs a subscription. `error.code` distinguishes insufficient_credits from subscription_required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"403":{"description":"The API key lacks the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"404":{"description":"Not found (or not visible to this key).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"429":{"description":"Rate limit exceeded. Respect the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}}}}},"/images":{"post":{"operationId":"createImage","summary":"Generate, edit or face-swap an image","description":"Synchronous. mode=generate makes a new image from a prompt; mode=edit changes an existing one (needs image_url); mode=face-swap places a face into a scene (needs image_url and face_image_url). Output URLs can be fed straight into POST /videos as image_url.","tags":["Generation"],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","maxLength":2400},"mode":{"type":"string","enum":["generate","edit","face-swap"],"default":"generate"},"brand_id":{"type":"string"},"image_url":{"type":"string"},"face_image_url":{"type":"string"},"quality":{"type":"string","enum":["low","medium","high"],"default":"high"},"model":{"type":"string","enum":["economy","standard","premium"],"description":"Quality/price tier. Omit for the default."},"size":{"type":"string","default":"1024x1024"},"use_brand":{"type":"boolean","default":true}}}}}},"responses":{"200":{"description":"Finished image."},"400":{"description":"Invalid request — a parameter is missing or malformed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"401":{"description":"Missing, malformed, revoked or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"402":{"description":"Not enough credits, or the endpoint needs a subscription. `error.code` distinguishes insufficient_credits from subscription_required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"403":{"description":"The API key lacks the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"404":{"description":"Not found (or not visible to this key).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"429":{"description":"Rate limit exceeded. Respect the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}}}}},"/speech":{"post":{"operationId":"createSpeech","summary":"Text to speech","description":"Generates a voiceover audio file. Cost scales with character count. The returned URL can be passed to POST /avatars as audio_url.","tags":["Generation"],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string","maxLength":20000},"voice":{"type":"string","description":"Voice id. Omit for the brand default."},"brand_id":{"type":"string"}}}}}},"responses":{"200":{"description":"Audio file."},"400":{"description":"Invalid request — a parameter is missing or malformed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"401":{"description":"Missing, malformed, revoked or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"402":{"description":"Not enough credits, or the endpoint needs a subscription. `error.code` distinguishes insufficient_credits from subscription_required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"403":{"description":"The API key lacks the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"404":{"description":"Not found (or not visible to this key).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"429":{"description":"Rate limit exceeded. Respect the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}}}}},"/avatars":{"post":{"operationId":"createAvatar","summary":"Make a portrait speak (talking head / spokesperson)","description":"Takes a portrait image plus words and returns a video of that person saying them, lip-synced. Give either `text` (we generate the voice) or `audio_url` (your own track).","tags":["Generation"],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["image_url"],"properties":{"image_url":{"type":"string","description":"Portrait of the person who should speak."},"text":{"type":"string"},"audio_url":{"type":"string"},"voice":{"type":"string"},"resolution":{"type":"string","enum":["480p","720p","1080p"],"default":"720p"},"brand_id":{"type":"string"}}}}}},"responses":{"200":{"description":"Finished video."},"400":{"description":"Invalid request — a parameter is missing or malformed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"401":{"description":"Missing, malformed, revoked or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"402":{"description":"Not enough credits, or the endpoint needs a subscription. `error.code` distinguishes insufficient_credits from subscription_required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"403":{"description":"The API key lacks the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"404":{"description":"Not found (or not visible to this key).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"429":{"description":"Rate limit exceeded. Respect the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}}}}},"/content":{"post":{"operationId":"createContent","summary":"Write a script, carousel or caption","description":"Brand-grounded copy. content_type short_video/reel/tiktok returns a script with hooks; carousel returns slides; caption returns a post caption with hashtags. Cheap and fast — use it to draft before spending credits on a render.","tags":["Generation"],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["content_type"],"properties":{"content_type":{"type":"string","enum":["short_video","reel","tiktok","carousel","caption"]},"topic":{"type":"string"},"platforms":{"type":"array","items":{"type":"string"}},"custom_instructions":{"type":"string"},"slides_count":{"type":"integer","minimum":2,"maximum":20},"brand_id":{"type":"string"}}}}}},"responses":{"201":{"description":"Generated copy."},"400":{"description":"Invalid request — a parameter is missing or malformed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"401":{"description":"Missing, malformed, revoked or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"402":{"description":"Not enough credits, or the endpoint needs a subscription. `error.code` distinguishes insufficient_credits from subscription_required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"403":{"description":"The API key lacks the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"404":{"description":"Not found (or not visible to this key).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"429":{"description":"Rate limit exceeded. Respect the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}}}}},"/brand-videos":{"post":{"operationId":"createBrandVideo","summary":"Full brand video pipeline (script → scenes → voiceover → captions)","description":"The complete marketing-video pipeline, not a single clip. Give a `topic` and it writes the script itself. ASYNCHRONOUS: returns a job — poll GET /jobs/{id} or call POST /jobs/{id}/wait. Requires the brand to have been analysed.","tags":["Generation"],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"topic":{"type":"string","description":"What the video is about. We write the script."},"script":{"type":"string","description":"Your own script, instead of a topic."},"brand_id":{"type":"string"},"duration_s":{"type":"number","default":15},"platform":{"type":"string","enum":["tiktok","instagram","youtube","linkedin","facebook"],"default":"tiktok"},"aspect_ratio":{"type":"string","default":"9:16"},"metadata":{"type":"object"}}}}}},"responses":{"202":{"description":"Job created.","content":{"application/json":{"schema":{"type":"object","description":"A unified async job. Every long-running operation in the API returns this exact shape, whichever engine is doing the work.","properties":{"id":{"type":"string","example":"job_9f2c1a..."},"object":{"type":"string","const":"job"},"kind":{"type":"string","description":"brand_video | film | generation | studio | director_run"},"status":{"type":"string","enum":["queued","running","succeeded","failed","cancelled"],"description":"queued and running are non-terminal; the other three are final."},"progress":{"type":"integer","minimum":0,"maximum":100},"credits":{"type":"integer","description":"Credits charged for this job."},"output":{"type":["object","null"],"description":"Present once status is succeeded. `url` is the finished asset.","properties":{"type":{"type":"string","example":"video"},"url":{"type":"string","description":"Stable, shareable URL for the finished asset."},"download_url":{"type":"string","description":"Time-limited direct download (24h)."},"thumbnail_url":{"type":["string","null"]}}},"error":{"type":["string","null"],"description":"Why it failed. Credits are refunded automatically on failure."},"metadata":{"type":"object","description":"Whatever you passed as `metadata` at creation, echoed back."},"poll_url":{"type":"string"},"is_terminal":{"type":"boolean","description":"True when no further polling is needed."},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"Invalid request — a parameter is missing or malformed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"401":{"description":"Missing, malformed, revoked or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"402":{"description":"Not enough credits, or the endpoint needs a subscription. `error.code` distinguishes insufficient_credits from subscription_required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"403":{"description":"The API key lacks the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"404":{"description":"Not found (or not visible to this key).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"429":{"description":"Rate limit exceeded. Respect the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}}}}},"/films":{"post":{"operationId":"createFilm","summary":"One idea → a multi-scene narrated film","description":"The most capable generation in the product: an idea becomes a storyboarded, multi-scene, narrated film. ASYNCHRONOUS — returns a job. REQUIRES AN ACTIVE SUBSCRIPTION; buying credits does not unlock it, so a 402 with code subscription_required cannot be fixed by topping up.","tags":["Generation"],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["idea"],"properties":{"idea":{"type":"string","maxLength":4000},"duration_s":{"type":"number","default":60,"minimum":10,"maximum":300},"aspect_ratio":{"type":"string","default":"9:16"},"style":{"type":"string","enum":["cinematic","cartoon"],"default":"cinematic"},"voiceover":{"type":"boolean","default":true},"brand_id":{"type":"string"}}}}}},"responses":{"202":{"description":"Job created.","content":{"application/json":{"schema":{"type":"object","description":"A unified async job. Every long-running operation in the API returns this exact shape, whichever engine is doing the work.","properties":{"id":{"type":"string","example":"job_9f2c1a..."},"object":{"type":"string","const":"job"},"kind":{"type":"string","description":"brand_video | film | generation | studio | director_run"},"status":{"type":"string","enum":["queued","running","succeeded","failed","cancelled"],"description":"queued and running are non-terminal; the other three are final."},"progress":{"type":"integer","minimum":0,"maximum":100},"credits":{"type":"integer","description":"Credits charged for this job."},"output":{"type":["object","null"],"description":"Present once status is succeeded. `url` is the finished asset.","properties":{"type":{"type":"string","example":"video"},"url":{"type":"string","description":"Stable, shareable URL for the finished asset."},"download_url":{"type":"string","description":"Time-limited direct download (24h)."},"thumbnail_url":{"type":["string","null"]}}},"error":{"type":["string","null"],"description":"Why it failed. Credits are refunded automatically on failure."},"metadata":{"type":"object","description":"Whatever you passed as `metadata` at creation, echoed back."},"poll_url":{"type":"string"},"is_terminal":{"type":"boolean","description":"True when no further polling is needed."},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"Invalid request — a parameter is missing or malformed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"401":{"description":"Missing, malformed, revoked or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"402":{"description":"Not enough credits, or the endpoint needs a subscription. `error.code` distinguishes insufficient_credits from subscription_required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"403":{"description":"The API key lacks the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"404":{"description":"Not found (or not visible to this key).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"429":{"description":"Rate limit exceeded. Respect the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}}}}},"/ugc/script":{"post":{"operationId":"createUgcScript","summary":"Draft a UGC ad script (free)","description":"Writes a multi-scene creator-style ad script. FREE — no credits. Iterate here with the user, then pass the scenes to POST /ugc to render.","tags":["Generation"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"product":{"type":"string"},"angle":{"type":"string"},"ugc_type":{"type":"string","enum":["testimonial","unboxing","demo","review","story"],"default":"testimonial"},"duration_s":{"type":"number","default":30},"brand_id":{"type":"string"}}}}}},"responses":{"200":{"description":"Scene-by-scene script."},"400":{"description":"Invalid request — a parameter is missing or malformed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"401":{"description":"Missing, malformed, revoked or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"402":{"description":"Not enough credits, or the endpoint needs a subscription. `error.code` distinguishes insufficient_credits from subscription_required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"403":{"description":"The API key lacks the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"404":{"description":"Not found (or not visible to this key).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"429":{"description":"Rate limit exceeded. Respect the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}}}}},"/ugc":{"post":{"operationId":"createUgc","summary":"Render a UGC ad from a scene script","tags":["Generation"],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["scenes"],"properties":{"scenes":{"type":"array","maxItems":10,"items":{"type":"object","properties":{"spoken":{"type":"string"},"action":{"type":"string"},"duration_s":{"type":"number"}}}},"image_url":{"type":"string","description":"The creator/actor portrait."},"quality":{"type":"string","enum":["480p","720p","1080p"],"default":"720p"},"brand_id":{"type":"string"}}}}}},"responses":{"200":{"description":"Finished video."},"400":{"description":"Invalid request — a parameter is missing or malformed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"401":{"description":"Missing, malformed, revoked or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"402":{"description":"Not enough credits, or the endpoint needs a subscription. `error.code` distinguishes insufficient_credits from subscription_required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"403":{"description":"The API key lacks the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"404":{"description":"Not found (or not visible to this key).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"429":{"description":"Rate limit exceeded. Respect the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}}}}},"/transcriptions":{"post":{"operationId":"createTranscription","summary":"Transcribe a video, or burn subtitles into it","tags":["Generation"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["video_url"],"properties":{"video_url":{"type":"string"},"mode":{"type":"string","enum":["transcript","subtitles"],"default":"transcript"},"brand_id":{"type":"string"}}}}}},"responses":{"200":{"description":"Transcript or subtitled video."},"400":{"description":"Invalid request — a parameter is missing or malformed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"401":{"description":"Missing, malformed, revoked or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"402":{"description":"Not enough credits, or the endpoint needs a subscription. `error.code` distinguishes insufficient_credits from subscription_required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"403":{"description":"The API key lacks the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"404":{"description":"Not found (or not visible to this key).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"429":{"description":"Rate limit exceeded. Respect the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}}}}},"/jobs":{"get":{"operationId":"listJobs","summary":"List jobs","tags":["Jobs"],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["queued","running","succeeded","failed","cancelled"]}},{"name":"kind","in":"query","schema":{"type":"string"}},{"name":"brand_id","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"Jobs."},"400":{"description":"Invalid request — a parameter is missing or malformed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"401":{"description":"Missing, malformed, revoked or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"402":{"description":"Not enough credits, or the endpoint needs a subscription. `error.code` distinguishes insufficient_credits from subscription_required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"403":{"description":"The API key lacks the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"404":{"description":"Not found (or not visible to this key).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"429":{"description":"Rate limit exceeded. Respect the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}}}}},"/jobs/{job_id}":{"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"},"description":"A job_... id, or the raw UUID of a job started elsewhere."}],"get":{"operationId":"getJob","summary":"Get job status and result","description":"Poll until is_terminal is true. On success, `output.url` is the finished asset. Prefer POST /jobs/{id}/wait, which blocks instead of making you poll.","tags":["Jobs"],"responses":{"200":{"description":"Job.","content":{"application/json":{"schema":{"type":"object","description":"A unified async job. Every long-running operation in the API returns this exact shape, whichever engine is doing the work.","properties":{"id":{"type":"string","example":"job_9f2c1a..."},"object":{"type":"string","const":"job"},"kind":{"type":"string","description":"brand_video | film | generation | studio | director_run"},"status":{"type":"string","enum":["queued","running","succeeded","failed","cancelled"],"description":"queued and running are non-terminal; the other three are final."},"progress":{"type":"integer","minimum":0,"maximum":100},"credits":{"type":"integer","description":"Credits charged for this job."},"output":{"type":["object","null"],"description":"Present once status is succeeded. `url` is the finished asset.","properties":{"type":{"type":"string","example":"video"},"url":{"type":"string","description":"Stable, shareable URL for the finished asset."},"download_url":{"type":"string","description":"Time-limited direct download (24h)."},"thumbnail_url":{"type":["string","null"]}}},"error":{"type":["string","null"],"description":"Why it failed. Credits are refunded automatically on failure."},"metadata":{"type":"object","description":"Whatever you passed as `metadata` at creation, echoed back."},"poll_url":{"type":"string"},"is_terminal":{"type":"boolean","description":"True when no further polling is needed."},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"Invalid request — a parameter is missing or malformed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"401":{"description":"Missing, malformed, revoked or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"402":{"description":"Not enough credits, or the endpoint needs a subscription. `error.code` distinguishes insufficient_credits from subscription_required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"403":{"description":"The API key lacks the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"404":{"description":"Not found (or not visible to this key).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"429":{"description":"Rate limit exceeded. Respect the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}}}}},"/jobs/{job_id}/wait":{"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"operationId":"waitForJob","summary":"Block until a job finishes","description":"Long-polls, up to timeout_s (default 60, max 300). Returns as soon as the job is terminal. If it is still running when the timeout hits you get 200 with timed_out:true — call again to keep waiting. This is the preferred way to await a job: no polling loop, no wasted turns.","tags":["Jobs"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"timeout_s":{"type":"integer","default":60,"maximum":300}}}}}},"responses":{"200":{"description":"Job, terminal or timed out.","content":{"application/json":{"schema":{"type":"object","description":"A unified async job. Every long-running operation in the API returns this exact shape, whichever engine is doing the work.","properties":{"id":{"type":"string","example":"job_9f2c1a..."},"object":{"type":"string","const":"job"},"kind":{"type":"string","description":"brand_video | film | generation | studio | director_run"},"status":{"type":"string","enum":["queued","running","succeeded","failed","cancelled"],"description":"queued and running are non-terminal; the other three are final."},"progress":{"type":"integer","minimum":0,"maximum":100},"credits":{"type":"integer","description":"Credits charged for this job."},"output":{"type":["object","null"],"description":"Present once status is succeeded. `url` is the finished asset.","properties":{"type":{"type":"string","example":"video"},"url":{"type":"string","description":"Stable, shareable URL for the finished asset."},"download_url":{"type":"string","description":"Time-limited direct download (24h)."},"thumbnail_url":{"type":["string","null"]}}},"error":{"type":["string","null"],"description":"Why it failed. Credits are refunded automatically on failure."},"metadata":{"type":"object","description":"Whatever you passed as `metadata` at creation, echoed back."},"poll_url":{"type":"string"},"is_terminal":{"type":"boolean","description":"True when no further polling is needed."},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"Invalid request — a parameter is missing or malformed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"401":{"description":"Missing, malformed, revoked or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"402":{"description":"Not enough credits, or the endpoint needs a subscription. `error.code` distinguishes insufficient_credits from subscription_required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"403":{"description":"The API key lacks the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"404":{"description":"Not found (or not visible to this key).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"429":{"description":"Rate limit exceeded. Respect the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}}}}},"/assets":{"get":{"operationId":"listAssets","summary":"List generated assets","description":"Everything this account has produced. This is where a render that outlived its request window turns up.","tags":["Assets"],"parameters":[{"name":"kind","in":"query","schema":{"type":"string","enum":["video","image","audio"]}},{"name":"brand_id","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":25,"maximum":100}}],"responses":{"200":{"description":"Assets."},"400":{"description":"Invalid request — a parameter is missing or malformed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"401":{"description":"Missing, malformed, revoked or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"402":{"description":"Not enough credits, or the endpoint needs a subscription. `error.code` distinguishes insufficient_credits from subscription_required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"403":{"description":"The API key lacks the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"404":{"description":"Not found (or not visible to this key).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"429":{"description":"Rate limit exceeded. Respect the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}}}}},"/uploads":{"post":{"operationId":"createUpload","summary":"Get a presigned URL to upload your own media","description":"Two steps: call this, then PUT the bytes to `upload_url` with the same Content-Type. Pass the returned `asset_url` to any endpoint that takes image_url / video_url / audio_url. This is how you bring a product photo or an existing clip into a generation.","tags":["Assets"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["filename","content_type"],"properties":{"filename":{"type":"string"},"content_type":{"type":"string","example":"image/png"},"brand_id":{"type":"string"}}}}}},"responses":{"200":{"description":"Presigned upload."},"400":{"description":"Invalid request — a parameter is missing or malformed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"401":{"description":"Missing, malformed, revoked or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"402":{"description":"Not enough credits, or the endpoint needs a subscription. `error.code` distinguishes insufficient_credits from subscription_required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"403":{"description":"The API key lacks the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"404":{"description":"Not found (or not visible to this key).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"429":{"description":"Rate limit exceeded. Respect the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}}}}},"/models":{"get":{"operationId":"listModels","summary":"List available generation models","tags":["Assets"],"responses":{"200":{"description":"Models."},"400":{"description":"Invalid request — a parameter is missing or malformed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"401":{"description":"Missing, malformed, revoked or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"402":{"description":"Not enough credits, or the endpoint needs a subscription. `error.code` distinguishes insufficient_credits from subscription_required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"403":{"description":"The API key lacks the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"404":{"description":"Not found (or not visible to this key).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"429":{"description":"Rate limit exceeded. Respect the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}}}}},"/webhooks":{"get":{"operationId":"listWebhooks","summary":"List webhook endpoints","tags":["Webhooks"],"responses":{"200":{"description":"Webhooks."},"400":{"description":"Invalid request — a parameter is missing or malformed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"401":{"description":"Missing, malformed, revoked or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"402":{"description":"Not enough credits, or the endpoint needs a subscription. `error.code` distinguishes insufficient_credits from subscription_required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"403":{"description":"The API key lacks the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"404":{"description":"Not found (or not visible to this key).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"429":{"description":"Rate limit exceeded. Respect the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}}}},"post":{"operationId":"createWebhook","summary":"Register a webhook endpoint","description":"Be told when a job finishes instead of polling. The signing secret is returned ONCE — store it. Each delivery carries `M4M-Signature: t=<unix>,v1=<hmac-sha256 of \"t.body\">`.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"https required (http allowed for localhost)."},"events":{"type":"array","items":{"type":"string","enum":["job.running","job.succeeded","job.failed","brand.analysis.completed"]},"description":"Omit for all events."},"description":{"type":"string"}}}}}},"responses":{"201":{"description":"Created — includes the secret."},"400":{"description":"Invalid request — a parameter is missing or malformed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"401":{"description":"Missing, malformed, revoked or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"402":{"description":"Not enough credits, or the endpoint needs a subscription. `error.code` distinguishes insufficient_credits from subscription_required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"403":{"description":"The API key lacks the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"404":{"description":"Not found (or not visible to this key).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"429":{"description":"Rate limit exceeded. Respect the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}}}}},"/webhooks/{webhook_id}":{"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"delete":{"operationId":"deleteWebhook","summary":"Delete a webhook endpoint","tags":["Webhooks"],"responses":{"200":{"description":"Deleted."},"400":{"description":"Invalid request — a parameter is missing or malformed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"401":{"description":"Missing, malformed, revoked or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"402":{"description":"Not enough credits, or the endpoint needs a subscription. `error.code` distinguishes insufficient_credits from subscription_required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"403":{"description":"The API key lacks the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"404":{"description":"Not found (or not visible to this key).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"429":{"description":"Rate limit exceeded. Respect the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}}}}},"/webhooks/{webhook_id}/test":{"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"testWebhook","summary":"Send a test event to a webhook endpoint","description":"Verifies the endpoint is reachable and answers 2xx, without spending credits on a real render first.","tags":["Webhooks"],"responses":{"200":{"description":"Delivery result."},"400":{"description":"Invalid request — a parameter is missing or malformed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"401":{"description":"Missing, malformed, revoked or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"402":{"description":"Not enough credits, or the endpoint needs a subscription. `error.code` distinguishes insufficient_credits from subscription_required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"403":{"description":"The API key lacks the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"404":{"description":"Not found (or not visible to this key).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"429":{"description":"Rate limit exceeded. Respect the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}}}}},"/webhooks/events":{"get":{"operationId":"listWebhookEvents","summary":"List the event types you can subscribe to","tags":["Webhooks"],"responses":{"200":{"description":"Event types."},"400":{"description":"Invalid request — a parameter is missing or malformed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"401":{"description":"Missing, malformed, revoked or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"402":{"description":"Not enough credits, or the endpoint needs a subscription. `error.code` distinguishes insufficient_credits from subscription_required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"403":{"description":"The API key lacks the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"404":{"description":"Not found (or not visible to this key).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}},"429":{"description":"Rate limit exceeded. Respect the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Broad category, e.g. invalid_request_error, insufficient_credits_error."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on the message."},"message":{"type":"string","description":"Human- and model-readable explanation, written to be actionable."},"param":{"type":"string","description":"The offending parameter, when the error is about one."},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message"]}}}}}}}}}},"tags":[{"name":"Account","description":"Identity, credits, pricing and usage."},{"name":"Brands","description":"Brands and the brand brain that makes generations on-brand."},{"name":"Generation","description":"Making things: video, image, speech, avatars, copy."},{"name":"Jobs","description":"One envelope for every async operation."},{"name":"Assets","description":"Getting media in and out."},{"name":"Webhooks","description":"Be told when work finishes."}]}