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",
  • "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",
  • "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 30-60 seconds. 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 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.

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 [ 10 .. 280 ] characters
mission
required
string <= 1000 characters
values
required
Array of strings <= 10 items [ items <= 50 characters ]
tone
required
Array of strings[ items <= 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 [ 10 .. 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[ items <= 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)

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

Website URLs to feed into the web extractor

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 > ]
urls
Array of strings <uri> <= 20 items [ items <uri > ]

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)

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",
  • "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
}

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",
  • "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
}

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)

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,
  • "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,
  • "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. 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. Reference counts and duration are capped per plan tier below the absolute maxItems ceilings, and reference videos are themselves tier-gated, so video-only 2.5 jobs are not available on every plan; over the caller's tier the request fails with upgrade_required.

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 all models except seedance-2.5-pro. Rejected for seedance-2.5-pro (refs-only).

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.

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

Reference image asset IDs for seedance-2.5-pro (@Image N order). Optional (omit for none). Rejected for every other model. For 2.5, at least one reference total (images and/or videos) is required. maxItems is the absolute ceiling; the effective cap is per plan tier and lower tiers allow fewer. Must be JPEG or PNG, 120MB or smaller, and an image, logo, or environment asset. 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. Video-only 2.5 jobs are allowed, but reference videos are tier-gated: lower tiers permit none and get upgrade_required. maxItems is the absolute ceiling; the effective cap is per tier. Must be MP4 or QuickTime, 200MB or smaller, 1.8 to 30.2 seconds each, 30 seconds combined, 23.8 to 60 FPS. 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 the optimized model. Optional (omit for none). Order is temporal. Per-duration min/max enforced server-side. Rejected for non-optimized models.

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

One or more text prompts describing the desired context/environment.

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 falls back to a per-model default. Backend currently does not enforce a per-model allow-list.

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. 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. Reference counts are capped per plan tier below the absolute maxItems ceilings, and reference videos are tier-gated, so over the caller's tier the request fails with upgrade_required.

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 all models except seedance-2.5-pro. Rejected for seedance-2.5-pro (refs-only).

endFrameAssetId
string <uuid>

ID of the end frame image asset. Optional. Rejected for seedance-2.5-pro.

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

Reference image asset IDs for seedance-2.5-pro (@Image N order). Optional (omit for none). Rejected for every other model. For 2.5, at least one reference total (images and/or videos) is required. maxItems is the absolute ceiling; the effective cap is per plan tier and lower tiers allow fewer. Must be JPEG or PNG, 120MB or smaller, and an image, logo, or environment asset. 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. Video-only 2.5 jobs are allowed, but reference videos are tier-gated: lower tiers permit none and get upgrade_required. maxItems is the absolute ceiling; the effective cap is per tier. Must be MP4 or QuickTime, 200MB or smaller, 1.8 to 30.2 seconds each, 30 seconds combined, 23.8 to 60 FPS. 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 optimized-model enhancement. Optional. Fed to the enhancer alongside start/end. Rejected for non-optimized models. (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) — enforced in Go when model is seedance-2.5-pro, not by this field.

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

The target aspect ratio for the video.

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.

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": {
    }
}