> ## Documentation Index
> Fetch the complete documentation index at: https://docs.turboads.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> Getting started with the TurboAds Public API.

## Authentication

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

```http theme={null}
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

```text theme={null}
https://api.turboads.ai
```

All v1 endpoints are rooted under `/v1`.

## Discovery endpoints

Use these endpoints to find IDs before creating generation jobs:

```text theme={null}
GET /v1/projects
GET /v1/actors
GET /v1/voices
```

## File uploads

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

```text theme={null}
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:

```json theme={null}
{
  "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

```bash theme={null}
curl "https://api.turboads.ai/v1/projects" \
  -H "Authorization: Bearer $TURBOADS_API_KEY"
```

### Generate an image

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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"
```