Skip to main content
API docs by Redocly

NativeAds Headless API (1.0.0)

Download OpenAPI specification:Download

License: Commercial

The headless REST API for programmatic creative generation. Authenticate with a per-user API key (Authorization: Bearer nak_...). This reference lists only the endpoints an API key may call; generation endpoints are asynchronous (submit returns an id, then poll).

Assets

Initiate file upload

Get presigned URLs for secure direct-to-storage uploads

Authorizations:
BearerAuth
Request Body schema: application/json
required
brandId
required
string <uuid>
categoryId
string <uuid>
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "brandId": "0e9bcbb3-096e-49f9-aeea-7a13a201eff5",
  • "categoryId": "337f5e5d-288b-40d5-be14-901cc3acacc0",
  • "files": [
    ]
}

Response samples

Content type
application/json
{
  • "uploads": [
    ]
}

Confirm successful upload

Marks upload as complete and triggers asset processing

Authorizations:
BearerAuth
Request Body schema: application/json
required
uploadId
required
string <uuid>
categoryId
string <uuid>

Optional category ID to assign the asset to

Responses

Request samples

Content type
application/json
{
  • "uploadId": "ef523ba8-509e-47af-8e2c-5fa751596497",
  • "categoryId": "337f5e5d-288b-40d5-be14-901cc3acacc0"
}

Response samples

Content type
application/json
{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "brandId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  • "status": "uploading",
  • "url": "string",
  • "thumbnailUrl": "string",
  • "displayUrl": "string",
  • "metadata": {
    },
  • "tags": [
    ],
  • "autoGeneratedTags": [
    ],
  • "usedInCampaigns": [
    ],
  • "assetQualityTags": [
    ],
  • "qualityAssessment": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "version": 0
}

Cancel an in-progress upload

Cancels an upload and cleans up any temporary resources

Authorizations:
BearerAuth
path Parameters
uploadId
required
string <uuid>

Unique identifier of the upload to cancel

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Upload cancelled successfully"
}

Get asset details

Authorizations:
BearerAuth
path Parameters
assetId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "brandId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  • "status": "uploading",
  • "url": "string",
  • "thumbnailUrl": "string",
  • "displayUrl": "string",
  • "metadata": {
    },
  • "tags": [
    ],
  • "autoGeneratedTags": [
    ],
  • "usedInCampaigns": [
    ],
  • "assetQualityTags": [
    ],
  • "qualityAssessment": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "version": 0
}

List brand assets

Retrieve assets with filtering and pagination

Authorizations:
BearerAuth
path Parameters
brandId
required
string <uuid>
query Parameters
type
string
Enum: "image" "logo" "video" "document" "model" "mask" "text" "walmart_preview" "environment" "font"
status
string
Enum: "uploading" "uploaded" "processing" "complete" "failed" "canceled"
tags
Array of strings
campaignId
string <uuid>
page
integer
Default: 1
limit
integer <= 100
Default: 20
sort
string
Default: "-createdAt"
Enum: "createdAt" "-createdAt" "fileName" "-fileName"

Responses

Response samples

Content type
application/json
{
  • "categories": [
    ]
}

URL Asset Extraction

Start extracting assets from a page URL

Accepts a page URL and starts an asynchronous extraction. Returns immediately with an extraction id and status: pending; no candidates are present yet.

Poll GET /assets/extract-from-url/{extractionId} until status is completed or failed. A typical run takes one to five minutes, depending on how many related pages the site has. Internal ceilings bound it: a run still pending or processing after roughly 10 minutes has exhausted them and lands on failed.

Extraction consumes no plan or feature usage. The only volume guard is the per-organization cap described under 429.

Authorizations:
BearerAuth
Request Body schema: application/json
required
url
required
string <uri> <= 2048 characters

The page to scrape. Must be a public http(s) URL.

brandId
required
string <uuid>

Brand that scopes any assets committed from this extraction.

purpose
string or null <= 64 characters

Optional hint for what the results will be used for, which tunes how the ranker scores candidates and how many it keeps.

Recognised today:

  • scene_forge — biases toward clean, isolated, croppable product shots. Strictest keep threshold, and returns at most 10 kept candidates.
  • video — allows scenic and establishing shots. Loosest threshold, up to 40.
  • any — no lean, middling threshold, up to 40. This is also what an omitted, null, or blank value means.

Matching ignores case, hyphens and spaces, so Scene Forge and scene-forge both reach the scene_forge profile.

Anything else is free text, and is used rather than discarded: it keeps any's thresholds and limit, and the text itself is passed to the ranker as a description of intent, so it re-tunes the ordering. "Facebook ad creative for first-time buyers" is a valid purpose and ranks differently from no purpose at all. It is truncated at 300 characters. Nothing here is ever rejected, so callers do not break as the vocabulary grows.

media
string
Default: "both"
Enum: "images" "videos" "both"

What to pull off the page. both returns whatever is currently supported and is the right default for most callers.

Video extraction is not available yet: videos is rejected with 400 until it ships. Until then images and both behave identically — the ranker only ever reads <img> elements, so every candidate comes back with mediaType: image. The value is recorded on the extraction so the distinction becomes meaningful once video ships.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "extractionId": "5c4aa6dc-a49c-4bc5-890c-373387fe75fe",
  • "sourceUrl": "http://example.com",
  • "purpose": "string",
  • "media": "images",
  • "status": "pending",
  • "errorCode": "string",
  • "errorMessage": "string",
  • "truncated": 0,
  • "candidates": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z"
}

Read an extraction and its ranked candidates

Returns the extraction's current status. Once completed, candidates holds the ranked results, best first (rank 1 is the strongest match).

Only candidates the ranker kept are returned by default. Pass includeRejected=true to see everything it considered and why it rejected each one. Rejected candidates are staged on the first run, so asking for them costs no second extraction.

Fields are omitted rather than sent as null. A run that has not completed has no candidates key at all rather than an empty array, so read the response defensively.

Re-reading an extraction also mints fresh candidate preview URLs, which is how you recover from an expired one.

Authorizations:
BearerAuth
path Parameters
extractionId
required
string <uuid>

The extraction returned by the submit call.

query Parameters
includeRejected
boolean
Default: false

Include candidates the ranker rejected, for debugging or manual override.

Responses

Response samples

Content type
application/json
{
  • "extractionId": "5c4aa6dc-a49c-4bc5-890c-373387fe75fe",
  • "sourceUrl": "http://example.com",
  • "purpose": "string",
  • "media": "images",
  • "status": "pending",
  • "errorCode": "string",
  • "errorMessage": "string",
  • "truncated": 0,
  • "candidates": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z"
}

Delete an extraction and its staged candidates

Removes the extraction, its candidates, and the staged copies behind them. Use it to withdraw a scrape — a page submitted by mistake, or media you no longer want held.

Assets already committed from this extraction are NOT affected. Committing copies the bytes to a new asset key, so no Asset depends on a staged object; delete those with DELETE /assets/{assetId} instead.

Staged bytes are removed on a best-effort basis: the extraction is gone from the API either way, and anything the cleanup misses is collected by the storage expiry rule.

Authorizations:
BearerAuth
path Parameters
extractionId
required
string <uuid>

The extraction returned by the submit call.

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6"
}

Commit chosen candidates as assets

Promotes candidates into real Assets on the extraction's brand, using the same path as a direct upload, so the committed files get identical validation and image-quality processing. A committed image therefore lands as uploaded and reaches complete only after processing — poll the asset before referencing it in generation.

Send no body (or an empty object) to commit every KEPT candidate, none of them flagged as a logo. Commit-all never includes rejected candidates; a rejected candidate can only be committed by naming its candidateId explicitly. Send items to choose a subset and flag individual candidates as logos.

Committing is idempotent per candidate: one that was already committed returns the asset it produced the first time rather than creating a duplicate.

Committing also deduplicates across this brand's extractions, by the image's content. Each candidate's staged bytes are hashed (sha256) first, and a candidate whose bytes match an asset this brand already saved from any extraction, as the same kind of asset (logo or not), returns that existing asset instead of a copy, and its committedAssetId then points at it. Two candidates with the same bytes in one request make one asset. This covers captures with no URL of their own, such as an inline SVG, and two different captures that share their page's URL stay two assets. An image saved before content matching existed carries no hash, so it alone is matched by its http(s) source URL instead. alreadyInLibraryCount says how many of the returned assets were there before this request. Only a live asset (uploaded, processing or complete) is reused; a deleted or failed one never is. An isLogo request never reuses a plain image, and a plain request never reuses a logo; each kind is created once.

Committing is NOT atomic across candidates. They are promoted one at a time in ranked order and the first failure returns immediately, leaving the earlier ones committed. Retrying the same request is the correct recovery, and the per-candidate idempotency is what makes that safe.

Authorizations:
BearerAuth
path Parameters
extractionId
required
string <uuid>

The extraction whose candidates are being committed.

Request Body schema: application/json
optional
Array of objects (CommitUrlExtractionItem)

The candidates to commit. Omit this field entirely (or send no body at all) to commit every KEPT candidate with isLogo false.

There is no commit-nothing request shape: an empty body means "commit all", so a client driving this from a user's selection must not call the endpoint when nothing is selected.

Array
candidateId
required
string <uuid>
isLogo
boolean
Default: false

Mark this specific candidate as the brand's logo. This is not only a label. The asset is created as a logo internally, which skips both the quality assessment and the image-processing workflow a normally committed image goes through.

The type itself is not on the asset response, but the effect is visible: a logo is complete as soon as the commit returns, where a normal image passes through uploaded first and has to be polled.

Because commit is idempotent per candidate, setting this on a candidate that was already committed has no effect. Flag it on its first commit. A logo is never matched to a plain image the brand already has from the same URL, so flagging it creates the logo even when that image was saved before.

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{}

Brands

Create a new brand

Authorizations:
BearerAuth
Request Body schema: application/json
required

Details of the brand to be created

name
required
string [ 1 .. 100 ] characters
industry
required
string [ 1 .. 50 ] characters
description
required
string <= 280 characters
mission
required
string <= 1000 characters
values
required
Array of strings <= 10 items [ items <= 50 characters ]
tone
required
Array of strings <= 5 items
Items Enum: "Professional" "Casual" "Friendly" "Authoritative" "Playful" "Innovative" "Traditional" "Luxurious"
voice
required
Array of strings <= 5 items [ items <= 50 characters ]
logoAssetId
string or null <uuid>

ID of an existing asset to be used as the brand's logo, should be a logo asset.

Responses

Request samples

Content type
application/json
{
  • "name": "Acme Corporation",
  • "industry": "Technology",
  • "description": "Leading provider of innovative cloud solutions",
  • "mission": "To accelerate the world's transition to sustainable technology",
  • "values": [
    ],
  • "tone": [
    ],
  • "voice": [
    ],
  • "logoAssetId": "123e4567-e89b-12d3-a456-426614174000"
}

Response samples

Content type
application/json
{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "name": "Acme Corporation",
  • "industry": "Technology",
  • "description": "Leading provider of innovative cloud solutions",
  • "mission": "To accelerate the world's transition to sustainable technology",
  • "values": [
    ],
  • "tone": [
    ],
  • "voice": [
    ],
  • "logoAsset": {},
  • "organizationId": "123e4567-e89b-12d3-a456-426614174000",
  • "organizationName": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "brandDnaStatus": "none"
}

Retrieve a list of brands

Authorizations:
BearerAuth
query Parameters
all_organizations
boolean
Default: false

Set to 'true' to retrieve brands from all organizations. This is an admin-only parameter. Requests from non-admin users with this parameter will result in a 403 Forbidden error.

page
integer >= 1
Default: 1
limit
integer [ 1 .. 100 ]
Default: 20
sort
string
Default: "-createdAt"
Enum: "name" "-name" "createdAt" "-createdAt"
industry
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    },
  • "links": {}
}

Retrieve a specific brand

Authorizations:
BearerAuth
path Parameters
brandId
required
string <uuid>

Unique identifier of the brand

Responses

Response samples

Content type
application/json
{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "name": "Acme Corporation",
  • "industry": "Technology",
  • "description": "Leading provider of innovative cloud solutions",
  • "mission": "To accelerate the world's transition to sustainable technology",
  • "values": [
    ],
  • "tone": [
    ],
  • "voice": [
    ],
  • "logoAsset": {},
  • "organizationId": "123e4567-e89b-12d3-a456-426614174000",
  • "organizationName": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "brandDnaStatus": "none"
}

Update a specific brand

Authorizations:
BearerAuth
path Parameters
brandId
required
string <uuid>

Unique identifier of the brand

header Parameters
If-Match
required
string

ETag from previous get/update

Request Body schema: application/json
required
name
string or null [ 1 .. 100 ] characters
industry
string or null [ 1 .. 50 ] characters
description
string or null <= 280 characters
mission
string or null <= 1000 characters
values
Array of strings or null <= 10 items [ items <= 50 characters ]
tone
Array of strings or null <= 5 items
Enum: "Professional" "Casual" "Friendly" "Authoritative" "Playful" "Innovative" "Traditional" "Luxurious"
voice
Array of strings or null <= 5 items [ items <= 50 characters ]
logoAssetId
string or null <uuid>

ID of an existing asset to update the brand's logo. Send null to disassociate logo.

Responses

Request samples

Content type
application/json
{
  • "name": "Acme Corporation",
  • "industry": "Technology",
  • "description": "Leading provider of innovative cloud solutions",
  • "mission": "To accelerate the world's transition to sustainable technology",
  • "values": [
    ],
  • "tone": [
    ],
  • "voice": [
    ],
  • "logoAssetId": "123e4567-e89b-12d3-a456-426614174000"
}

Response samples

Content type
application/json
{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "name": "Acme Corporation",
  • "industry": "Technology",
  • "description": "Leading provider of innovative cloud solutions",
  • "mission": "To accelerate the world's transition to sustainable technology",
  • "values": [
    ],
  • "tone": [
    ],
  • "voice": [
    ],
  • "logoAsset": {},
  • "organizationId": "123e4567-e89b-12d3-a456-426614174000",
  • "organizationName": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "brandDnaStatus": "none"
}

Get Brand DNA status and data

Returns the current Brand DNA extraction status and the merged Brand DNA data for a brand. If no PDFs have been uploaded, status will be 'none'.

Authorizations:
BearerAuth
path Parameters
brandId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Brand DNA Versions

List Brand DNA versions for a brand

Returns all versions for the brand, newest first. Each item carries the preview slice but not the full DNA payload.

Authorizations:
BearerAuth
path Parameters
brandId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ]
}

Create a new Brand DNA version

Create a new version with one or more source assets/URLs. Returns the version in pending state; the orchestrator picks up the workflow trigger row and runs per-source extractors plus the merger asynchronously.

Authorizations:
BearerAuth
path Parameters
brandId
required
string <uuid>
Request Body schema: application/json
required
name
string <= 200 characters

Optional human-readable label

assetIds
Array of strings <uuid> <= 20 items [ items <uuid > ]

Asset IDs to feed into per-source extractors (PDF, image, or video). The real limit is COMBINED: assetIds and urls together may not exceed 20, and a request over that is refused with "Too many sources (max 20)". maxItems here is a per-array ceiling and cannot express the sum, so reading it as 20 + 20 is wrong.

urls
Array of strings <uri> <= 20 items [ items <uri > ]

Website URLs to feed into the web extractor. Counts toward the same combined limit of 20 as assetIds, not a separate allowance.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "assetIds": [
    ],
  • "urls": []
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get the currently active Brand DNA version

Returns the active version detail. When the active version is mid-rerun (status=pending or extracting), responds 200 with dna: null. Returns 404 when no version has ever been activated for the brand.

Authorizations:
BearerAuth
path Parameters
brandId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get a specific Brand DNA version

Returns the full version detail including sources and (when ready) the canonical DNA payload.

Authorizations:
BearerAuth
path Parameters
brandId
required
string <uuid>
versionId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Update a Brand DNA version (rename and/or edit DNA payload)

Optimistic-locked update via updatedAt. Setting dna overwrites the canonical S3 payload and recomputes the preview slice; name updates metadata only. At least one of name or dna must be provided. Confidence score and missing fields are immutable from this endpoint.

Authorizations:
BearerAuth
path Parameters
brandId
required
string <uuid>
versionId
required
string <uuid>
Request Body schema: application/json
required
name
string <= 200 characters
object

Full canonical Brand DNA payload (snake_case). Overwrites the existing s3_key blob.

updatedAt
required
string <date-time>

Concurrency token; the previously-returned updatedAt for this version

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "dna": { },
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Delete a Brand DNA version

Hard-deletes a non-active version, including its sources (CASCADE) and S3 artifacts. Deleting the active version is forbidden; activate another version first.

Authorizations:
BearerAuth
path Parameters
brandId
required
string <uuid>
versionId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6"
}

Activate a Brand DNA version

Marks the version active and mirrors its s3_key, version_number, and status to Brands.brand_dna_s3_key/brand_dna_version/brand_dna_status so downstream modal consumers pick up the new payload. Idempotent on an already-active version.

Authorizations:
BearerAuth
path Parameters
brandId
required
string <uuid>
versionId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Cancel an in-flight Brand DNA extraction

Signals workflow cancellation and deletes the version row. Only valid while the version is pending or extracting. Best-effort cleans S3 partials.

Authorizations:
BearerAuth
path Parameters
brandId
required
string <uuid>
versionId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6"
}

Re-run extraction for a Brand DNA version

Replaces the version's source set with the supplied assetIds and urls, resets status to pending, and queues a fresh extraction. The version retains its versionNumber and is_active flag. Returns 202 Accepted.

Authorizations:
BearerAuth
path Parameters
brandId
required
string <uuid>
versionId
required
string <uuid>
Request Body schema: application/json
required
assetIds
Array of strings <uuid> <= 20 items [ items <uuid > ]

Counts toward the combined limit of 20 shared with urls.

urls
Array of strings <uri> <= 20 items [ items <uri > ]

Counts toward the combined limit of 20 shared with assetIds.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Environment Generations

Create environment generation request

Generate an environment image from a text prompt. This is an asynchronous operation that returns 202 Accepted. Poll the GET endpoint to check generation status.

Authorizations:
BearerAuth
path Parameters
brandId
required
string <uuid>
Example: 223e4567-e89b-12d3-a456-426614174000

Brand context for the generation

Request Body schema: application/json
required
prompt
required
string [ 1 .. 2500 ] characters

Environment description prompt for AI generation

Responses

Request samples

Content type
application/json
{
  • "prompt": "A clean white studio with soft natural lighting"
}

Response samples

Content type
application/json
{
  • "environmentGenerationId": "123e4567-e89b-12d3-a456-426614174000",
  • "brandId": "223e4567-e89b-12d3-a456-426614174000",
  • "prompt": "A clean white studio with soft natural lighting",
  • "status": "pending",
  • "generatedAsset": {},
  • "errorCode": "GENERATION_FAILED",
  • "errorMessage": "Failed to generate environment from prompt",
  • "createdAt": "2024-01-01T00:00:00Z",
  • "updatedAt": "2024-01-01T00:00:00Z",
  • "completedAt": "2024-01-01T00:05:30Z",
  • "failedAt": "2024-01-01T00:05:30Z"
}

Get environment generation by ID

Retrieve environment generation details and status. Use this endpoint to poll for completion status after creating an environment generation.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

Environment generation identifier

Responses

Response samples

Content type
application/json
{
  • "environmentGenerationId": "123e4567-e89b-12d3-a456-426614174000",
  • "brandId": "223e4567-e89b-12d3-a456-426614174000",
  • "prompt": "A clean white studio with soft natural lighting",
  • "status": "pending",
  • "generatedAsset": {},
  • "errorCode": "GENERATION_FAILED",
  • "errorMessage": "Failed to generate environment from prompt",
  • "createdAt": "2024-01-01T00:00:00Z",
  • "updatedAt": "2024-01-01T00:00:00Z",
  • "completedAt": "2024-01-01T00:05:30Z",
  • "failedAt": "2024-01-01T00:05:30Z"
}

Scene Forges

Create scene forge request

Generate a scene with products, optional environment, and blending prompt. This is an asynchronous operation that creates 4 initial variations. Returns 202 Accepted. Poll the GET endpoint to check generation status.

Authorizations:
BearerAuth
path Parameters
brandId
required
string <uuid>
Example: 223e4567-e89b-12d3-a456-426614174000

Brand context for the scene forge

Request Body schema: application/json
required
blendingPrompt
required
string [ 1 .. 2500 ] characters

Scene composition prompt (original or enhanced)

promptIsEnhanced
required
boolean

Whether the prompt has been AI-enhanced. Set to true only when the current prompt text exactly matches an accepted enhancement result. Undo and manual edits set this to false.

partner
string (Partner)
Enum: "default" "walmart" "chewy" "instacart"

Partner (retail-media network) slug. default means no partner.

theme
string or null <= 500 characters

Theme from preview (when promptIsEnhanced=true and preview was accepted)

aspectRatio
string or null
Enum: "1:1" "2:3" "3:2" "3:4" "4:3" "9:16" "16:9" "21:9"

Target aspect ratio for generation (optional)

productAssetIds
Array of strings <uuid> <= 5 items [ items <uuid > ]

Array of product asset UUIDs (max 5 products)

environmentAssetId
string or null <uuid>

Optional environment asset UUID (from environment generation or uploaded)

useBrandDna
boolean or null

Whether to apply Brand DNA to scene generation (defaults to true if omitted)

transparentBackground
boolean or null

Render the subject on a transparent background, with no backdrop. Each variation is a PNG with an alpha channel. Cannot be combined with environmentAssetId. Every later round of the scene forge (extend, refine) keeps it. Omitted (or null) means false.

authoredPrompt
string or null <= 2500 characters

If you called the prompt-enhancement endpoint and are submitting its output as blendingPrompt, pass the text you wrote before enhancement here. Omit it otherwise; the server stores blendingPrompt. Stored write-once as authoredPrompt. Not the same as originalPrompt, which is the prompt as submitted.

adverteyesScoring
boolean or null

Whether AdverEyes scores this generation's variations. Omitted (or null) means false. A scored round takes one Creative Optimization; when none is left it is refused with 400 USAGE_LIMIT_EXCEEDED and nothing starts. An extend sent without its own adverteyesScoring reuses the value of the scene forge's most recent generate or extend round, or false when that round stored none.

Responses

Request samples

Content type
application/json
{
  • "blendingPrompt": "Products displayed on a marble countertop with natural lighting",
  • "aspectRatio": "16:9",
  • "productAssetIds": [
    ],
  • "environmentAssetId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}

Response samples

Content type
application/json
{
  • "sceneForgeId": "323e4567-e89b-12d3-a456-426614174000",
  • "brandId": "223e4567-e89b-12d3-a456-426614174000",
  • "blendingPrompt": "Products displayed on a marble countertop with natural lighting",
  • "prompt": "A breathtaking, cinematic action shot of the motorcycle and rider from [Image 1]…",
  • "originalPrompt": "motorcycle on a mountain road",
  • "authoredPrompt": "motorcycle on a mountain road",
  • "promptIsEnhanced": true,
  • "aspectRatio": "1:1",
  • "theme": "Product Display Scene",
  • "productAssets": [],
  • "environmentAsset": {},
  • "assetSource": {},
  • "status": "pending",
  • "variations": [
    ],
  • "refinedVariations": [
    ],
  • "errorCode": "GENERATION_FAILED",
  • "errorMessage": "Failed to generate scene from inputs",
  • "createdAt": "2024-01-01T00:00:00Z",
  • "updatedAt": "2024-01-01T00:00:00Z",
  • "completedAt": "2024-01-01T00:10:00Z",
  • "failedAt": "2024-01-01T00:10:00Z",
  • "useBrandDna": true,
  • "transparentBackground": false,
  • "adverteyesScoring": true
}

List scene forges for brand

Retrieve a paginated list of scene forges for the specified brand. Results can be filtered by status and sorted by creation or update time.

Authorizations:
BearerAuth
path Parameters
brandId
required
string <uuid>
Example: 223e4567-e89b-12d3-a456-426614174000

Brand identifier

query Parameters
partner
string (PartnerFilter)
Enum: "all" "default" "walmart" "chewy" "instacart"
Example: partner=all

Partner list filter. Omit for the default bucket only; "all" returns every partner; otherwise a single partner slug.

page
integer >= 1
Default: 1
Example: page=1

Page number (1-indexed)

limit
integer [ 1 .. 100 ]
Default: 20
Example: limit=20

Number of items per page

sortBy
string
Default: "createdAt"
Enum: "createdAt" "updatedAt"
Example: sortBy=createdAt

Field to sort by

sortOrder
string
Default: "desc"
Enum: "asc" "desc"
Example: sortOrder=desc

Sort direction

status
string (GenerationStatus)
Enum: "pending" "processing" "completed" "failed"
Example: status=completed

Filter by generation status

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Get scene forge by ID

Retrieve scene forge details including all generated variations. Use this endpoint to poll for completion status after creating a scene forge.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>
Example: 323e4567-e89b-12d3-a456-426614174000

Scene forge identifier

Responses

Response samples

Content type
application/json
{
  • "sceneForgeId": "323e4567-e89b-12d3-a456-426614174000",
  • "brandId": "223e4567-e89b-12d3-a456-426614174000",
  • "blendingPrompt": "Products displayed on a marble countertop with natural lighting",
  • "prompt": "A breathtaking, cinematic action shot of the motorcycle and rider from [Image 1]…",
  • "originalPrompt": "motorcycle on a mountain road",
  • "authoredPrompt": "motorcycle on a mountain road",
  • "promptIsEnhanced": true,
  • "aspectRatio": "1:1",
  • "theme": "Product Display Scene",
  • "productAssets": [],
  • "environmentAsset": {},
  • "assetSource": {},
  • "status": "pending",
  • "variations": [
    ],
  • "refinedVariations": [
    ],
  • "errorCode": "GENERATION_FAILED",
  • "errorMessage": "Failed to generate scene from inputs",
  • "createdAt": "2024-01-01T00:00:00Z",
  • "updatedAt": "2024-01-01T00:00:00Z",
  • "completedAt": "2024-01-01T00:10:00Z",
  • "failedAt": "2024-01-01T00:10:00Z",
  • "useBrandDna": true,
  • "transparentBackground": false,
  • "adverteyesScoring": true
}

Scene Forge Prompt Enhancements

Create prompt enhancement request

Request AI enhancement of a prompt for Scene Forge generation. This is an asynchronous operation that returns 202 Accepted. Poll the GET endpoint to check enhancement status and retrieve results.

Authorizations:
BearerAuth
path Parameters
brandId
required
string <uuid>
Example: 223e4567-e89b-12d3-a456-426614174000

Brand context for the enhancement

Request Body schema: application/json
required
originalPrompt
required
string [ 1 .. 2500 ] characters

Original prompt text to be enhanced

productAssetIds
Array of strings <uuid> <= 5 items [ items <uuid > ]

Array of product asset UUIDs (max 5 products)

environmentAssetId
string or null <uuid>

Optional environment asset UUID

useBrandDna
boolean or null

Whether to apply Brand DNA to prompt enhancement (defaults to true if omitted)

transparentBackground
boolean or null

The scene will render the subject on a transparent background (the Scene Forge transparentBackground option), so the enhanced prompt describes the subject only, with no setting. Cannot be combined with environmentAssetId. Omitted (or null) means false.

partner
string (Partner)
Enum: "default" "walmart" "chewy" "instacart"

Partner (retail-media network) slug. default means no partner.

Responses

Request samples

Content type
application/json
{
  • "originalPrompt": "A modern kitchen with stainless steel appliances",
  • "productAssetIds": [
    ],
  • "environmentAssetId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}

Response samples

Content type
application/json
{
  • "promptEnhancementId": "123e4567-e89b-12d3-a456-426614174000",
  • "brandId": "223e4567-e89b-12d3-a456-426614174000",
  • "originalPrompt": "A modern kitchen with stainless steel appliances",
  • "optimizedPrompt": "A sleek, contemporary kitchen featuring premium stainless steel appliances, marble countertops, and soft natural lighting from large windows",
  • "theme": "Modern Elegance",
  • "status": "pending",
  • "errorCode": "ENHANCEMENT_FAILED",
  • "errorMessage": "Failed to enhance prompt",
  • "createdAt": "2024-01-01T00:00:00Z",
  • "updatedAt": "2024-01-01T00:00:00Z",
  • "completedAt": "2024-01-01T00:00:30Z",
  • "failedAt": "2024-01-01T00:00:30Z",
  • "useBrandDna": true,
  • "transparentBackground": false,
  • "partner": "default",
  • "warnings": [
    ]
}

Get prompt enhancement by ID

Retrieve prompt enhancement details and status. Use this endpoint to poll for completion status after creating a prompt enhancement request. Returns both originalPrompt and optimizedPrompt to support frontend Undo functionality.

Authorizations:
BearerAuth
path Parameters
brandId
required
string <uuid>
Example: 223e4567-e89b-12d3-a456-426614174000

Brand context

id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

Prompt enhancement identifier

Responses

Response samples

Content type
application/json
{
  • "promptEnhancementId": "123e4567-e89b-12d3-a456-426614174000",
  • "brandId": "223e4567-e89b-12d3-a456-426614174000",
  • "originalPrompt": "A modern kitchen with stainless steel appliances",
  • "optimizedPrompt": "A sleek, contemporary kitchen featuring premium stainless steel appliances, marble countertops, and soft natural lighting from large windows",
  • "theme": "Modern Elegance",
  • "status": "pending",
  • "errorCode": "ENHANCEMENT_FAILED",
  • "errorMessage": "Failed to enhance prompt",
  • "createdAt": "2024-01-01T00:00:00Z",
  • "updatedAt": "2024-01-01T00:00:00Z",
  • "completedAt": "2024-01-01T00:00:30Z",
  • "failedAt": "2024-01-01T00:00:30Z",
  • "useBrandDna": true,
  • "transparentBackground": false,
  • "partner": "default",
  • "warnings": [
    ]
}

VideoGeneration

Submit Video Generation Job

Creates a new Video Generation Group and triggers the asynchronous generation of videos variations. It generates a video for every combination of the provided prompts and dimensions, using the specified source asset. Every asset ID in the request (startImageAssetId, endImageAssetId, intermediateImageAssetIds, referenceImageAssetIds, referenceVideoAssetIds) must belong to the brand in the path. An asset that belongs to another brand — including another brand in your own organization — is reported as not found (404). Only the six models VideoModel lists as accepted are taken, each with its exact lengths. Any other model (the legacy veo-3.1-fast, kling-v3-pro, seedance-1.5-pro and pixverse-v6 included) or any other length is refused with 400. For seedance-2.5-pro (refs-only / reference-to-video), omit startImageAssetId, endImageAssetId, and intermediateImageAssetIds (those fields are rejected) and pass referenceImageAssetIds and/or referenceVideoAssetIds — at least one reference total. Seedance 2.5 depends on the plan, and a request over the caller's plan is refused with 403: Starter has no Seedance 2.5 at all; Pro allows up to 30 reference images, no reference videos and up to 15 seconds; Ultra allows up to 30 reference images, up to 10 reference videos and up to 30 seconds. seedance-2.0-pro and kling-v3-omni-pro take either frames (startImageAssetId with an optional endImageAssetId) or referenceImageAssetIds (up to 9 for seedance-2.0-pro, up to 7 for kling-v3-omni-pro, on every plan), never both, and reject referenceVideoAssetIds. Every other model requires startImageAssetId and rejects both reference fields. grok-imagine-video renders from the start frame only and refuses endImageAssetId with 400. resolution is optional and defaults to 720p; 1080p is on Pro and Ultra and refused with 403 on Starter. Each video is billed video credits by model, length and resolution (see resolution).

Authorizations:
BearerAuth
path Parameters
brandId
required
string <uuid>

The unique identifier of the brand.

Request Body schema: application/json
required
startImageAssetId
string <uuid>

The ID of the original source asset of the image that will be used as the video start frame. Required for every model except seedance-2.5-pro, which rejects it (refs-only). seedance-2.0-pro and kling-v3-omni-pro need it unless referenceImageAssetIds is sent, and reject it alongside references.

endImageAssetId
string <uuid>

The ID of the asset to use as the video end frame. Optional. Not supported by all models. Rejected for seedance-2.5-pro, and for seedance-2.0-pro and kling-v3-omni-pro when referenceImageAssetIds is sent.

referenceImageAssetIds
Array of strings <uuid> <= 30 items [ items <uuid > ]

Reference image asset IDs. Taken by seedance-2.5-pro, seedance-2.0-pro and kling-v3-omni-pro, in the order sent (seedance-2.5-pro prompts address them as @Image N). Optional (omit for none). Rejected for every other model. seedance-2.5-pro is refs-only and needs at least one reference total (images and/or videos); maxItems is its absolute ceiling, which Pro and Ultra both allow; Starter has no seedance-2.5-pro (403). seedance-2.0-pro takes up to 9 and kling-v3-omni-pro up to 7, on every plan, and only without startImageAssetId and endImageAssetId: these two models take frames or references, never both. Each must be JPEG or PNG and an image, logo, or environment asset, 30MB or smaller (50MB for kling-v3-omni-pro). For kling-v3-omni-pro, an image whose dimensions are recorded must also have an aspect ratio (width / height) between 0.4 and 2.5; an image with no recorded dimensions skips that check. Assets generated by NativeAds (scene_forge, environments, generative resize and the rest) report fileType as the bare category 'image' and are accepted as-is.

referenceVideoAssetIds
Array of strings <uuid> <= 10 items [ items <uuid > ]

Reference video asset IDs for seedance-2.5-pro (@Video N order). Optional (omit for none). Rejected for every other model, seedance-2.0-pro and kling-v3-omni-pro included. Video-only 2.5 jobs are allowed, but reference videos are tier-gated: only Ultra takes them, up to maxItems; Starter and Pro get 403. Must be MP4 or QuickTime, 200MB or smaller, 2 to 30 seconds each, 30 seconds combined, 23.8 to 60 FPS. Frame dimensions, when known, must satisfy BOTH of the model's rules: a pixel count (width x height) between 407696 and 8295044, and an aspect ratio (width / height) between 0.4 and 2.5. They are independent -- 1400x300 is 420000 pixels, inside the band, and is still refused on its 4.67 ratio. No separate per-side rule is enforced: satisfying both of the above confines every side to 404-4554 px. A video whose dimensions were never measured skips both checks rather than being rejected. A video with no measured duration is rejected: conflict while still processing, invalid_argument once complete without one.

intermediateImageAssetIds
Array of strings <uuid> [ 1 .. 5 ] items [ items <uuid > ]

Ordered intermediate frame assets for kling-v3-omni-pro with a start frame. Optional (omit for none). Order is temporal. Allowed count by length: 6 and 8 take 0-1, 10 and 12 take 0-2, 15 takes 0-3, 20 takes 1-4, 30 takes 1-5. Refused with 400 for every other model, optimized included.

userPrompts
required
Array of strings non-empty [ items [ 1 .. 2500 ] characters ]

One or more text prompts describing the desired context/environment. Each entry produces its own video and is billed separately. 2500 characters for every model except seedance-2.5-pro, which allows 5000, as does optimized where it renders on seedance-2.5-pro (Pro and Ultra). The higher cap is enforced in Go, not by this field. Empty and whitespace-only prompts are rejected.

authoredPrompts
Array of strings[ items <= 5000 characters ]

Optional, parallel to userPrompts. If you called the prompt-enhancement endpoint and are submitting its output, pass, at the same index, the text you wrote before enhancement. When present, [] included, it must have the same length as userPrompts. An empty entry, or omitting the array, makes the server store that entry's userPrompts text. Stored write-once on each group as authoredPrompt.

required
object (Dimension)
enableAudio
boolean
Default: false

Whether to generate audio for the video. Defaults to false.

model
string
Default: "seedance-2.0-pro"
Enum: "veo-3.1" "veo-3.1-fast" "kling-v3-pro" "kling-v3-omni-pro" "grok-imagine-video" "seedance-1.5-pro" "seedance-2.0-pro" "seedance-2.5-pro" "pixverse-v6" "optimized"

The AI model to use for video generation. Defaults to seedance-2.0-pro, which also sets the default duration to 8 seconds. seedance-2.5-pro is never the default: it rejects startImageAssetId and requires at least one reference image or video, so it must be requested explicitly alongside referenceImageAssetIds / referenceVideoAssetIds.

duration
integer >= 1

Desired video duration in seconds. Optional; when omitted the backend uses the model's default. Each model accepts an exact list of lengths (see VideoModel): seedance-2.5-pro takes 6, 8, 10, 15, 20 or 30; kling-v3-omni-pro takes 6, 8, 10, 12, 15, 20 or 30; seedance-2.0-pro and grok-imagine-video take 6, 8, 10, 12 or 15; veo-3.1 takes 6 or 8; optimized takes its plan's model's lengths and defaults to 8. Any other value is refused with 400. seedance-2.5-pro is further capped by plan: up to 15 on Pro and 30 on Ultra, and longer is refused with 403.

resolution
string
Enum: "720p" "1080p"

Output resolution. Optional; defaults to 720p. Starter renders 720p only, and 1080p there is refused with 403. Each video is billed video credits by model, length and resolution, from 1 to 10: most cost 1, and seedance-2.5-pro at 30s and 1080p costs 10. A request costs the sum over its prompts.

promptIsEnhanced
boolean
Default: false

Whether the prompt was enhanced via the prompt enhancement preview flow.

useBrandDna
boolean
Default: false

Whether to apply Brand DNA to inline prompt enhancement during video generation. Defaults to false.

partner
string (Partner)
Enum: "default" "walmart" "chewy" "instacart"

Partner (retail-media network) slug. default means no partner.

Responses

Request samples

Content type
application/json
Example
{
  • "startImageAssetId": "123e4567-e89b-12d3-a456-426614174000",
  • "userPrompts": [
    ],
  • "dimension": {
    },
  • "enableAudio": false
}

Response samples

Content type
application/json
{}

List Generated Video Groups

Retrieves a paginated list of all generated videos groups created by the user/brand, suitable for the gallery view. Each group includes its source asset info, parameters, and the generated video variations with their current status.

Authorizations:
BearerAuth
path Parameters
brandId
required
string <uuid>

The unique identifier of the brand.

query Parameters
partner
string (PartnerFilter)
Enum: "all" "default" "walmart" "chewy" "instacart"
Example: partner=all

Partner list filter. Omit for the default bucket only; "all" returns every partner; otherwise a single partner slug.

page
integer >= 1
Default: 1

Page number for pagination.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page.

sortBy
string
Default: "createdAt"
Value: "createdAt"

Field to sort by.

sortOrder
string
Default: "desc"
Enum: "asc" "desc"

Sort order.

Responses

Response samples

Content type
application/json
{}

Get Generated Videos Group Details

Retrieves the details of a specific generated videos group, including the status of all its generated variations. Poll this endpoint after submitting a video generation job to track progress.

Authorizations:
BearerAuth
path Parameters
generatedVideosGroupId
required
string <uuid>

The unique identifier of the generated videos group.

Responses

Response samples

Content type
application/json
{}

Image-to-Video Prompt Enhancements

Create an image-to-video prompt enhancement preview

Creates a prompt enhancement preview request for image-to-video generation. The enhancement workflow will refine the provided prompt using AI, taking into account the start frame image, aspect ratio, and target video model, and return an optimized version suitable for video generation. Every asset ID in the request (startFrameAssetId, endFrameAssetId, intermediateFrameAssetIds, referenceImageAssetIds, referenceVideoAssetIds) must belong to the brand in the path. An asset that belongs to another brand — including another brand in your own organization — is reported as not found (404). For seedance-2.5-pro (refs-only), omit startFrameAssetId, endFrameAssetId, and intermediateFrameAssetIds (those fields are rejected) and pass referenceImageAssetIds and/or referenceVideoAssetIds — at least one reference total. Seedance 2.5 depends on the plan, as for video generation, and a request over the caller's plan is refused with 403: Starter has no Seedance 2.5; Pro allows up to 30 reference images, no reference videos and up to 15 seconds; Ultra allows up to 30 reference images, up to 10 reference videos and up to 30 seconds. The model and duration are checked as for a new video: only the six accepted models (see VideoModel), each with its exact lengths, and anything else is refused with 400, so a prompt is never enhanced for a video that could not be made. seedance-2.0-pro and kling-v3-omni-pro take either frames (startFrameAssetId with an optional endFrameAssetId) or referenceImageAssetIds (up to 9 for seedance-2.0-pro, up to 7 for kling-v3-omni-pro, on every plan), never both, and reject referenceVideoAssetIds. Every other model requires startFrameAssetId and rejects both reference fields. grok-imagine-video renders from the start frame only and refuses endFrameAssetId with 400.

Authorizations:
BearerAuth
path Parameters
brandId
required
string <uuid>

The unique identifier of the brand.

Request Body schema: application/json
required
startFrameAssetId
string <uuid>

ID of the start frame image asset. Required for every model except seedance-2.5-pro, which rejects it (refs-only). seedance-2.0-pro and kling-v3-omni-pro need it unless referenceImageAssetIds is sent, and reject it alongside references.

endFrameAssetId
string <uuid>

ID of the end frame image asset. Optional. Rejected for seedance-2.5-pro, and for seedance-2.0-pro and kling-v3-omni-pro when referenceImageAssetIds is sent.

referenceImageAssetIds
Array of strings <uuid> <= 30 items [ items <uuid > ]

Reference image asset IDs. Taken by seedance-2.5-pro, seedance-2.0-pro and kling-v3-omni-pro, in the order sent (seedance-2.5-pro prompts address them as @Image N). Optional (omit for none). Rejected for every other model. seedance-2.5-pro is refs-only and needs at least one reference total (images and/or videos); maxItems is its absolute ceiling, which Pro and Ultra both allow; Starter has no seedance-2.5-pro (403). seedance-2.0-pro takes up to 9 and kling-v3-omni-pro up to 7, on every plan, and only without startFrameAssetId and endFrameAssetId: these two models take frames or references, never both. Each must be JPEG or PNG and an image, logo, or environment asset, 30MB or smaller (50MB for kling-v3-omni-pro). For kling-v3-omni-pro, an image whose dimensions are recorded must also have an aspect ratio (width / height) between 0.4 and 2.5; an image with no recorded dimensions skips that check. Assets generated by NativeAds (scene_forge, environments, generative resize and the rest) report fileType as the bare category 'image' and are accepted as-is.

referenceVideoAssetIds
Array of strings <uuid> <= 10 items [ items <uuid > ]

Reference video asset IDs for seedance-2.5-pro (@Video N order). Optional (omit for none). Rejected for every other model, seedance-2.0-pro and kling-v3-omni-pro included. Video-only 2.5 jobs are allowed, but reference videos are tier-gated: only Ultra takes them, up to maxItems; Starter and Pro get 403. Must be MP4 or QuickTime, 200MB or smaller, 2 to 30 seconds each, 30 seconds combined, 23.8 to 60 FPS. Frame dimensions, when known, must satisfy BOTH of the model's rules: a pixel count (width x height) between 407696 and 8295044, and an aspect ratio (width / height) between 0.4 and 2.5. They are independent -- 1400x300 is 420000 pixels, inside the band, and is still refused on its 4.67 ratio. No separate per-side rule is enforced: satisfying both of the above confines every side to 404-4554 px. A video whose dimensions were never measured skips both checks rather than being rejected. A video with no measured duration is rejected: conflict while still processing, invalid_argument once complete without one.

intermediateFrameAssetIds
Array of strings <uuid> [ 1 .. 5 ] items [ items <uuid > ]

Ordered intermediate frame assets for kling-v3-omni-pro enhancement. Optional. Fed to the enhancer alongside start/end. Refused with 400 for every other model, optimized included. (No per-duration min/max enforced here; preview is exploratory, see generation rules.)

originalPrompt
required
string [ 1 .. 2500 ] characters

The text prompt to enhance for video generation. 2500 characters for every model except seedance-2.5-pro, which uses Seedance25Prompt (5000), as does optimized where it renders on seedance-2.5-pro (Pro and Ultra). Enforced in Go, not by this field.

aspectRatio
required
string
Enum: "16:9" "9:16" "1:1"

The target aspect ratio for the video. Veo 3.1 has no square render, so on Veo 3.1 a 1:1 request is accepted and the prompt is written for 16:9.

model
required
string
Enum: "veo-3.1" "veo-3.1-fast" "kling-v3-pro" "kling-v3-omni-pro" "grok-imagine-video" "seedance-1.5-pro" "seedance-2.0-pro" "seedance-2.5-pro" "pixverse-v6" "optimized"

The target video generation model.

duration
integer >= 1

Target video duration (s). Lets the enhancer detect the long-video (>8s) ClipForge case. Omitted means the model's default. Must be one of the model's lengths (see VideoModel), or the request is refused with 400.

enableAudio
boolean
Default: false

Whether audio is enabled -- controls audio guidance in prompt enhancement. Defaults to false.

useBrandDna
boolean
Default: false

Whether to apply Brand DNA to prompt enhancement. Defaults to false. FE sends explicitly based on Brand DNA toggle state.

Responses

Request samples

Content type
application/json
Example
{
  • "startFrameAssetId": "550e8400-e29b-41d4-a716-446655440000",
  • "endFrameAssetId": "660e8400-e29b-41d4-a716-446655440001",
  • "originalPrompt": "The product slowly rotates on a marble countertop with soft natural lighting",
  • "aspectRatio": "16:9",
  • "model": "veo-3.1"
}

Response samples

Content type
application/json
{
  • "promptEnhancementId": "123e4567-e89b-12d3-a456-426614174000",
  • "brandId": "223e4567-e89b-12d3-a456-426614174000",
  • "startFrameAssetId": "550e8400-e29b-41d4-a716-446655440000",
  • "endFrameAssetId": "93aa28e6-7ae6-4083-af4d-58f3411b4df6",
  • "referenceImageAssetIds": [
    ],
  • "referenceVideoAssetIds": [
    ],
  • "intermediateFrameAssetIds": [
    ],
  • "originalPrompt": "The product slowly rotates on a marble countertop with soft natural lighting",
  • "aspectRatio": "16:9",
  • "model": "veo-3.1",
  • "duration": 1,
  • "enhancedPrompt": "A premium skincare product elegantly rotates on a polished Calacatta marble countertop, bathed in warm diffused golden-hour light filtering through sheer curtains, with subtle reflections dancing across the marble surface...",
  • "status": "pending",
  • "errorCode": "ENHANCEMENT_FAILED",
  • "errorMessage": "Failed to enhance prompt due to content policy violation",
  • "createdAt": "2024-01-01T00:00:00Z",
  • "updatedAt": "2024-01-01T00:00:00Z",
  • "completedAt": "2024-01-01T00:00:30Z",
  • "failedAt": "2024-01-01T00:00:30Z",
  • "enableAudio": true,
  • "useBrandDna": true
}

Get image-to-video prompt enhancement status and results

Retrieves the status and results of a prompt enhancement request. Poll this endpoint until status is 'completed' or 'failed'.

Authorizations:
BearerAuth
path Parameters
brandId
required
string <uuid>

The unique identifier of the brand.

id
required
string <uuid>

The prompt enhancement ID.

Responses

Response samples

Content type
application/json
{
  • "promptEnhancementId": "123e4567-e89b-12d3-a456-426614174000",
  • "brandId": "223e4567-e89b-12d3-a456-426614174000",
  • "startFrameAssetId": "550e8400-e29b-41d4-a716-446655440000",
  • "endFrameAssetId": "93aa28e6-7ae6-4083-af4d-58f3411b4df6",
  • "referenceImageAssetIds": [
    ],
  • "referenceVideoAssetIds": [
    ],
  • "intermediateFrameAssetIds": [
    ],
  • "originalPrompt": "The product slowly rotates on a marble countertop with soft natural lighting",
  • "aspectRatio": "16:9",
  • "model": "veo-3.1",
  • "duration": 1,
  • "enhancedPrompt": "A premium skincare product elegantly rotates on a polished Calacatta marble countertop, bathed in warm diffused golden-hour light filtering through sheer curtains, with subtle reflections dancing across the marble surface...",
  • "status": "pending",
  • "errorCode": "ENHANCEMENT_FAILED",
  • "errorMessage": "Failed to enhance prompt due to content policy violation",
  • "createdAt": "2024-01-01T00:00:00Z",
  • "updatedAt": "2024-01-01T00:00:00Z",
  • "completedAt": "2024-01-01T00:00:30Z",
  • "failedAt": "2024-01-01T00:00:30Z",
  • "enableAudio": true,
  • "useBrandDna": true
}

Organizations

Get feature usage status

Retrieve usage status for all managed features. Returns current usage counts, limits, remaining quota, and reset timing for the current organization.

Features are grouped by source (plan or override) and include cap information for each cap type (e.g., generation, training).

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Upscale

Create an upscale group

Needs the Pro or Ultra plan, or Upscale granted to your organization; on another plan the request is refused with 403 and nothing is charged.

Upscales one image asset to 1-4 targets. Each target produces exactly one output, which is generated asynchronously. The response is the new group with every output pending. Poll GET /upscale-groups/{groupId} until the group status is completed or failed. A group is completed when at least one output completed, and failed when every output failed.

Targets. A target is {"mode": "factor", "value": 2 | 3 | 4} or {"mode": "long_edge", "value": <pixels>}. The effective factor f is value in factor mode and value / source long edge in long-edge mode, so it can be fractional (1.5). Each output is round(source width × f) × round(source height × f), which keeps the aspect ratio to within 1 px of rounding. A target is accepted only when:

  • 1 < f ≤ 4
  • the output long edge is at most 8192 px, or 16384 px with print size (below)
  • the source long edge is at least 256 px and at most 8192 px (a larger image, such as a print-size output, is not upscaled again)

Two targets that produce the same output size in one request are rejected.

Print size. An output long edge above 8192 px (up to 16384) needs print size: the Pro and Ultra plans have it, or it is granted to your organization. Without it the request is refused with 403 and nothing is charged. gated_features.upscale_print_size on GET /organizations/current/feature-usage says whether you have it.

Source. source_asset_id must be an image asset (a PNG, JPEG or WebP upload, or an image generated on the platform) that your organization owns. Output sizes are computed from the width and height recorded on the asset. A source that is still being processed is rejected with 422; retry shortly. A source with no recorded dimensions is rejected with 400; re-upload the image.

Usage. Each output counts against the organization's images pool by output size: 1 up to 24 MP, 2 up to 48 MP, 4 up to 96 MP and 11 up to 268.4 MP (16384 × 16384, print size). The whole request is charged when the group is created. A failed output is given back. GET /organizations/current/feature-usage reports what is left.

Authorizations:
BearerAuth
path Parameters
brandId
required
string <uuid>

The unique identifier of the brand.

Request Body schema: application/json
required
source_asset_id
required
string <uuid>

The image asset to upscale. It must belong to your organization.

required
Array of objects (UpscaleTarget) [ 1 .. 4 ] items

1-4 targets. Each produces exactly one output. Two targets with the same output size are rejected.

partner
string (Partner)
Enum: "default" "walmart" "chewy" "instacart"

Partner (retail-media network) slug. default means no partner.

Responses

Request samples

Content type
application/json
{
  • "source_asset_id": "550e8400-e29b-41d4-a716-446655440000",
  • "targets": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "333e4567-e89b-12d3-a456-426614174002",
  • "brand_id": "444e4567-e89b-12d3-a456-426614174003",
  • "source_asset_id": "550e8400-e29b-41d4-a716-446655440000",
  • "source_asset": {
    },
  • "status": "processing",
  • "outputs": [
    ],
  • "total_credits": 5,
  • "error_code": null,
  • "error_message": null,
  • "created_at": "2026-10-16T00:00:00Z",
  • "updated_at": "2026-10-16T00:00:30Z",
  • "completed_at": null,
  • "failed_at": null
}

List upscale groups for a brand

Returns a page of the brand's upscale groups with their outputs, newest first.

Authorizations:
BearerAuth
path Parameters
brandId
required
string <uuid>

The unique identifier of the brand.

query Parameters
partner
string (PartnerFilter)
Enum: "all" "default" "walmart" "chewy" "instacart"
Example: partner=all

Partner list filter. Omit for the default bucket only; "all" returns every partner; otherwise a single partner slug.

offset
integer >= 0
Default: 0

Number of items to skip.

limit
integer [ 1 .. 100 ]
Default: 20

Maximum number of items to return.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 42,
  • "offset": 0,
  • "limit": 20
}

Get an upscale group

Returns one upscale group with all of its outputs. Use it to poll a group created with POST /brands/{brandId}/upscale-groups: stop when status is completed or failed. A completed output carries its asset; a failed one carries error_code and error_message.

Authorizations:
BearerAuth
path Parameters
groupId
required
string <uuid>

The unique identifier of the upscale group.

Responses

Response samples

Content type
application/json
{
  • "id": "333e4567-e89b-12d3-a456-426614174002",
  • "brand_id": "444e4567-e89b-12d3-a456-426614174003",
  • "source_asset_id": "550e8400-e29b-41d4-a716-446655440000",
  • "source_asset": {
    },
  • "status": "processing",
  • "outputs": [
    ],
  • "total_credits": 5,
  • "error_code": null,
  • "error_message": null,
  • "created_at": "2026-10-16T00:00:00Z",
  • "updated_at": "2026-10-16T00:00:30Z",
  • "completed_at": null,
  • "failed_at": null
}

Delete an upscale group

Soft-deletes the group and its outputs; they no longer appear in any response. Processing outputs are not cancelled.

Authorizations:
BearerAuth
path Parameters
groupId
required
string <uuid>

The unique identifier of the upscale group.

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6"
}

Delete an upscale output

Removes one output from its group. The group and its other outputs are kept. Deleting an output that is still processing does not stop it and does not give its usage back.

Authorizations:
BearerAuth
path Parameters
outputId
required
string <uuid>

The unique identifier of the upscale output.

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6"
}