API for generating UGC-style AI advertising videos using AI creators. Accepts a script (up to 800 characters), a creator name, and optional media assets (JPEG, PNG, MOV, MP4). Usage is billed at 1 credit per second of generated video. Exposes /list-creators, /submit, and /poll endpoints for asynchronous job management.
openapi: 3.0.3
info:
title: Captions AI Creator & AI Ads API
description: >
REST API for generating AI talking-head videos using community avatars
(AI Creator) and UGC-style AI advertising videos (AI Ads). Both APIs are
asynchronous: submit a job, then poll for completion. Scripts are limited
to 800 characters, supporting 30+ languages with automatic detection.
Usage is billed at 1 credit per second of generated video. Rate limit is
5 requests per minute per endpoint.
version: '1.0'
contact:
name: Captions API Support
url: https://captions.ai/help/docs/api/overview
servers:
- url: https://api.captions.ai/api
description: Captions API production server
security:
- ApiKeyAuth: []
tags:
- name: AI Creator
description: Generate talking-head videos using community AI avatars or AI Twins
- name: AI Ads
description: Generate UGC-style AI advertising videos using AI creators
paths:
/creator/list:
post:
tags: [AI Creator]
summary: List AI Creators
description: >
Retrieves a list of AI creators (community avatars and AI Twins) that
can be used with the AI Creator API, along with thumbnail image and
video preview URLs.
operationId: listCreators
responses:
'200':
description: Returns list of supported creators and thumbnails
content:
application/json:
schema:
$ref: '#/components/schemas/CreatorListResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/creator/submit:
post:
tags: [AI Creator]
summary: Submit AI Creator Video Job
description: >
Submit a video generation job using an AI Creator avatar. The script
must be 800 characters or fewer and supports 30+ languages with
automatic language detection. Videos max out at 1 minute. Usage is
billed at 1 credit per second of generated video.
operationId: submitCreatorJob
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatorSubmitRequest'
responses:
'200':
description: Returns an operation ID for polling
content:
application/json:
schema:
$ref: '#/components/schemas/SubmitResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/RateLimited'
/creator/poll:
post:
tags: [AI Creator]
summary: Poll AI Creator Video Job
description: >
Poll the status of an AI Creator video generation job. Returns
QUEUED or PROCESSING with a progress value while in-flight, or a
completed video URL when done.
operationId: pollCreatorJob
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PollRequest'
responses:
'200':
description: Returns job status and video URL on completion
content:
application/json:
schema:
$ref: '#/components/schemas/PollResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/ads/submit:
post:
tags: [AI Ads]
summary: Submit AI Ads Video Job
description: >
Submit a UGC-style AI advertising video generation job. Requires a
script (max 800 characters), a creator name, and at least one media
URL (JPEG, PNG, MOV, or MP4). Supports up to 10 media URLs.
Usage is billed at 1 credit per second of generated video.
Rate limit is 5 requests per minute.
operationId: submitAdsJob
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AdsSubmitRequest'
responses:
'200':
description: Returns an operation ID for polling
content:
application/json:
schema:
$ref: '#/components/schemas/SubmitResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/RateLimited'
/ads/poll:
post:
tags: [AI Ads]
summary: Poll AI Ads Video Job
description: >
Poll the status of an AI Ads video generation job. Returns QUEUED
or PROCESSING with a progress value while in-flight, or a completed
video URL and COMPLETE state when done.
operationId: pollAdsJob
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PollRequest'
responses:
'200':
description: Returns job status and video URL on completion
content:
application/json:
schema:
$ref: '#/components/schemas/PollResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
responses:
Unauthorized:
description: Unauthorized — invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
BadRequest:
description: Bad Request — missing required fields or invalid parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
RateLimited:
description: Too Many Requests — rate limit is 5 requests per minute
content:
text/html:
schema:
type: string
schemas:
CreatorListResponse:
type: object
description: List of available AI creators with thumbnail assets
properties:
supportedCreators:
type: array
items:
type: string
description: List of available creator names
example: [Kate, Alex, Jordan]
thumbnails:
type: object
description: Map of creator name to thumbnail URLs
additionalProperties:
$ref: '#/components/schemas/CreatorThumbnail'
CreatorThumbnail:
type: object
description: Thumbnail assets for an AI creator
properties:
imageUrl:
type: string
description: Static thumbnail image URL
example: https://cdn.captions.ai/creators/kate/thumb.jpg
videoUrl:
type: string
description: Short preview video URL
example: https://cdn.captions.ai/creators/kate/preview.mp4
CreatorSubmitRequest:
type: object
required: [script]
description: >
Request body for submitting an AI Creator video generation job.
properties:
script:
type: string
maxLength: 800
description: Script for the AI Creator (max 800 characters)
example: Welcome to Captions! Create stunning AI videos in seconds.
creatorName:
type: string
description: AI Creator name. Defaults to Kate if not specified.
default: Kate
example: Kate
webhookId:
type: string
description: Registered webhook identifier for completion notification
example: wh_abc123
resolution:
type: string
enum: [fhd, 4k]
default: '4k'
description: Output video resolution
AdsSubmitRequest:
type: object
required: [script, creatorName, mediaUrls]
description: >
Request body for submitting an AI Ads video generation job.
properties:
script:
type: string
maxLength: 800
description: Script for the AI Ad (max 800 characters, any language)
example: Try our new product — it changes everything!
creatorName:
type: string
description: Name of the AI Creator to use
example: Kate
mediaUrls:
type: array
items:
type: string
format: uri
minItems: 1
maxItems: 10
description: >
URLs to publicly hosted media files (JPEG, PNG, MOV, MP4).
Minimum 1, maximum 10.
example:
- https://example.com/product-image.jpg
webhookId:
type: string
description: Unique ID for a registered webhook
example: wh_abc123
resolution:
type: string
enum: [fhd, 4k]
default: '4k'
description: Output video resolution
PollRequest:
type: object
required: [operationId]
description: Request body for polling a video generation job
properties:
operationId:
type: string
description: The identifier for the video generation request to check
example: op_xyz789abc
SubmitResponse:
type: object
description: Response from a job submission containing the operation ID
properties:
operationId:
type: string
description: Unique identifier for the submitted job; use with poll endpoints
example: op_xyz789abc
PollResponse:
type: object
description: >
Job status response. If completed, includes a video URL and
state=COMPLETE. If still in flight, includes state (QUEUED or
PROCESSING) and a progress value.
properties:
url:
type: string
description: URL to the generated video (present when state=COMPLETE)
example: https://cdn.captions.ai/videos/op_xyz789abc.mp4
state:
type: string
enum: [QUEUED, PROCESSING, COMPLETE]
description: Current state of the job
example: COMPLETE
progress:
type: number
description: Progress indicator (present while in-flight)
example: 65
ErrorResponse:
type: object
description: Error response body
properties:
detail:
type: string
description: Human-readable error message
example: Unauthorized API key