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" "video" "document"
status
string
Enum: "processing" "complete" "failed"
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": [
    ]
}

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

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"

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",
  • "aspectRatio": "1:1",
  • "theme": "Product Display Scene",
  • "productAssets": [],
  • "environmentAsset": {},
  • "status": "pending",
  • "variations": [
    ],
  • "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"
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",
  • "aspectRatio": "1:1",
  • "theme": "Product Display Scene",
  • "productAssets": [],
  • "environmentAsset": {},
  • "status": "pending",
  • "variations": [
    ],
  • "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"

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.

Authorizations:
BearerAuth
path Parameters
brandId
required
string <uuid>

The unique identifier of the brand.

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

The ID of the original source asset of the image that will be used as the video start frame.

endImageAssetId
string <uuid>

The ID of the asset to use as the video end frame. Optional. Not supported by all models.

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: "veo-3.1"
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" "pixverse-v6" "optimized"

The AI model to use for video generation. Defaults to veo-3.1.

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"

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

Responses

Request samples

Content type
application/json
{
  • "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"
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.

Authorizations:
BearerAuth
path Parameters
brandId
required
string <uuid>

The unique identifier of the brand.

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

ID of the start frame image asset.

endFrameAssetId
string <uuid>

ID of the end frame image asset. Optional.

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.

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