API Overview

Authentication

TurboAds API keys are workspace-scoped bearer tokens. Create a key in Settings > Developers, then send it in the Authorization header:

Authorization: Bearer ta_live_...

Only workspace owners can create or revoke keys. TurboAds stores only a SHA-256 hash of each key, and the full secret is shown once when created. Revoked keys stop working immediately and return 401 unauthorized.

Base URL

https://api.turboads.ai

All v1 endpoints are rooted under /v1.

Discovery endpoints

Use these endpoints to find IDs before creating generation jobs:

GET /v1/projects
GET /v1/actors
GET /v1/voices

File uploads

Use file uploads when a generation needs an image or video reference.

POST /v1/upload
POST /v1/upload-from-url

Then pass the returned file upload ID into a generation request, such as reference_file_ids, start_frame_file_id, end_frame_file_id, image_file_id, or video_file_id. Images can be up to 10MB. Videos uploaded from URL can be up to 50MB. Direct multipart uploads are limited to 20MB by Convex HTTP action limits. Accepted MIME types:

Type	MIME types
Images	`image/jpeg`, `image/png`, `image/webp`
Videos	`video/mp4`, `video/quicktime`, `video/webm`

Rate limits

Rate limits are applied per API key.

Endpoint type	Limit
Discovery and polling	`120` requests per minute
Generation	`30` requests per minute

When a key exceeds its limit, TurboAds returns 429 rate_limited with retry_after_ms.

Errors

TurboAds returns JSON errors with a stable shape:

{
  "error": {
    "code": "invalid_request",
    "message": "project_id, prompt, model, aspect_ratio, and count are required."
  }
}

Common status codes:

HTTP status	Code	Meaning
`400`	`invalid_request`	Required fields are missing or malformed.
`400`	`invalid_model`	The selected model is not supported by the endpoint.
`401`	`unauthorized`	API key is missing, invalid, or revoked.
`402`	`insufficient_credits`	The workspace does not have enough credits for the requested generation.
`403`	`forbidden`	The requested project is outside the key’s workspace.
`404`	`not_found`	The resource does not exist or is not visible to the key.
`409`	`not_ready`	The final media URL is not ready yet.
`409`	`generation_failed`	The generation failed.
`429`	`rate_limited`	The API key has exceeded its rate limit.
`500`	`internal_error`	TurboAds could not complete the request.

Examples

List projects

curl "https://api.turboads.ai/v1/projects" \
  -H "Authorization: Bearer $TURBOADS_API_KEY"

Generate an image

curl "https://api.turboads.ai/v1/images/generate" \
  -H "Authorization: Bearer $TURBOADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "PROJECT_ID",
    "prompt": "A cinematic product photo of a skincare bottle on a marble counter",
    "model": "nano-banana-2",
    "aspect_ratio": "1:1",
    "count": 1
  }'

Upload a reference file

curl "https://api.turboads.ai/v1/upload" \
  -H "Authorization: Bearer $TURBOADS_API_KEY" \
  -F "file=@reference.png" \
  -F "project_id=PROJECT_ID"

Upload from URL

curl "https://api.turboads.ai/v1/upload-from-url" \
  -H "Authorization: Bearer $TURBOADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/reference.png",
    "project_id": "PROJECT_ID"
  }'

Poll and fetch the final URL

curl "https://api.turboads.ai/v1/images/IMAGE_ID" \
  -H "Authorization: Bearer $TURBOADS_API_KEY"

curl "https://api.turboads.ai/v1/images/IMAGE_ID/url" \
  -H "Authorization: Bearer $TURBOADS_API_KEY"

Overview

Projects

Voices

Actors

Uploads

Image Generation

Video Generation

Replace Actors

Talking Actors

Authentication

Base URL

Discovery endpoints

File uploads

Rate limits

Errors

Examples

List projects

Generate an image

Upload a reference file

Upload from URL

Poll and fetch the final URL

​Authentication

​Base URL

​Discovery endpoints

​File uploads

​Rate limits

​Errors

​Examples

​List projects

​Generate an image

​Upload a reference file

​Upload from URL

​Poll and fetch the final URL

Authentication

Base URL

Discovery endpoints

File uploads

Rate limits

Errors

Examples

List projects

Generate an image

Upload a reference file

Upload from URL

Poll and fetch the final URL