​
Overview

The AI Ads API allows you to generate a UGC-style ads up to 1 minute in length in 30+ languages. With a script and a selected creator among our community creators, the API will return a fully composited ad with media of your choosing.

1

Create a script

  • Write a script that is 800 characters or less (currently, videos must be 1 minute or less in length).

  • The script can be in any language and your language will be automatically detected.

2

Choose your creator

  • Open the Captions iPhone app to browse available community creators (Android coming soon).

  • Use the /list-creators path to choose one of our creators.

3

Choose your media

Ensure that the media you want to include in the AI Ad are at publicly-hosted downloadable URLs. Supported formats are JPEG, PNG, MOV and MP4.

4

Generate your video

Use the /submit path to enter your API Key, Creator Name, and Script and links to any media you would like to be in the ad.

5

Download your video

  • While you wait, you can use the /poll path to check the status.

  • Once complete, you’ll be able to download the video.

​
Requirements to using the API

To use the Captions API, you must:

  1. Accept the Captions API Terms

  2. Have enough credits to complete your request

​
Usage, credits, and limitations

  • The AI Ads API consumes 1 credit per second.

  • For example, generating a 30-second video would consume 30 credits.

  • You can view remaining credits and purchase additional credits on the API Dashboard.

  • The maximum length of a video you can generate is 1 minute (800 character script)

​
Instructions

​
/list-creators

List creators available to use in the API.

Request

Bash script
curl -X POST https://api.captions.ai/api/ads/list-creators -H "Content-Type: application/json" -H "x-api-key: <api-key>"

Response Types

​
/submit

Begin the AI Ads video generation process with a specified creator.

Request

script - required - Scripts up to 800 characters are supported.

creatorName - required - Default value is "Kate". For a complete list of supported creators, please refer to the /list-creators endpoint down below and the Captions iOS app or provided thumbnails for their likeness.

mediaUrls - required - Must contain at least one media URL and up to ten URLs. Currently supported formats are JPEG, PNG, MOV and MP4. If you’d like to make a creator video without any media, please refer to our AI Creator API.

webhookId - optional - Unique ID for a registered webhook to be used as a callback for any enabled events.

Bash script
curl -X POST https://api.captions.ai/api/ads/submit -H "Content-Type: application/json" -H "x-api-key: <api-key>" -d '{"creatorName": "<creator-name>", "script": "<script>", "mediaUrls": ["media-url-1", "media-url-2", ...]}'

Response Types

​
/poll

Check the status of an AI Ads video generation.

Request

We recommend polling first after 30 seconds, and every 5 seconds thereafter.

Bash script
curl -X POST https://api.captions.ai/api/ads/poll -H "Content-Type: application/json" -H "x-api-key: <api-key>" -H "x-operation-id: <operation-id>"

Response Types

Was this page helpful?

AI Translate APIAI Edit API