Home
Developers
API reference

Reference

API reference

All 57 endpoints of the Azimo REST API with parameters, request bodies, response fields and a curl example, generated from the live API definition.

> This is the Markdown version of the Azimo developer docs page "API reference", for use by an AI assistant.
> - Azimo (https://azimo.ai) is an AI business-video production service: a brief and a few files in, a QA-checked commercial video out. It offers an asynchronous REST API, Python and TypeScript SDKs, the azimo command line and an MCP server.
> - Base URL: https://azimo.ai
> - Auth: every /v1 request sends `Authorization: Bearer <API key>` (create a key at https://azimo.ai/console#account); `X-Project-ID` selects a project, the default project otherwise.
> - This page: https://azimo.ai/en/developers/api
> - Prices are not published: contact sales@azimo.ai.

# API reference

Parameters, request body, response fields and a curl example for every endpoint, generated from the live API definition.

## Basics

- **Base URL**: `https://azimo.ai`
- **Authentication**: Every `/v1` request sends `Authorization: Bearer <API key>`. Create a key in [your account](https://azimo.ai/console#account); the raw key is shown only once.
- **Projects**: `X-Project-ID` selects a project; the default project is used when it is omitted.
- **Idempotency**: Send an `Idempotency-Key` with requests that create something and reuse it when retrying; the same value with a different request returns 409.
- **Asynchronous jobs**: `POST /v1/videos` returns 202 and a video id; poll `GET /v1/videos/{job_id}` or receive a webhook. `needs_input` means something is missing, not that the video is done.
- **Pagination**: Lists return `data`, `next_cursor` and `has_more`; pass `next_cursor` as `cursor` to get the next page.
- **Pricing**: The API never returns prices. For a quote, contact sales@azimo.ai.

### Errors

| Name | Type | Required | Description |
|---|---|---|---|
| `error` | object | yes |  |
| `error.code` | string | yes | Stable machine-readable code, e.g. unauthenticated, not_found, idempotency_conflict, validation_error, rate_limited, insufficient_balance, budget_exceeded, contact_sales, internal_error |
| `error.message` | string | yes |  |
| `error.details` | any |  | Structured context: validation errors, unmet workflow requirements, or null |
| `error.request_id` | string | yes | nullable |

- `401` Missing or invalid bearer key (`WWW-Authenticate: Bearer`)
- `402` Wallet balance or spending limit would be exceeded
- `403` Key role or project scope does not allow this; `contact_sales` for anything about pricing
- `404` Resource not found in this organization/project
- `409` State conflict, or Idempotency-Key reused with a different request
- `422` Validation error; `details` lists the failing fields or requirements
- `429` Hourly limit reached (`Retry-After` in seconds)
- `500` Unexpected failure; cite `request_id` when reporting it

## Account and capabilities

Who the current key is, and which workflows and video types are available.

### GET /v1/me — Me

Requires an API key. Success: 200.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Response 200**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `key_id` | string | yes | Same as `id` |
| `organization_id` | string | yes |  |
| `project_id` | string | yes |  |
| `role` | string | yes | One of: `owner` `editor` `viewer` |
| `billing_mode` | string | yes | One of: `budget` `prepaid` |
| `wallet` | object | yes |  |
| `permissions` | map<string, boolean> | yes |  |

```bash
curl "https://azimo.ai/v1/me" \
  -H "Authorization: Bearer $AZIMO_API_KEY"
```

### GET /v1/workflows — Workflows

Requires an API key. Success: 200.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Response 200**

| Name | Type | Required | Description |
|---|---|---|---|
| `router` | object | yes |  |
| `workflows` | map<string, object> | yes |  |

```bash
curl "https://azimo.ai/v1/workflows" \
  -H "Authorization: Bearer $AZIMO_API_KEY"
```

### GET /v1/workflows/creative_video/skills — Video Skills

Requires an API key. Success: 200.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Response 200**

| Name | Type | Required | Description |
|---|---|---|---|
| `data` | array<any> | yes |  |

```bash
curl "https://azimo.ai/v1/workflows/creative_video/skills" \
  -H "Authorization: Bearer $AZIMO_API_KEY"
```

### GET /v1/video-types — Video Types

Requires an API key. Success: 200.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `lang` (query) | string |  | Display language, `zh` (default) or `en`; when absent the first `zh`/`en` entry of `Accept-Language` is used; length ≤ 16; nullable |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |
| `accept-language` (header) | string |  | nullable |

**Response 200**

| Name | Type | Required | Description |
|---|---|---|---|
| `data` | array<object> | yes |  |
| `data[].id` | string | yes |  |
| `data[].version` | any | yes |  |
| `data[].template` | any |  |  |
| `next_cursor` | string |  | Opaque; pass as `cursor` (or the `after` alias) for the next page; nullable |
| `has_more` | boolean |  | Default `false` |

```bash
curl "https://azimo.ai/v1/video-types" \
  -H "Authorization: Bearer $AZIMO_API_KEY"
```

### GET /v1/playground — Playground

Requires an API key. Success: 200.

The workflow gallery: seven fixed entries, each with routing values, whether this account can start it now, and a runnable example.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `lang` (query) | string |  | Display language, `zh` (default) or `en`; when absent the first `zh`/`en` entry of `Accept-Language` is used; length ≤ 16; nullable |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |
| `accept-language` (header) | string |  | nullable |

**Response 200**

| Name | Type | Required | Description |
|---|---|---|---|
| `data` | array<object> | yes |  |
| `data[].id` | string | yes | Stable catalogue id |
| `data[].name` | string | yes |  |
| `data[].summary` | string | yes | One benefit-oriented sentence |
| `data[].workflow` | string | yes | Backend routing value for `options.workflow`; null when the entry cannot be started yet; nullable |
| `data[].video_type` | string | yes | `options.video_type` for structured explainers, otherwise null; nullable |
| `data[].aspect` | string | yes | One of: `16:9` `9:16` `1:1` |
| `data[].duration` | integer | yes | Default `options.duration_max` in seconds |
| `data[].duration_range` | array<integer> | yes | [minimum, maximum] seconds the workflow accepts |
| `data[].needs_assets` | boolean | yes | Reference material (photos, product pictures) is strongly recommended |
| `data[].available` | boolean | yes |  |
| `data[].reason` | string | yes | Why `available` is false: coming_soon, not_configured (this environment) or contact_sales (not sold to this account); One of: `coming_soon` `not_configured` `contact_sales`; nullable |
| `data[].coming_soon` | boolean | yes |  |
| `data[].example` | object | yes |  |
| `data[].example.prompt` | string | yes | A ready-to-run creative brief for `POST /v1/videos` or `POST /v1/plans` |
| `data[].example.content_data` | map<string, string> | yes | Sample value for every input of the workflow's video type (`options.content_data`); empty when the workflow has none |

```bash
curl "https://azimo.ai/v1/playground" \
  -H "Authorization: Bearer $AZIMO_API_KEY"
```

## Assets

Upload PDFs, slides and pictures; reference the returned asset ids in a plan.

### GET /v1/assets — List Assets

Requires an API key. Success: 200.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `limit` (query) | integer |  | Default `50`; range 1–200 |
| `cursor` (query) | string |  | length ≤ 256; nullable |
| `after` (query) | string |  | length ≤ 256; nullable |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Response 200**

| Name | Type | Required | Description |
|---|---|---|---|
| `data` | array<object> | yes |  |
| `data[].id` | string | yes |  |
| `data[].project_id` | string | yes | nullable |
| `data[].filename` | string | yes |  |
| `data[].bytes` | integer | yes |  |
| `data[].sha256` | string | yes |  |
| `data[].created_at` | number | yes |  |
| `next_cursor` | string |  | Opaque; pass as `cursor` (or the `after` alias) for the next page; nullable |
| `has_more` | boolean |  | Default `false` |

```bash
curl "https://azimo.ai/v1/assets" \
  -H "Authorization: Bearer $AZIMO_API_KEY"
```

### POST /v1/assets — Upload Asset

Requires an API key. Success: 201.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `Idempotency-Key` (header) | string |  | A unique value you generate and keep; reuse it when retrying so the request never runs twice; length 1–128; nullable |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Request body** (multipart/form-data)

| Name | Type | Required | Description |
|---|---|---|---|
| `file` | file | yes |  |

**Response 201**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `project_id` | string | yes | nullable |
| `filename` | string | yes |  |
| `bytes` | integer | yes |  |
| `sha256` | string | yes |  |
| `created_at` | number | yes |  |

```bash
curl -X POST "https://azimo.ai/v1/assets" \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "file=@deck.pdf"
```

### GET /v1/assets/{asset_id} — Get Asset

Requires an API key. Success: 200.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `asset_id` (path) | string | yes |  |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Response 200**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `project_id` | string | yes | nullable |
| `filename` | string | yes |  |
| `bytes` | integer | yes |  |
| `sha256` | string | yes |  |
| `created_at` | number | yes |  |

```bash
curl "https://azimo.ai/v1/assets/<asset_id>" \
  -H "Authorization: Bearer $AZIMO_API_KEY"
```

### DELETE /v1/assets/{asset_id} — Delete Asset

Requires an API key. Success: 200.

Remove an upload and its bytes. Jobs that already consumed it keep their own copies.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `asset_id` (path) | string | yes |  |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Response 200**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `deleted` | boolean |  | Default `true` |

```bash
curl -X DELETE "https://azimo.ai/v1/assets/<asset_id>" \
  -H "Authorization: Bearer $AZIMO_API_KEY"
```

### GET /v1/assets/{asset_id}/file — Download Asset

Requires an API key. Success: 200.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `asset_id` (path) | string | yes |  |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

```bash
curl "https://azimo.ai/v1/assets/<asset_id>/file" \
  -H "Authorization: Bearer $AZIMO_API_KEY"
```

## Plans

Plan before producing: workflow, specs, assets and structure are frozen and anything missing is reported.

### GET /v1/plans — List Plans

Requires an API key. Success: 200.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `limit` (query) | integer |  | Default `50`; range 1–200 |
| `cursor` (query) | string |  | length ≤ 256; nullable |
| `after` (query) | string |  | length ≤ 256; nullable |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Response 200**

| Name | Type | Required | Description |
|---|---|---|---|
| `data` | array<object> | yes |  |
| `data[].id` | string | yes |  |
| `data[].project_id` | string | yes | nullable |
| `data[].kind` | string | yes |  |
| `data[].name` | string | yes |  |
| `data[].version` | integer | yes |  |
| `data[].created_at` | number | yes |  |
| `data[].updated_at` | number | yes |  |
| `data[].data` | object | yes |  |
| `data[].data.status` | string | yes | One of: `planning` `ready` `needs_input` `unavailable` |
| `data[].data.request` | object | yes |  |
| `data[].data.assets` | array<object> |  |  |
| `data[].data.routing` | object |  | nullable |
| `data[].data.requirements` | array<object> |  |  |
| `data[].data.reason` | string |  | nullable |
| `data[].data.job_id` | string |  | The production this plan started; a plan starts at most one; nullable |
| `next_cursor` | string |  | Opaque; pass as `cursor` (or the `after` alias) for the next page; nullable |
| `has_more` | boolean |  | Default `false` |

```bash
curl "https://azimo.ai/v1/plans" \
  -H "Authorization: Bearer $AZIMO_API_KEY"
```

### POST /v1/plans — Create Plan

Requires an API key. Success: 201.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `Idempotency-Key` (header) | string |  | A unique value you generate and keep; reuse it when retrying so the request never runs twice; length 1–128; nullable |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Request body** (application/json)

| Name | Type | Required | Description |
|---|---|---|---|
| `prompt` | string |  | length ≤ 4000 |
| `assets` | array<string> |  | up to 30 items |
| `options` | object |  |  |
| `options.workflow` | string |  | One of: `auto` `explainer` `short_drama` `creative_video` `motion_explainer` `profile_card` `product_pitch`; Default `explainer` |
| `options.goal` | string |  | length ≤ 2000 |
| `options.audience` | string |  | length ≤ 1000 |
| `options.duration_max` | integer |  | Default `60`; range 5–180 |
| `options.width` | integer |  | Default `1920`; range 640–3840 |
| `options.height` | integer |  | Default `1080`; range 360–2160 |
| `options.fps` | integer |  | Default `30`; range 24–60 |
| `options.subtitles` | boolean |  | Default `false` |
| `options.music` | boolean |  | Default `true` |
| `options.skill_id` | string |  | length ≤ 200; nullable |
| `options.credit_budget` | integer |  | range 1–1000000; nullable |
| `options.video_type` | string |  | One of: `project` `product` `personal` `corporate`; nullable |
| `options.content_data` | map<string, string> |  |  |
| `options.style_preset` | string |  | One of: `cinematic_realism` `clean_3d` `product_studio`; Default `cinematic_realism` |
| `options.brand` | object |  |  |
| `options.motion_style` | string |  | One of: `mono` `photo`; Default `mono` |
| `options.photo_subject` | string |  | length ≤ 120 |
| `options.photo_license` | string |  | One of: `strict` `sharealike`; Default `strict` |
| `webhook_url` | string |  | length ≤ 2000; nullable |
| `plan_id` | string |  | nullable |
| `template_id` | string |  | nullable |
| `brand_id` | string |  | nullable |
| `variables` | map<string, string> |  |  |

**Response 201**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `project_id` | string | yes | nullable |
| `kind` | string | yes |  |
| `name` | string | yes |  |
| `version` | integer | yes |  |
| `created_at` | number | yes |  |
| `updated_at` | number | yes |  |
| `data` | object | yes |  |
| `data.status` | string | yes | One of: `planning` `ready` `needs_input` `unavailable` |
| `data.request` | object | yes |  |
| `data.assets` | array<object> |  |  |
| `data.routing` | object |  | nullable |
| `data.requirements` | array<object> |  |  |
| `data.reason` | string |  | nullable |
| `data.job_id` | string |  | The production this plan started; a plan starts at most one; nullable |

```bash
curl -X POST "https://azimo.ai/v1/plans" \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "<prompt>", "assets": ["<asset id>"]}'
```

### GET /v1/plans/{plan_id} — Get Plan

Requires an API key. Success: 200.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `plan_id` (path) | string | yes |  |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Response 200**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `project_id` | string | yes | nullable |
| `kind` | string | yes |  |
| `name` | string | yes |  |
| `version` | integer | yes |  |
| `created_at` | number | yes |  |
| `updated_at` | number | yes |  |
| `data` | object | yes |  |
| `data.status` | string | yes | One of: `planning` `ready` `needs_input` `unavailable` |
| `data.request` | object | yes |  |
| `data.assets` | array<object> |  |  |
| `data.routing` | object |  | nullable |
| `data.requirements` | array<object> |  |  |
| `data.reason` | string |  | nullable |
| `data.job_id` | string |  | The production this plan started; a plan starts at most one; nullable |

```bash
curl "https://azimo.ai/v1/plans/<plan_id>" \
  -H "Authorization: Bearer $AZIMO_API_KEY"
```

### POST /v1/route — Preview Route

Requires an API key. Success: 200.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `Idempotency-Key` (header) | string |  | A unique value you generate and keep; reuse it when retrying so the request never runs twice; length 1–128; nullable |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Request body** (application/json)

| Name | Type | Required | Description |
|---|---|---|---|
| `prompt` | string |  | length ≤ 4000 |
| `assets` | array<string> |  | up to 30 items |
| `options` | object |  |  |
| `options.workflow` | string |  | One of: `auto` `explainer` `short_drama` `creative_video` `motion_explainer` `profile_card` `product_pitch`; Default `explainer` |
| `options.goal` | string |  | length ≤ 2000 |
| `options.audience` | string |  | length ≤ 1000 |
| `options.duration_max` | integer |  | Default `60`; range 5–180 |
| `options.width` | integer |  | Default `1920`; range 640–3840 |
| `options.height` | integer |  | Default `1080`; range 360–2160 |
| `options.fps` | integer |  | Default `30`; range 24–60 |
| `options.subtitles` | boolean |  | Default `false` |
| `options.music` | boolean |  | Default `true` |
| `options.skill_id` | string |  | length ≤ 200; nullable |
| `options.credit_budget` | integer |  | range 1–1000000; nullable |
| `options.video_type` | string |  | One of: `project` `product` `personal` `corporate`; nullable |
| `options.content_data` | map<string, string> |  |  |
| `options.style_preset` | string |  | One of: `cinematic_realism` `clean_3d` `product_studio`; Default `cinematic_realism` |
| `options.brand` | object |  |  |
| `options.motion_style` | string |  | One of: `mono` `photo`; Default `mono` |
| `options.photo_subject` | string |  | length ≤ 120 |
| `options.photo_license` | string |  | One of: `strict` `sharealike`; Default `strict` |
| `webhook_url` | string |  | length ≤ 2000; nullable |
| `plan_id` | string |  | nullable |
| `template_id` | string |  | nullable |
| `brand_id` | string |  | nullable |
| `variables` | map<string, string> |  |  |

**Response 200**

| Name | Type | Required | Description |
|---|---|---|---|
| `plan_id` | string | yes |  |
| `workflow` | string |  | nullable |
| `requirements` | array<object> |  |  |

```bash
curl -X POST "https://azimo.ai/v1/route" \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "<prompt>", "assets": ["<asset id>"]}'
```

## Videos

Produce a video from a confirmed plan, follow its progress, download it, resume, revise or cancel it.

### GET /v1/videos — List Videos

Requires an API key. Success: 200.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `limit` (query) | integer |  | Default `50`; range 1–200 |
| `cursor` (query) | string |  | length ≤ 256; nullable |
| `after` (query) | string |  | length ≤ 256; nullable |
| `status` (query) | string |  | One of: `queued` `running` `needs_input` `complete` `rejected` `failed` `cancelled`; nullable |
| `batch_id` (query) | string |  | length ≤ 32; nullable |
| `created_after` (query) | number |  | range ≥ 0; nullable |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Response 200**

| Name | Type | Required | Description |
|---|---|---|---|
| `data` | array<object> | yes |  |
| `data[].id` | string | yes |  |
| `data[].project_id` | string | yes | nullable |
| `data[].batch_id` | string |  | nullable |
| `data[].parent_id` | string |  | nullable |
| `data[].status` | string | yes | One of: `queued` `running` `needs_input` `complete` `rejected` `failed` `cancelled` |
| `data[].stage` | string | yes | nullable |
| `data[].progress` | integer | yes | nullable |
| `data[].error` | string |  | nullable |
| `data[].created_at` | number | yes | nullable |
| `data[].updated_at` | number |  | nullable |
| `data[].started_at` | number |  | nullable |
| `data[].finished_at` | number |  | nullable |
| `data[].deleted_at` | number |  | nullable |
| `data[].recovery` | object | yes |  |
| `data[].recovery.attempt` | integer | yes |  |
| `data[].recovery.max_attempts` | integer | yes |  |
| `data[].recovery.retry_at` | number |  | nullable |
| `data[].result` | object |  | nullable |
| `data[].result.files` | map<string, string> |  | Signed download links; present on GET once complete/rejected; nullable |
| `data[].result.duration` | number |  | nullable |
| `data[].result.shot_count` | integer |  | nullable |
| `data[].result.visual_mix` | any |  |  |
| `data[].result.qa` | any |  |  |
| `data[].result.brief` | any |  |  |
| `data[].result.workflow` | string |  | nullable |
| `data[].result.routing` | any |  |  |
| `data[].result.input_required` | object |  | Why the job is `needs_input`: `code`, `actor`, `message` and what to send to /resume. A spending stop has `code: budget_approval` and `approvable: true` and carries no amounts; answer it with `POST /v1/videos/{id}/resume {"approve_budget": true}`; nullable |
| `data[].result.native_project` | any |  |  |
| `data[].requested_workflow` | string | yes |  |
| `next_cursor` | string |  | Opaque; pass as `cursor` (or the `after` alias) for the next page; nullable |
| `has_more` | boolean |  | Default `false` |

```bash
curl "https://azimo.ai/v1/videos" \
  -H "Authorization: Bearer $AZIMO_API_KEY"
```

### POST /v1/videos — Create Video

Requires an API key. Success: 202.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `Idempotency-Key` (header) | string |  | A unique value you generate and keep; reuse it when retrying so the request never runs twice; length 1–128; nullable |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Request body** (application/json)

| Name | Type | Required | Description |
|---|---|---|---|
| `prompt` | string |  | length ≤ 4000 |
| `assets` | array<string> |  | up to 30 items |
| `options` | object |  |  |
| `options.workflow` | string |  | One of: `auto` `explainer` `short_drama` `creative_video` `motion_explainer` `profile_card` `product_pitch`; Default `explainer` |
| `options.goal` | string |  | length ≤ 2000 |
| `options.audience` | string |  | length ≤ 1000 |
| `options.duration_max` | integer |  | Default `60`; range 5–180 |
| `options.width` | integer |  | Default `1920`; range 640–3840 |
| `options.height` | integer |  | Default `1080`; range 360–2160 |
| `options.fps` | integer |  | Default `30`; range 24–60 |
| `options.subtitles` | boolean |  | Default `false` |
| `options.music` | boolean |  | Default `true` |
| `options.skill_id` | string |  | length ≤ 200; nullable |
| `options.credit_budget` | integer |  | range 1–1000000; nullable |
| `options.video_type` | string |  | One of: `project` `product` `personal` `corporate`; nullable |
| `options.content_data` | map<string, string> |  |  |
| `options.style_preset` | string |  | One of: `cinematic_realism` `clean_3d` `product_studio`; Default `cinematic_realism` |
| `options.brand` | object |  |  |
| `options.motion_style` | string |  | One of: `mono` `photo`; Default `mono` |
| `options.photo_subject` | string |  | length ≤ 120 |
| `options.photo_license` | string |  | One of: `strict` `sharealike`; Default `strict` |
| `webhook_url` | string |  | length ≤ 2000; nullable |
| `plan_id` | string |  | nullable |
| `template_id` | string |  | nullable |
| `brand_id` | string |  | nullable |
| `variables` | map<string, string> |  |  |

**Response 202**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `project_id` | string | yes | nullable |
| `batch_id` | string |  | nullable |
| `parent_id` | string |  | nullable |
| `status` | string | yes | One of: `queued` `running` `needs_input` `complete` `rejected` `failed` `cancelled` |
| `stage` | string | yes | nullable |
| `progress` | integer | yes | nullable |
| `error` | string |  | nullable |
| `created_at` | number | yes | nullable |
| `updated_at` | number |  | nullable |
| `started_at` | number |  | nullable |
| `finished_at` | number |  | nullable |
| `deleted_at` | number |  | nullable |
| `recovery` | object | yes |  |
| `recovery.attempt` | integer | yes |  |
| `recovery.max_attempts` | integer | yes |  |
| `recovery.retry_at` | number |  | nullable |
| `result` | object |  | nullable |
| `result.files` | map<string, string> |  | Signed download links; present on GET once complete/rejected; nullable |
| `result.duration` | number |  | nullable |
| `result.shot_count` | integer |  | nullable |
| `result.visual_mix` | any |  |  |
| `result.qa` | any |  |  |
| `result.brief` | any |  |  |
| `result.workflow` | string |  | nullable |
| `result.routing` | any |  |  |
| `result.input_required` | object |  | Why the job is `needs_input`: `code`, `actor`, `message` and what to send to /resume. A spending stop has `code: budget_approval` and `approvable: true` and carries no amounts; answer it with `POST /v1/videos/{id}/resume {"approve_budget": true}`; nullable |
| `result.native_project` | any |  |  |
| `requested_workflow` | string | yes |  |
| `webhook_signing_secret` | string |  | Only present when the request set `webhook_url`: the project secret that signs that per-job callback (`Vidgen-Signature`). Store it; verify deliveries with it; nullable |

```bash
curl -X POST "https://azimo.ai/v1/videos" \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "<prompt>", "assets": ["<asset id>"]}'
```

### POST /v1/videos/{job_id}/resume — Resume

Requires an API key. Success: 202.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `job_id` (path) | string | yes |  |
| `Idempotency-Key` (header) | string |  | A unique value you generate and keep; reuse it when retrying so the request never runs twice; length 1–128; nullable |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Request body** (application/json)

| Name | Type | Required | Description |
|---|---|---|---|
| `message` | string |  | length ≤ 4000 |
| `questionnaire_id` | string |  | length ≤ 200; nullable |
| `answers` | array<object> |  | up to 30 items |
| `assets` | array<string> |  | up to 9 items |
| `approve_budget` | boolean |  | Approve the pending budget stop; the server computes the new limit; Default `false` |
| `credit_budget` | integer |  | Legacy: explicit new Vikoo credit budget for a credit budget stop; range 1–1000000; nullable |
| `budget_usd` | number |  | Legacy: explicit new total USD limit for a budget stop; range 0–100000; nullable |

**Response 202**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `project_id` | string | yes | nullable |
| `batch_id` | string |  | nullable |
| `parent_id` | string |  | nullable |
| `status` | string | yes | One of: `queued` `running` `needs_input` `complete` `rejected` `failed` `cancelled` |
| `stage` | string | yes | nullable |
| `progress` | integer | yes | nullable |
| `error` | string |  | nullable |
| `created_at` | number | yes | nullable |
| `updated_at` | number |  | nullable |
| `started_at` | number |  | nullable |
| `finished_at` | number |  | nullable |
| `deleted_at` | number |  | nullable |
| `recovery` | object | yes |  |
| `recovery.attempt` | integer | yes |  |
| `recovery.max_attempts` | integer | yes |  |
| `recovery.retry_at` | number |  | nullable |
| `result` | object |  | nullable |
| `result.files` | map<string, string> |  | Signed download links; present on GET once complete/rejected; nullable |
| `result.duration` | number |  | nullable |
| `result.shot_count` | integer |  | nullable |
| `result.visual_mix` | any |  |  |
| `result.qa` | any |  |  |
| `result.brief` | any |  |  |
| `result.workflow` | string |  | nullable |
| `result.routing` | any |  |  |
| `result.input_required` | object |  | Why the job is `needs_input`: `code`, `actor`, `message` and what to send to /resume. A spending stop has `code: budget_approval` and `approvable: true` and carries no amounts; answer it with `POST /v1/videos/{id}/resume {"approve_budget": true}`; nullable |
| `result.native_project` | any |  |  |
| `requested_workflow` | string | yes |  |

```bash
curl -X POST "https://azimo.ai/v1/videos/<job_id>/resume" \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"message": "<message>", "questionnaire_id": "<questionnaire_id>"}'
```

### POST /v1/videos/{job_id}/revisions — Revise Video

Requires an API key. Success: 202.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `job_id` (path) | string | yes |  |
| `Idempotency-Key` (header) | string |  | A unique value you generate and keep; reuse it when retrying so the request never runs twice; length 1–128; nullable |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Request body** (application/json)

| Name | Type | Required | Description |
|---|---|---|---|
| `prompt` | string |  | length 10–4000; nullable |
| `assets` | array<string> |  | up to 30 items; nullable |
| `options` | object |  |  |
| `options.workflow` | string |  | One of: `auto` `explainer` `short_drama` `creative_video` `motion_explainer` `profile_card` `product_pitch`; Default `explainer` |
| `options.goal` | string |  | length ≤ 2000 |
| `options.audience` | string |  | length ≤ 1000 |
| `options.duration_max` | integer |  | Default `60`; range 5–180 |
| `options.width` | integer |  | Default `1920`; range 640–3840 |
| `options.height` | integer |  | Default `1080`; range 360–2160 |
| `options.fps` | integer |  | Default `30`; range 24–60 |
| `options.subtitles` | boolean |  | Default `false` |
| `options.music` | boolean |  | Default `true` |
| `options.skill_id` | string |  | length ≤ 200; nullable |
| `options.credit_budget` | integer |  | range 1–1000000; nullable |
| `options.video_type` | string |  | One of: `project` `product` `personal` `corporate`; nullable |
| `options.content_data` | map<string, string> |  |  |
| `options.style_preset` | string |  | One of: `cinematic_realism` `clean_3d` `product_studio`; Default `cinematic_realism` |
| `options.brand` | object |  |  |
| `options.motion_style` | string |  | One of: `mono` `photo`; Default `mono` |
| `options.photo_subject` | string |  | length ≤ 120 |
| `options.photo_license` | string |  | One of: `strict` `sharealike`; Default `strict` |

**Response 202**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `project_id` | string | yes | nullable |
| `batch_id` | string |  | nullable |
| `parent_id` | string |  | nullable |
| `status` | string | yes | One of: `queued` `running` `needs_input` `complete` `rejected` `failed` `cancelled` |
| `stage` | string | yes | nullable |
| `progress` | integer | yes | nullable |
| `error` | string |  | nullable |
| `created_at` | number | yes | nullable |
| `updated_at` | number |  | nullable |
| `started_at` | number |  | nullable |
| `finished_at` | number |  | nullable |
| `deleted_at` | number |  | nullable |
| `recovery` | object | yes |  |
| `recovery.attempt` | integer | yes |  |
| `recovery.max_attempts` | integer | yes |  |
| `recovery.retry_at` | number |  | nullable |
| `result` | object |  | nullable |
| `result.files` | map<string, string> |  | Signed download links; present on GET once complete/rejected; nullable |
| `result.duration` | number |  | nullable |
| `result.shot_count` | integer |  | nullable |
| `result.visual_mix` | any |  |  |
| `result.qa` | any |  |  |
| `result.brief` | any |  |  |
| `result.workflow` | string |  | nullable |
| `result.routing` | any |  |  |
| `result.input_required` | object |  | Why the job is `needs_input`: `code`, `actor`, `message` and what to send to /resume. A spending stop has `code: budget_approval` and `approvable: true` and carries no amounts; answer it with `POST /v1/videos/{id}/resume {"approve_budget": true}`; nullable |
| `result.native_project` | any |  |  |
| `requested_workflow` | string | yes |  |
| `webhook_signing_secret` | string |  | Only present when the request set `webhook_url`: the project secret that signs that per-job callback (`Vidgen-Signature`). Store it; verify deliveries with it; nullable |

```bash
curl -X POST "https://azimo.ai/v1/videos/<job_id>/revisions" \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "<prompt>", "assets": ["<asset id>"]}'
```

### GET /v1/videos/{job_id} — Get Video

Requires an API key. Success: 200.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `job_id` (path) | string | yes |  |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Response 200**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `project_id` | string | yes | nullable |
| `batch_id` | string |  | nullable |
| `parent_id` | string |  | nullable |
| `status` | string | yes | One of: `queued` `running` `needs_input` `complete` `rejected` `failed` `cancelled` |
| `stage` | string | yes | nullable |
| `progress` | integer | yes | nullable |
| `error` | string |  | nullable |
| `created_at` | number | yes | nullable |
| `updated_at` | number |  | nullable |
| `started_at` | number |  | nullable |
| `finished_at` | number |  | nullable |
| `deleted_at` | number |  | nullable |
| `recovery` | object | yes |  |
| `recovery.attempt` | integer | yes |  |
| `recovery.max_attempts` | integer | yes |  |
| `recovery.retry_at` | number |  | nullable |
| `result` | object |  | nullable |
| `result.files` | map<string, string> |  | Signed download links; present on GET once complete/rejected; nullable |
| `result.duration` | number |  | nullable |
| `result.shot_count` | integer |  | nullable |
| `result.visual_mix` | any |  |  |
| `result.qa` | any |  |  |
| `result.brief` | any |  |  |
| `result.workflow` | string |  | nullable |
| `result.routing` | any |  |  |
| `result.input_required` | object |  | Why the job is `needs_input`: `code`, `actor`, `message` and what to send to /resume. A spending stop has `code: budget_approval` and `approvable: true` and carries no amounts; answer it with `POST /v1/videos/{id}/resume {"approve_budget": true}`; nullable |
| `result.native_project` | any |  |  |
| `requested_workflow` | string | yes |  |

```bash
curl "https://azimo.ai/v1/videos/<job_id>" \
  -H "Authorization: Bearer $AZIMO_API_KEY"
```

### DELETE /v1/videos/{job_id} — Delete Video

Requires an API key. Success: 200.

Purge a finished job's films, uploads copies and diagnostics; the job record stays for usage history.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `job_id` (path) | string | yes |  |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Response 200**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `deleted` | boolean |  | Default `true` |

```bash
curl -X DELETE "https://azimo.ai/v1/videos/<job_id>" \
  -H "Authorization: Bearer $AZIMO_API_KEY"
```

### POST /v1/videos/{job_id}/cancel — Cancel Video

Requires an API key. Success: 200.

queued / needs_input jobs cancel at once; a running job stops before its next paid step (`cancelling`).

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `job_id` (path) | string | yes |  |
| `Idempotency-Key` (header) | string |  | A unique value you generate and keep; reuse it when retrying so the request never runs twice; length 1–128; nullable |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Response 200**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `status` | string | yes | One of: `cancelled` `cancelling` |

```bash
curl -X POST "https://azimo.ai/v1/videos/<job_id>/cancel" \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

### GET /v1/videos/{job_id}/files/{name} — Get File

Signed link; no key. Success: 200.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `job_id` (path) | string | yes |  |
| `name` (path) | string | yes |  |
| `expires` (query) | integer | yes |  |
| `sig` (query) | string | yes |  |

```bash
curl "https://azimo.ai/v1/videos/<job_id>/files/<name>?expires=<expires>&sig=<sig>"
```

## Batches

Submit several videos at once.

### GET /v1/batches — List Batches

Requires an API key. Success: 200.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `limit` (query) | integer |  | Default `50`; range 1–200 |
| `cursor` (query) | string |  | length ≤ 256; nullable |
| `after` (query) | string |  | length ≤ 256; nullable |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Response 200**

| Name | Type | Required | Description |
|---|---|---|---|
| `data` | array<object> | yes |  |
| `data[].id` | string | yes |  |
| `data[].name` | string | yes |  |
| `data[].created_at` | number | yes |  |
| `next_cursor` | string |  | Opaque; pass as `cursor` (or the `after` alias) for the next page; nullable |
| `has_more` | boolean |  | Default `false` |

```bash
curl "https://azimo.ai/v1/batches" \
  -H "Authorization: Bearer $AZIMO_API_KEY"
```

### POST /v1/batches — Create Batch

Requires an API key. Success: 202.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `Idempotency-Key` (header) | string |  | A unique value you generate and keep; reuse it when retrying so the request never runs twice; length 1–128; nullable |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Request body** (application/json)

| Name | Type | Required | Description |
|---|---|---|---|
| `name` | string |  | Default `Batch`; length 1–160 |
| `items` | array<object> | yes | up to 50 items |
| `items[].prompt` | string |  | length ≤ 4000 |
| `items[].assets` | array<string> |  | up to 30 items |
| `items[].options` | object |  |  |
| `items[].options.workflow` | string |  | One of: `auto` `explainer` `short_drama` `creative_video` `motion_explainer` `profile_card` `product_pitch`; Default `explainer` |
| `items[].options.goal` | string |  | length ≤ 2000 |
| `items[].options.audience` | string |  | length ≤ 1000 |
| `items[].options.duration_max` | integer |  | Default `60`; range 5–180 |
| `items[].options.width` | integer |  | Default `1920`; range 640–3840 |
| `items[].options.height` | integer |  | Default `1080`; range 360–2160 |
| `items[].options.fps` | integer |  | Default `30`; range 24–60 |
| `items[].options.subtitles` | boolean |  | Default `false` |
| `items[].options.music` | boolean |  | Default `true` |
| `items[].options.skill_id` | string |  | length ≤ 200; nullable |
| `items[].options.credit_budget` | integer |  | range 1–1000000; nullable |
| `items[].options.video_type` | string |  | One of: `project` `product` `personal` `corporate`; nullable |
| `items[].options.content_data` | map<string, string> |  |  |
| `items[].options.style_preset` | string |  | One of: `cinematic_realism` `clean_3d` `product_studio`; Default `cinematic_realism` |
| `items[].options.brand` | object |  |  |
| `items[].options.motion_style` | string |  | One of: `mono` `photo`; Default `mono` |
| `items[].options.photo_subject` | string |  | length ≤ 120 |
| `items[].options.photo_license` | string |  | One of: `strict` `sharealike`; Default `strict` |
| `items[].webhook_url` | string |  | length ≤ 2000; nullable |
| `items[].plan_id` | string |  | nullable |
| `items[].template_id` | string |  | nullable |
| `items[].brand_id` | string |  | nullable |
| `items[].variables` | map<string, string> |  |  |

**Response 202**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `name` | string | yes |  |
| `jobs` | array<object> | yes |  |
| `jobs[].id` | string | yes |  |
| `jobs[].project_id` | string | yes | nullable |
| `jobs[].batch_id` | string |  | nullable |
| `jobs[].parent_id` | string |  | nullable |
| `jobs[].status` | string | yes | One of: `queued` `running` `needs_input` `complete` `rejected` `failed` `cancelled` |
| `jobs[].stage` | string | yes | nullable |
| `jobs[].progress` | integer | yes | nullable |
| `jobs[].error` | string |  | nullable |
| `jobs[].created_at` | number | yes | nullable |
| `jobs[].updated_at` | number |  | nullable |
| `jobs[].started_at` | number |  | nullable |
| `jobs[].finished_at` | number |  | nullable |
| `jobs[].deleted_at` | number |  | nullable |
| `jobs[].recovery` | object | yes |  |
| `jobs[].recovery.attempt` | integer | yes |  |
| `jobs[].recovery.max_attempts` | integer | yes |  |
| `jobs[].recovery.retry_at` | number |  | nullable |
| `jobs[].result` | object |  | nullable |
| `jobs[].result.files` | map<string, string> |  | Signed download links; present on GET once complete/rejected; nullable |
| `jobs[].result.duration` | number |  | nullable |
| `jobs[].result.shot_count` | integer |  | nullable |
| `jobs[].result.visual_mix` | any |  |  |
| `jobs[].result.qa` | any |  |  |
| `jobs[].result.brief` | any |  |  |
| `jobs[].result.workflow` | string |  | nullable |
| `jobs[].result.routing` | any |  |  |
| `jobs[].result.input_required` | object |  | Why the job is `needs_input`: `code`, `actor`, `message` and what to send to /resume. A spending stop has `code: budget_approval` and `approvable: true` and carries no amounts; answer it with `POST /v1/videos/{id}/resume {"approve_budget": true}`; nullable |
| `jobs[].result.native_project` | any |  |  |
| `jobs[].requested_workflow` | string | yes |  |
| `data` | array<object> | yes | Alias of `jobs`, kept for v0.3 clients |
| `data[].id` | string | yes |  |
| `data[].project_id` | string | yes | nullable |
| `data[].batch_id` | string |  | nullable |
| `data[].parent_id` | string |  | nullable |
| `data[].status` | string | yes | One of: `queued` `running` `needs_input` `complete` `rejected` `failed` `cancelled` |
| `data[].stage` | string | yes | nullable |
| `data[].progress` | integer | yes | nullable |
| `data[].error` | string |  | nullable |
| `data[].created_at` | number | yes | nullable |
| `data[].updated_at` | number |  | nullable |
| `data[].started_at` | number |  | nullable |
| `data[].finished_at` | number |  | nullable |
| `data[].deleted_at` | number |  | nullable |
| `data[].recovery` | object | yes |  |
| `data[].recovery.attempt` | integer | yes |  |
| `data[].recovery.max_attempts` | integer | yes |  |
| `data[].recovery.retry_at` | number |  | nullable |
| `data[].result` | object |  | nullable |
| `data[].result.files` | map<string, string> |  | Signed download links; present on GET once complete/rejected; nullable |
| `data[].result.duration` | number |  | nullable |
| `data[].result.shot_count` | integer |  | nullable |
| `data[].result.visual_mix` | any |  |  |
| `data[].result.qa` | any |  |  |
| `data[].result.brief` | any |  |  |
| `data[].result.workflow` | string |  | nullable |
| `data[].result.routing` | any |  |  |
| `data[].result.input_required` | object |  | Why the job is `needs_input`: `code`, `actor`, `message` and what to send to /resume. A spending stop has `code: budget_approval` and `approvable: true` and carries no amounts; answer it with `POST /v1/videos/{id}/resume {"approve_budget": true}`; nullable |
| `data[].result.native_project` | any |  |  |
| `data[].requested_workflow` | string | yes |  |
| `counts` | map<string, integer> | yes |  |
| `webhook_signing_secret` | string |  | Set when an item carried `webhook_url`: the project secret that signs those per-job callbacks (`Vidgen-Signature`). Store it; verify deliveries with it; nullable |

```bash
curl -X POST "https://azimo.ai/v1/batches" \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"items": [{}]}'
```

### GET /v1/batches/{batch_id} — Get Batch

Requires an API key. Success: 200.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `batch_id` (path) | string | yes |  |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Response 200**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `name` | string | yes |  |
| `jobs` | array<object> | yes |  |
| `jobs[].id` | string | yes |  |
| `jobs[].project_id` | string | yes | nullable |
| `jobs[].batch_id` | string |  | nullable |
| `jobs[].parent_id` | string |  | nullable |
| `jobs[].status` | string | yes | One of: `queued` `running` `needs_input` `complete` `rejected` `failed` `cancelled` |
| `jobs[].stage` | string | yes | nullable |
| `jobs[].progress` | integer | yes | nullable |
| `jobs[].error` | string |  | nullable |
| `jobs[].created_at` | number | yes | nullable |
| `jobs[].updated_at` | number |  | nullable |
| `jobs[].started_at` | number |  | nullable |
| `jobs[].finished_at` | number |  | nullable |
| `jobs[].deleted_at` | number |  | nullable |
| `jobs[].recovery` | object | yes |  |
| `jobs[].recovery.attempt` | integer | yes |  |
| `jobs[].recovery.max_attempts` | integer | yes |  |
| `jobs[].recovery.retry_at` | number |  | nullable |
| `jobs[].result` | object |  | nullable |
| `jobs[].result.files` | map<string, string> |  | Signed download links; present on GET once complete/rejected; nullable |
| `jobs[].result.duration` | number |  | nullable |
| `jobs[].result.shot_count` | integer |  | nullable |
| `jobs[].result.visual_mix` | any |  |  |
| `jobs[].result.qa` | any |  |  |
| `jobs[].result.brief` | any |  |  |
| `jobs[].result.workflow` | string |  | nullable |
| `jobs[].result.routing` | any |  |  |
| `jobs[].result.input_required` | object |  | Why the job is `needs_input`: `code`, `actor`, `message` and what to send to /resume. A spending stop has `code: budget_approval` and `approvable: true` and carries no amounts; answer it with `POST /v1/videos/{id}/resume {"approve_budget": true}`; nullable |
| `jobs[].result.native_project` | any |  |  |
| `jobs[].requested_workflow` | string | yes |  |
| `data` | array<object> | yes | Alias of `jobs`, kept for v0.3 clients |
| `data[].id` | string | yes |  |
| `data[].project_id` | string | yes | nullable |
| `data[].batch_id` | string |  | nullable |
| `data[].parent_id` | string |  | nullable |
| `data[].status` | string | yes | One of: `queued` `running` `needs_input` `complete` `rejected` `failed` `cancelled` |
| `data[].stage` | string | yes | nullable |
| `data[].progress` | integer | yes | nullable |
| `data[].error` | string |  | nullable |
| `data[].created_at` | number | yes | nullable |
| `data[].updated_at` | number |  | nullable |
| `data[].started_at` | number |  | nullable |
| `data[].finished_at` | number |  | nullable |
| `data[].deleted_at` | number |  | nullable |
| `data[].recovery` | object | yes |  |
| `data[].recovery.attempt` | integer | yes |  |
| `data[].recovery.max_attempts` | integer | yes |  |
| `data[].recovery.retry_at` | number |  | nullable |
| `data[].result` | object |  | nullable |
| `data[].result.files` | map<string, string> |  | Signed download links; present on GET once complete/rejected; nullable |
| `data[].result.duration` | number |  | nullable |
| `data[].result.shot_count` | integer |  | nullable |
| `data[].result.visual_mix` | any |  |  |
| `data[].result.qa` | any |  |  |
| `data[].result.brief` | any |  |  |
| `data[].result.workflow` | string |  | nullable |
| `data[].result.routing` | any |  |  |
| `data[].result.input_required` | object |  | Why the job is `needs_input`: `code`, `actor`, `message` and what to send to /resume. A spending stop has `code: budget_approval` and `approvable: true` and carries no amounts; answer it with `POST /v1/videos/{id}/resume {"approve_budget": true}`; nullable |
| `data[].result.native_project` | any |  |  |
| `data[].requested_workflow` | string | yes |  |
| `counts` | map<string, integer> | yes |  |

```bash
curl "https://azimo.ai/v1/batches/<batch_id>" \
  -H "Authorization: Bearer $AZIMO_API_KEY"
```

## Events and webhooks

Instead of polling, receive status changes through signed webhooks or the event list.

### GET /v1/events — List Events

Requires an API key. Success: 200.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `after` (query) | integer |  | Default `0`; range ≥ 0 |
| `limit` (query) | integer |  | Default `50`; range 1–200 |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Response 200**

| Name | Type | Required | Description |
|---|---|---|---|
| `data` | array<object> | yes |  |
| `data[].id` | string | yes |  |
| `data[].sequence` | integer | yes |  |
| `data[].type` | string | yes |  |
| `data[].created_at` | number | yes |  |
| `data[].api_version` | string | yes |  |
| `data[].project_id` | string | yes | nullable |
| `data[].data` | object | yes |  |
| `next_cursor` | integer | yes | Sequence number to pass as `after`; unchanged when the page is empty |
| `has_more` | boolean |  | Default `false` |

```bash
curl "https://azimo.ai/v1/events" \
  -H "Authorization: Bearer $AZIMO_API_KEY"
```

### GET /v1/webhooks — List Webhooks

Requires an API key. Success: 200.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `limit` (query) | integer |  | Default `50`; range 1–200 |
| `cursor` (query) | string |  | length ≤ 256; nullable |
| `after` (query) | string |  | length ≤ 256; nullable |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Response 200**

| Name | Type | Required | Description |
|---|---|---|---|
| `data` | array<object> | yes |  |
| `data[].id` | string | yes |  |
| `data[].project_id` | string | yes | nullable |
| `data[].kind` | string | yes |  |
| `data[].name` | string | yes |  |
| `data[].version` | integer | yes |  |
| `data[].created_at` | number | yes |  |
| `data[].updated_at` | number | yes |  |
| `data[].data` | object | yes |  |
| `data[].data.name` | string | yes |  |
| `data[].data.url` | string | yes |  |
| `data[].data.active` | boolean |  | Default `true` |
| `data[].data.has_secret` | boolean | yes |  |
| `next_cursor` | string |  | Opaque; pass as `cursor` (or the `after` alias) for the next page; nullable |
| `has_more` | boolean |  | Default `false` |

```bash
curl "https://azimo.ai/v1/webhooks" \
  -H "Authorization: Bearer $AZIMO_API_KEY"
```

### POST /v1/webhooks — Create Webhook

Requires an API key. Success: 201.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `Idempotency-Key` (header) | string |  | A unique value you generate and keep; reuse it when retrying so the request never runs twice; length 1–128; nullable |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Request body** (application/json)

| Name | Type | Required | Description |
|---|---|---|---|
| `name` | string |  | Default `Webhook`; length ≤ 160 |
| `url` | string | yes | length ≤ 2000 |
| `active` | boolean |  | Default `true` |

**Response 201**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `project_id` | string | yes | nullable |
| `kind` | string | yes |  |
| `name` | string | yes |  |
| `version` | integer | yes |  |
| `created_at` | number | yes |  |
| `updated_at` | number | yes |  |
| `data` | object | yes |  |
| `data.name` | string | yes |  |
| `data.url` | string | yes |  |
| `data.active` | boolean |  | Default `true` |
| `data.has_secret` | boolean | yes |  |
| `signing_secret` | string | yes | Shown at creation/rotation and for the same actor's idempotent retry within 24 hours; nullable |

```bash
curl -X POST "https://azimo.ai/v1/webhooks" \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"url": "<url>"}'
```

### POST /v1/webhooks/{webhook_id}/rotate-secret — Rotate Webhook Secret

Requires an API key. Success: 200.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `webhook_id` (path) | string | yes |  |
| `expected_version` (query) | integer | yes | range ≥ 1 |
| `Idempotency-Key` (header) | string |  | A unique value you generate and keep; reuse it when retrying so the request never runs twice; length 1–128; nullable |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Response 200**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `project_id` | string | yes | nullable |
| `kind` | string | yes |  |
| `name` | string | yes |  |
| `version` | integer | yes |  |
| `created_at` | number | yes |  |
| `updated_at` | number | yes |  |
| `data` | object | yes |  |
| `data.name` | string | yes |  |
| `data.url` | string | yes |  |
| `data.active` | boolean |  | Default `true` |
| `data.has_secret` | boolean | yes |  |
| `signing_secret` | string | yes | Shown at creation/rotation and for the same actor's idempotent retry within 24 hours; nullable |

```bash
curl -X POST "https://azimo.ai/v1/webhooks/<webhook_id>/rotate-secret?expected_version=<expected_version>" \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

### PUT /v1/webhooks/{webhook_id} — Update Webhook

Requires an API key. Success: 200.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `webhook_id` (path) | string | yes |  |
| `expected_version` (query) | integer | yes | range ≥ 1 |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Request body** (application/json)

| Name | Type | Required | Description |
|---|---|---|---|
| `name` | string |  | Default `Webhook`; length ≤ 160 |
| `url` | string | yes | length ≤ 2000 |
| `active` | boolean |  | Default `true` |

**Response 200**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `project_id` | string | yes | nullable |
| `kind` | string | yes |  |
| `name` | string | yes |  |
| `version` | integer | yes |  |
| `created_at` | number | yes |  |
| `updated_at` | number | yes |  |
| `data` | object | yes |  |
| `data.name` | string | yes |  |
| `data.url` | string | yes |  |
| `data.active` | boolean |  | Default `true` |
| `data.has_secret` | boolean | yes |  |

```bash
curl -X PUT "https://azimo.ai/v1/webhooks/<webhook_id>?expected_version=<expected_version>" \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "<url>"}'
```

### DELETE /v1/webhooks/{webhook_id} — Delete Webhook

Requires an API key. Success: 200.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `webhook_id` (path) | string | yes |  |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Response 200**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `deleted` | boolean |  | Default `true` |

```bash
curl -X DELETE "https://azimo.ai/v1/webhooks/<webhook_id>" \
  -H "Authorization: Bearer $AZIMO_API_KEY"
```

### GET /v1/webhook-deliveries — List Deliveries

Requires an API key. Success: 200.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `limit` (query) | integer |  | Default `50`; range 1–200 |
| `cursor` (query) | string |  | length ≤ 256; nullable |
| `after` (query) | string |  | length ≤ 256; nullable |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Response 200**

| Name | Type | Required | Description |
|---|---|---|---|
| `data` | array<object> | yes |  |
| `data[].id` | string | yes |  |
| `data[].event_id` | string | yes |  |
| `data[].url` | string | yes |  |
| `data[].status` | string | yes |  |
| `data[].attempts` | integer | yes |  |
| `data[].last_error` | string | yes | nullable |
| `data[].delivered_at` | number | yes | nullable |
| `next_cursor` | string |  | Opaque; pass as `cursor` (or the `after` alias) for the next page; nullable |
| `has_more` | boolean |  | Default `false` |

```bash
curl "https://azimo.ai/v1/webhook-deliveries" \
  -H "Authorization: Bearer $AZIMO_API_KEY"
```

### POST /v1/webhook-deliveries/{delivery_id}/replay — Replay

Requires an API key. Success: 202.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `delivery_id` (path) | string | yes |  |
| `webhook_id` (query) | string |  | length ≤ 32; nullable |
| `Idempotency-Key` (header) | string |  | A unique value you generate and keep; reuse it when retrying so the request never runs twice; length 1–128; nullable |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Response 202**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `status` | string | yes | One of: `pending` |

```bash
curl -X POST "https://azimo.ai/v1/webhook-deliveries/<delivery_id>/replay" \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

## Brands and templates

Save brand kits and reusable templates, then reference them when producing.

### GET /v1/brands — Listing

Requires an API key. Success: 200.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `limit` (query) | integer |  | Default `50`; range 1–200 |
| `cursor` (query) | string |  | length ≤ 256; nullable |
| `after` (query) | string |  | length ≤ 256; nullable |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Response 200**

| Name | Type | Required | Description |
|---|---|---|---|
| `data` | array<object> | yes |  |
| `data[].id` | string | yes |  |
| `data[].project_id` | string | yes | nullable |
| `data[].kind` | string | yes |  |
| `data[].name` | string | yes |  |
| `data[].version` | integer | yes |  |
| `data[].created_at` | number | yes |  |
| `data[].updated_at` | number | yes |  |
| `data[].data` | object | yes |  |
| `next_cursor` | string |  | Opaque; pass as `cursor` (or the `after` alias) for the next page; nullable |
| `has_more` | boolean |  | Default `false` |

```bash
curl "https://azimo.ai/v1/brands" \
  -H "Authorization: Bearer $AZIMO_API_KEY"
```

### POST /v1/brands — Create

Requires an API key. Success: 201.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `Idempotency-Key` (header) | string |  | A unique value you generate and keep; reuse it when retrying so the request never runs twice; length 1–128; nullable |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Request body** (application/json)

| Name | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes | length 1–120 |
| `slogan` | string |  | length ≤ 500 |
| `primary_color` | string |  | Default `#0F4C81` |
| `theme` | string |  | One of: `light` `dark`; Default `dark` |
| `assets` | array<string> |  | up to 30 items |
| `notes` | string |  | length ≤ 2000 |

**Response 201**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `project_id` | string | yes | nullable |
| `kind` | string | yes |  |
| `name` | string | yes |  |
| `version` | integer | yes |  |
| `created_at` | number | yes |  |
| `updated_at` | number | yes |  |
| `data` | object | yes |  |

```bash
curl -X POST "https://azimo.ai/v1/brands" \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "<name>"}'
```

### GET /v1/brands/{resource_id} — Get

Requires an API key. Success: 200.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `resource_id` (path) | string | yes |  |
| `version` (query) | integer |  | range ≥ 1; nullable |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Response 200**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `project_id` | string | yes | nullable |
| `kind` | string | yes |  |
| `name` | string | yes |  |
| `version` | integer | yes |  |
| `created_at` | number | yes |  |
| `updated_at` | number | yes |  |
| `data` | object | yes |  |

```bash
curl "https://azimo.ai/v1/brands/<resource_id>" \
  -H "Authorization: Bearer $AZIMO_API_KEY"
```

### PUT /v1/brands/{resource_id} — Revise

Requires an API key. Success: 200.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `resource_id` (path) | string | yes |  |
| `expected_version` (query) | integer | yes | range ≥ 1 |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Request body** (application/json)

| Name | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes | length 1–120 |
| `slogan` | string |  | length ≤ 500 |
| `primary_color` | string |  | Default `#0F4C81` |
| `theme` | string |  | One of: `light` `dark`; Default `dark` |
| `assets` | array<string> |  | up to 30 items |
| `notes` | string |  | length ≤ 2000 |

**Response 200**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `project_id` | string | yes | nullable |
| `kind` | string | yes |  |
| `name` | string | yes |  |
| `version` | integer | yes |  |
| `created_at` | number | yes |  |
| `updated_at` | number | yes |  |
| `data` | object | yes |  |

```bash
curl -X PUT "https://azimo.ai/v1/brands/<resource_id>?expected_version=<expected_version>" \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "<name>"}'
```

### DELETE /v1/brands/{resource_id} — Remove

Requires an API key. Success: 200.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `resource_id` (path) | string | yes |  |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Response 200**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `deleted` | boolean |  | Default `true` |

```bash
curl -X DELETE "https://azimo.ai/v1/brands/<resource_id>" \
  -H "Authorization: Bearer $AZIMO_API_KEY"
```

### GET /v1/templates — Listing

Requires an API key. Success: 200.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `limit` (query) | integer |  | Default `50`; range 1–200 |
| `cursor` (query) | string |  | length ≤ 256; nullable |
| `after` (query) | string |  | length ≤ 256; nullable |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Response 200**

| Name | Type | Required | Description |
|---|---|---|---|
| `data` | array<object> | yes |  |
| `data[].id` | string | yes |  |
| `data[].project_id` | string | yes | nullable |
| `data[].kind` | string | yes |  |
| `data[].name` | string | yes |  |
| `data[].version` | integer | yes |  |
| `data[].created_at` | number | yes |  |
| `data[].updated_at` | number | yes |  |
| `data[].data` | object | yes |  |
| `next_cursor` | string |  | Opaque; pass as `cursor` (or the `after` alias) for the next page; nullable |
| `has_more` | boolean |  | Default `false` |

```bash
curl "https://azimo.ai/v1/templates" \
  -H "Authorization: Bearer $AZIMO_API_KEY"
```

### POST /v1/templates — Create

Requires an API key. Success: 201.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `Idempotency-Key` (header) | string |  | A unique value you generate and keep; reuse it when retrying so the request never runs twice; length 1–128; nullable |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Request body** (application/json)

| Name | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes | length 1–160 |
| `prompt` | string | yes | Use $variable or ${variable} placeholders; length 10–4000 |
| `options` | object |  |  |
| `options.workflow` | string |  | One of: `auto` `explainer` `short_drama` `creative_video` `motion_explainer` `profile_card` `product_pitch`; Default `explainer` |
| `options.goal` | string |  | length ≤ 2000 |
| `options.audience` | string |  | length ≤ 1000 |
| `options.duration_max` | integer |  | Default `60`; range 5–180 |
| `options.width` | integer |  | Default `1920`; range 640–3840 |
| `options.height` | integer |  | Default `1080`; range 360–2160 |
| `options.fps` | integer |  | Default `30`; range 24–60 |
| `options.subtitles` | boolean |  | Default `false` |
| `options.music` | boolean |  | Default `true` |
| `options.skill_id` | string |  | length ≤ 200; nullable |
| `options.credit_budget` | integer |  | range 1–1000000; nullable |
| `options.video_type` | string |  | One of: `project` `product` `personal` `corporate`; nullable |
| `options.content_data` | map<string, string> |  |  |
| `options.style_preset` | string |  | One of: `cinematic_realism` `clean_3d` `product_studio`; Default `cinematic_realism` |
| `options.brand` | object |  |  |
| `options.motion_style` | string |  | One of: `mono` `photo`; Default `mono` |
| `options.photo_subject` | string |  | length ≤ 120 |
| `options.photo_license` | string |  | One of: `strict` `sharealike`; Default `strict` |
| `assets` | array<string> |  | up to 30 items |
| `brand_id` | string |  | nullable |

**Response 201**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `project_id` | string | yes | nullable |
| `kind` | string | yes |  |
| `name` | string | yes |  |
| `version` | integer | yes |  |
| `created_at` | number | yes |  |
| `updated_at` | number | yes |  |
| `data` | object | yes |  |

```bash
curl -X POST "https://azimo.ai/v1/templates" \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "<name>", "prompt": "<prompt>"}'
```

### GET /v1/templates/{resource_id} — Get

Requires an API key. Success: 200.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `resource_id` (path) | string | yes |  |
| `version` (query) | integer |  | range ≥ 1; nullable |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Response 200**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `project_id` | string | yes | nullable |
| `kind` | string | yes |  |
| `name` | string | yes |  |
| `version` | integer | yes |  |
| `created_at` | number | yes |  |
| `updated_at` | number | yes |  |
| `data` | object | yes |  |

```bash
curl "https://azimo.ai/v1/templates/<resource_id>" \
  -H "Authorization: Bearer $AZIMO_API_KEY"
```

### PUT /v1/templates/{resource_id} — Revise

Requires an API key. Success: 200.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `resource_id` (path) | string | yes |  |
| `expected_version` (query) | integer | yes | range ≥ 1 |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Request body** (application/json)

| Name | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes | length 1–160 |
| `prompt` | string | yes | Use $variable or ${variable} placeholders; length 10–4000 |
| `options` | object |  |  |
| `options.workflow` | string |  | One of: `auto` `explainer` `short_drama` `creative_video` `motion_explainer` `profile_card` `product_pitch`; Default `explainer` |
| `options.goal` | string |  | length ≤ 2000 |
| `options.audience` | string |  | length ≤ 1000 |
| `options.duration_max` | integer |  | Default `60`; range 5–180 |
| `options.width` | integer |  | Default `1920`; range 640–3840 |
| `options.height` | integer |  | Default `1080`; range 360–2160 |
| `options.fps` | integer |  | Default `30`; range 24–60 |
| `options.subtitles` | boolean |  | Default `false` |
| `options.music` | boolean |  | Default `true` |
| `options.skill_id` | string |  | length ≤ 200; nullable |
| `options.credit_budget` | integer |  | range 1–1000000; nullable |
| `options.video_type` | string |  | One of: `project` `product` `personal` `corporate`; nullable |
| `options.content_data` | map<string, string> |  |  |
| `options.style_preset` | string |  | One of: `cinematic_realism` `clean_3d` `product_studio`; Default `cinematic_realism` |
| `options.brand` | object |  |  |
| `options.motion_style` | string |  | One of: `mono` `photo`; Default `mono` |
| `options.photo_subject` | string |  | length ≤ 120 |
| `options.photo_license` | string |  | One of: `strict` `sharealike`; Default `strict` |
| `assets` | array<string> |  | up to 30 items |
| `brand_id` | string |  | nullable |

**Response 200**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `project_id` | string | yes | nullable |
| `kind` | string | yes |  |
| `name` | string | yes |  |
| `version` | integer | yes |  |
| `created_at` | number | yes |  |
| `updated_at` | number | yes |  |
| `data` | object | yes |  |

```bash
curl -X PUT "https://azimo.ai/v1/templates/<resource_id>?expected_version=<expected_version>" \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "<name>", "prompt": "<prompt>"}'
```

### DELETE /v1/templates/{resource_id} — Remove

Requires an API key. Success: 200.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `resource_id` (path) | string | yes |  |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Response 200**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `deleted` | boolean |  | Default `true` |

```bash
curl -X DELETE "https://azimo.ai/v1/templates/<resource_id>" \
  -H "Authorization: Bearer $AZIMO_API_KEY"
```

## Projects, keys and audit

Manage projects and API keys, and read the change log.

### GET /v1/projects — List Projects

Requires an API key. Success: 200.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `limit` (query) | integer |  | Default `50`; range 1–200 |
| `cursor` (query) | string |  | length ≤ 256; nullable |
| `after` (query) | string |  | length ≤ 256; nullable |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Response 200**

| Name | Type | Required | Description |
|---|---|---|---|
| `data` | array<object> | yes |  |
| `data[].id` | string | yes |  |
| `data[].organization_id` | string | yes |  |
| `data[].name` | string | yes |  |
| `data[].created_at` | number | yes |  |
| `next_cursor` | string |  | Opaque; pass as `cursor` (or the `after` alias) for the next page; nullable |
| `has_more` | boolean |  | Default `false` |

```bash
curl "https://azimo.ai/v1/projects" \
  -H "Authorization: Bearer $AZIMO_API_KEY"
```

### POST /v1/projects — Create Project

Requires an API key. Success: 201.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `Idempotency-Key` (header) | string |  | A unique value you generate and keep; reuse it when retrying so the request never runs twice; length 1–128; nullable |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Request body** (application/json)

| Name | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes | length 1–120 |

**Response 201**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `organization_id` | string | yes |  |
| `name` | string | yes |  |
| `created_at` | number | yes |  |

```bash
curl -X POST "https://azimo.ai/v1/projects" \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "<name>"}'
```

### DELETE /v1/projects/{project_id} — Delete Project

Requires an API key. Success: 200.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `project_id` (path) | string | yes |  |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Response 200**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `deleted` | boolean |  | Default `true` |

```bash
curl -X DELETE "https://azimo.ai/v1/projects/<project_id>" \
  -H "Authorization: Bearer $AZIMO_API_KEY"
```

### GET /v1/api-keys — List Keys

Requires an API key. Success: 200.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `limit` (query) | integer |  | Default `50`; range 1–200 |
| `cursor` (query) | string |  | length ≤ 256; nullable |
| `after` (query) | string |  | length ≤ 256; nullable |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Response 200**

| Name | Type | Required | Description |
|---|---|---|---|
| `data` | array<object> | yes |  |
| `data[].id` | string | yes |  |
| `data[].name` | string | yes | Label given at creation (also returned as `owner`) |
| `data[].owner` | string | yes |  |
| `data[].prefix` | string | yes | nullable |
| `data[].organization_id` | string | yes | nullable |
| `data[].project_id` | string |  | Set when the key is bound to one project; nullable |
| `data[].role` | string | yes | One of: `owner` `editor` `viewer` |
| `data[].active` | boolean | yes |  |
| `data[].created_at` | number | yes | nullable |
| `data[].last_used_at` | number |  | nullable |
| `data[].expires_at` | number |  | nullable |
| `data[].revoked_at` | number |  | nullable |
| `next_cursor` | string |  | Opaque; pass as `cursor` (or the `after` alias) for the next page; nullable |
| `has_more` | boolean |  | Default `false` |

```bash
curl "https://azimo.ai/v1/api-keys" \
  -H "Authorization: Bearer $AZIMO_API_KEY"
```

### POST /v1/api-keys — Create Key

Requires an API key. Success: 201.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `Idempotency-Key` (header) | string |  | A unique value you generate and keep; reuse it when retrying so the request never runs twice; length 1–128; nullable |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Request body** (application/json)

| Name | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes | length 1–120 |
| `role` | string |  | One of: `owner` `editor` `viewer`; Default `editor` |
| `project_id` | string |  | nullable |
| `monthly_budget_usd` | number |  | range ≥ 0; nullable |
| `rate_per_hour` | integer |  | range ≥ 1; nullable |

**Response 201**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `name` | string | yes | Label given at creation (also returned as `owner`) |
| `owner` | string | yes |  |
| `prefix` | string | yes | nullable |
| `organization_id` | string | yes | nullable |
| `project_id` | string |  | Set when the key is bound to one project; nullable |
| `role` | string | yes | One of: `owner` `editor` `viewer` |
| `active` | boolean | yes |  |
| `created_at` | number | yes | nullable |
| `last_used_at` | number |  | nullable |
| `expires_at` | number |  | nullable |
| `revoked_at` | number |  | nullable |
| `key` | string | yes | The bearer secret; shown once (an idempotent replay returns the same value) |

```bash
curl -X POST "https://azimo.ai/v1/api-keys" \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "<name>"}'
```

### POST /v1/api-keys/{key_id}/rotate — Rotate Key

Requires an API key. Success: 200.

The old secret dies at once, or after `grace_seconds` so running fleets can switch without downtime.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `key_id` (path) | string | yes |  |
| `grace_seconds` (query) | integer |  | Default `0`; range 0–604800 |
| `Idempotency-Key` (header) | string |  | A unique value you generate and keep; reuse it when retrying so the request never runs twice; length 1–128; nullable |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Response 200**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `key` | string | yes |  |
| `previous_id` | string | yes |  |
| `previous_expires_in` | integer | yes | nullable |

```bash
curl -X POST "https://azimo.ai/v1/api-keys/<key_id>/rotate" \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

### DELETE /v1/api-keys/{key_id} — Revoke Key

Requires an API key. Success: 200.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `key_id` (path) | string | yes |  |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Response 200**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `active` | boolean |  | Default `false` |

```bash
curl -X DELETE "https://azimo.ai/v1/api-keys/<key_id>" \
  -H "Authorization: Bearer $AZIMO_API_KEY"
```

### GET /v1/audit — Audit Log

Requires an API key. Success: 200.

Identity and configuration changes for this organization (keys, projects, webhooks), oldest first from `after`.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `after` (query) | integer |  | Default `0`; range ≥ 0 |
| `limit` (query) | integer |  | Default `50`; range 1–200 |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Response 200**

| Name | Type | Required | Description |
|---|---|---|---|
| `data` | array<object> | yes |  |
| `data[].id` | string | yes |  |
| `data[].sequence` | integer | yes |  |
| `data[].type` | string | yes |  |
| `data[].created_at` | number | yes |  |
| `data[].api_version` | string | yes |  |
| `data[].project_id` | string | yes | nullable |
| `data[].data` | object | yes |  |
| `next_cursor` | integer | yes | Sequence number to pass as `after`; unchanged when the page is empty |
| `has_more` | boolean |  | Default `false` |

```bash
curl "https://azimo.ai/v1/audit" \
  -H "Authorization: Bearer $AZIMO_API_KEY"
```

## Wallet and usage

Balance, statement and usage, and online top-up.

### GET /v1/wallet — Wallet

Requires an API key. Success: 200.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Response 200**

| Name | Type | Required | Description |
|---|---|---|---|
| `balance_cents` | integer | yes |  |
| `held_cents` | integer | yes |  |
| `available_cents` | integer | yes |  |
| `low_balance_cents` | integer | yes | nullable |
| `currency` | string | yes |  |
| `organization_id` | string | yes |  |

```bash
curl "https://azimo.ai/v1/wallet" \
  -H "Authorization: Bearer $AZIMO_API_KEY"
```

### GET /v1/wallet/entries — Wallet Entries

Requires an API key. Success: 200.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `after` (query) | string |  | length ≤ 64; nullable |
| `limit` (query) | integer |  | Default `50`; range 1–200 |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Response 200**

| Name | Type | Required | Description |
|---|---|---|---|
| `data` | array<object> | yes |  |
| `data[].id` | string | yes |  |
| `data[].organization_id` | string | yes |  |
| `data[].kind` | string | yes |  |
| `data[].amount_cents` | integer | yes |  |
| `data[].hold_cents` | integer | yes |  |
| `data[].job_id` | string | yes | nullable |
| `data[].note` | string | yes | nullable |
| `data[].actor` | string | yes | nullable |
| `data[].created_at` | number | yes |  |
| `next_cursor` | string |  | Opaque; pass as `cursor` (or the `after` alias) for the next page; nullable |
| `has_more` | boolean |  | Default `false` |

```bash
curl "https://azimo.ai/v1/wallet/entries" \
  -H "Authorization: Bearer $AZIMO_API_KEY"
```

### POST /v1/wallet/checkout — Checkout

Requires an API key. Success: 201.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `Idempotency-Key` (header) | string | yes | A unique value you generate and keep; reuse it when retrying so the request never runs twice; length 1–128 |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Request body** (application/json)

| Name | Type | Required | Description |
|---|---|---|---|
| `amount_cents` | integer | yes | USD cents, $5–$10,000; range 500–1000000 |

**Response 201**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `url` | string | yes |  |
| `amount_cents` | integer | yes |  |
| `currency` | string |  | Default `USD` |

```bash
curl -X POST "https://azimo.ai/v1/wallet/checkout" \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents": 500}'
```

### GET /v1/usage — Usage

Requires an API key. Success: 200.

The amount billed for this project's paid calls in [from, to) (default: the last 30 days), plus job counts, grouped on request.
`group_by=job` pages by job id with `after`; `group_by=workflow` reads at most 5000 jobs' request options.

**Parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `from` (query) | number |  | range ≥ 0; nullable |
| `to` (query) | number |  | range ≥ 0; nullable |
| `group_by` (query) | string |  | Default `none` |
| `limit` (query) | integer |  | Default `50`; range 1–200 |
| `after` (query) | string |  | length ≤ 32; nullable |
| `X-Project-ID` (header) | string |  | The project to act on; the default project when omitted; nullable |

**Response 200**

| Name | Type | Required | Description |
|---|---|---|---|
| `project_id` | string | yes |  |
| `range` | map<string, number> | yes |  |
| `jobs` | map<string, integer> | yes |  |
| `list_usd` | number | yes | Amount billed for the paid calls in the range |
| `group_by` | string | yes |  |
| `groups` | array<object> | yes | nullable |
| `next_cursor` | string | yes | nullable |

```bash
curl "https://azimo.ai/v1/usage" \
  -H "Authorization: Bearer $AZIMO_API_KEY"
```

## Service health

Health checks; no key needed.

### GET /healthz — Healthz

No authentication. Success: 200.

```bash
curl "https://azimo.ai/healthz"
```

### GET /readyz — Readyz

No authentication. Success: 200.

**Response 200**

| Name | Type | Required | Description |
|---|---|---|---|
| `ok` | boolean | yes |  |
| `db` | boolean | yes |  |
| `version` | string | yes |  |
| `queue_depth` | integer | yes |  |
| `running` | integer | yes |  |
| `worker_seen_at` | number |  | Latest job start or running-job heartbeat; nullable |
| `worker_alive` | boolean | yes | A worker sent a durable heartbeat within the last 5 minutes |

- `503` Service Unavailable

```bash
curl "https://azimo.ai/readyz"
```

View Markdown

Basics

Base URL: https://azimo.ai
Authentication: Every /v1 request sends Authorization: Bearer <API key>. Create a key in your account; the raw key is shown only once.
Projects: X-Project-ID selects a project; the default project is used when it is omitted.
Idempotency: Send an Idempotency-Key with requests that create something and reuse it when retrying; the same value with a different request returns 409.
Asynchronous jobs: POST /v1/videos returns 202 and a video id; poll GET /v1/videos/{job_id} or receive a webhook. needs_input means something is missing, not that the video is done.
Pagination: Lists return data, next_cursor and has_more; pass next_cursor as cursor to get the next page.
Pricing: The API never returns prices. For a quote, contact sales@azimo.ai.

Errors

Errors are JSON with the fields below; include the request_id when you report a problem.

Name	Type	Description
`error`required	object
`error.code`required	string	Stable machine-readable code, e.g. unauthenticated, not_found, idempotency_conflict, validation_error, rate_limited, insufficient_balance, budget_exceeded, contact_sales, internal_error
`error.message`required	string
`error.details`	any	Structured context: validation errors, unmet workflow requirements, or null
`error.request_id`required	string	nullable

Status	Meaning
`401`	Missing or invalid bearer key (`WWW-Authenticate: Bearer`)
`402`	Wallet balance or spending limit would be exceeded
`403`	Key role or project scope does not allow this; `contact_sales` for anything about pricing
`404`	Resource not found in this organization/project
`409`	State conflict, or Idempotency-Key reused with a different request
`422`	Validation error; `details` lists the failing fields or requirements
`429`	Hourly limit reached (`Retry-After` in seconds)
`500`	Unexpected failure; cite `request_id` when reporting it

Account and capabilities

Who the current key is, and which workflows and video types are available.

Me

GET/v1/me

API key requiredSuccess 200

Parameters

Name	Type	Description
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Response 200 application/json

Name	Type	Description
`id`required	string
`key_id`required	string	Same as `id`
`organization_id`required	string
`project_id`required	string
`role`required	string	One of: `owner` `editor` `viewer`
`billing_mode`required	string	One of: `budget` `prepaid`
`wallet`required	object
`permissions`required	map<string, boolean>

Example

curl "https://azimo.ai/v1/me" \
  -H "Authorization: Bearer $AZIMO_API_KEY"

Workflows

GET/v1/workflows

API key requiredSuccess 200

Parameters

Name	Type	Description
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Response 200 application/json

Name	Type	Description
`router`required	object
`workflows`required	map<string, object>

Example

curl "https://azimo.ai/v1/workflows" \
  -H "Authorization: Bearer $AZIMO_API_KEY"

Video Skills

GET/v1/workflows/creative_video/skills

API key requiredSuccess 200

Parameters

Name	Type	Description
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Response 200 application/json

Name	Type	Description
`data`required	array<any>

Example

curl "https://azimo.ai/v1/workflows/creative_video/skills" \
  -H "Authorization: Bearer $AZIMO_API_KEY"

Video Types

GET/v1/video-types

API key requiredSuccess 200

Parameters

Name	Type	Description
`lang`query	string	Display language, `zh` (default) or `en`; when absent the first `zh`/`en` entry of `Accept-Language` is used; length ≤ 16; nullable
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable
`accept-language`header	string	nullable

Response 200 application/json

Name	Type	Description
`data`required	array<object>
`data[].id`required	string
`data[].version`required	any
`data[].template`	any
`next_cursor`	string	Opaque; pass as `cursor` (or the `after` alias) for the next page; nullable
`has_more`	boolean	Default `false`

Example

curl "https://azimo.ai/v1/video-types" \
  -H "Authorization: Bearer $AZIMO_API_KEY"

Playground

GET/v1/playground

API key requiredSuccess 200

The workflow gallery: seven fixed entries, each with routing values, whether this account can start it now, and a runnable example.

Parameters

Name	Type	Description
`lang`query	string	Display language, `zh` (default) or `en`; when absent the first `zh`/`en` entry of `Accept-Language` is used; length ≤ 16; nullable
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable
`accept-language`header	string	nullable

Response 200 application/json

Name	Type	Description
`data`required	array<object>
`data[].id`required	string	Stable catalogue id
`data[].name`required	string
`data[].summary`required	string	One benefit-oriented sentence
`data[].workflow`required	string	Backend routing value for `options.workflow`; null when the entry cannot be started yet; nullable
`data[].video_type`required	string	`options.video_type` for structured explainers, otherwise null; nullable
`data[].aspect`required	string	One of: `16:9` `9:16` `1:1`
`data[].duration`required	integer	Default `options.duration_max` in seconds
`data[].duration_range`required	array<integer>	[minimum, maximum] seconds the workflow accepts
`data[].needs_assets`required	boolean	Reference material (photos, product pictures) is strongly recommended
`data[].available`required	boolean
`data[].reason`required	string	Why `available` is false: coming_soon, not_configured (this environment) or contact_sales (not sold to this account); One of: `coming_soon` `not_configured` `contact_sales`; nullable
`data[].coming_soon`required	boolean
`data[].example`required	object
`data[].example.prompt`required	string	A ready-to-run creative brief for `POST /v1/videos` or `POST /v1/plans`
`data[].example.content_data`required	map<string, string>	Sample value for every input of the workflow's video type (`options.content_data`); empty when the workflow has none

Example

curl "https://azimo.ai/v1/playground" \
  -H "Authorization: Bearer $AZIMO_API_KEY"

Assets

Upload PDFs, slides and pictures; reference the returned asset ids in a plan.

List Assets

GET/v1/assets

API key requiredSuccess 200

Parameters

Name	Type	Description
`limit`query	integer	Default `50`; range 1–200
`cursor`query	string	length ≤ 256; nullable
`after`query	string	length ≤ 256; nullable
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Response 200 application/json

Name	Type	Description
`data`required	array<object>
`data[].id`required	string
`data[].project_id`required	string	nullable
`data[].filename`required	string
`data[].bytes`required	integer
`data[].sha256`required	string
`data[].created_at`required	number
`next_cursor`	string	Opaque; pass as `cursor` (or the `after` alias) for the next page; nullable
`has_more`	boolean	Default `false`

Example

curl "https://azimo.ai/v1/assets" \
  -H "Authorization: Bearer $AZIMO_API_KEY"

Upload Asset

POST/v1/assets

API key requiredSuccess 201

Parameters

Name	Type	Description
`Idempotency-Key`header	string	A unique value you generate and keep; reuse it when retrying so the request never runs twice; length 1–128; nullable
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Request body multipart/form-data

Name	Type	Description
`file`required	file

Response 201 application/json

Name	Type	Description
`id`required	string
`project_id`required	string	nullable
`filename`required	string
`bytes`required	integer
`sha256`required	string
`created_at`required	number

Example

curl -X POST "https://azimo.ai/v1/assets" \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "file=@deck.pdf"

Get Asset

GET/v1/assets/{asset_id}

API key requiredSuccess 200

Parameters

Name	Type	Description
`asset_id`requiredpath	string
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Response 200 application/json

Name	Type	Description
`id`required	string
`project_id`required	string	nullable
`filename`required	string
`bytes`required	integer
`sha256`required	string
`created_at`required	number

Example

curl "https://azimo.ai/v1/assets/<asset_id>" \
  -H "Authorization: Bearer $AZIMO_API_KEY"

Delete Asset

DELETE/v1/assets/{asset_id}

API key requiredSuccess 200

Remove an upload and its bytes. Jobs that already consumed it keep their own copies.

Parameters

Name	Type	Description
`asset_id`requiredpath	string
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Response 200 application/json

Name	Type	Description
`id`required	string
`deleted`	boolean	Default `true`

Example

curl -X DELETE "https://azimo.ai/v1/assets/<asset_id>" \
  -H "Authorization: Bearer $AZIMO_API_KEY"

Download Asset

GET/v1/assets/{asset_id}/file

API key requiredSuccess 200

Parameters

Name	Type	Description
`asset_id`requiredpath	string
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Response 200 application/octet-stream

Returns the file bytes.

Example

curl "https://azimo.ai/v1/assets/<asset_id>/file" \
  -H "Authorization: Bearer $AZIMO_API_KEY"

Plans

Plan before producing: workflow, specs, assets and structure are frozen and anything missing is reported.

List Plans

GET/v1/plans

API key requiredSuccess 200

Parameters

Name	Type	Description
`limit`query	integer	Default `50`; range 1–200
`cursor`query	string	length ≤ 256; nullable
`after`query	string	length ≤ 256; nullable
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Response 200 application/json

Name	Type	Description
`data`required	array<object>
`data[].id`required	string
`data[].project_id`required	string	nullable
`data[].kind`required	string
`data[].name`required	string
`data[].version`required	integer
`data[].created_at`required	number
`data[].updated_at`required	number
`data[].data`required	object
`data[].data.status`required	string	One of: `planning` `ready` `needs_input` `unavailable`
`data[].data.request`required	object
`data[].data.assets`	array<object>
`data[].data.routing`	object	nullable
`data[].data.requirements`	array<object>
`data[].data.reason`	string	nullable
`data[].data.job_id`	string	The production this plan started; a plan starts at most one; nullable
`next_cursor`	string	Opaque; pass as `cursor` (or the `after` alias) for the next page; nullable
`has_more`	boolean	Default `false`

Example

curl "https://azimo.ai/v1/plans" \
  -H "Authorization: Bearer $AZIMO_API_KEY"

Create Plan

POST/v1/plans

API key requiredSuccess 201

Parameters

Name	Type	Description
`Idempotency-Key`header	string	A unique value you generate and keep; reuse it when retrying so the request never runs twice; length 1–128; nullable
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Request body application/json

Name	Type	Description
`prompt`	string	length ≤ 4000
`assets`	array<string>	up to 30 items
`options`	object
`options.workflow`	string	One of: `auto` `explainer` `short_drama` `creative_video` `motion_explainer` `profile_card` `product_pitch`; Default `explainer`
`options.goal`	string	length ≤ 2000
`options.audience`	string	length ≤ 1000
`options.duration_max`	integer	Default `60`; range 5–180
`options.width`	integer	Default `1920`; range 640–3840
`options.height`	integer	Default `1080`; range 360–2160
`options.fps`	integer	Default `30`; range 24–60
`options.subtitles`	boolean	Default `false`
`options.music`	boolean	Default `true`
`options.skill_id`	string	length ≤ 200; nullable
`options.credit_budget`	integer	range 1–1000000; nullable
`options.video_type`	string	One of: `project` `product` `personal` `corporate`; nullable
`options.content_data`	map<string, string>
`options.style_preset`	string	One of: `cinematic_realism` `clean_3d` `product_studio`; Default `cinematic_realism`
`options.brand`	object
`options.motion_style`	string	One of: `mono` `photo`; Default `mono`
`options.photo_subject`	string	length ≤ 120
`options.photo_license`	string	One of: `strict` `sharealike`; Default `strict`
`webhook_url`	string	length ≤ 2000; nullable
`plan_id`	string	nullable
`template_id`	string	nullable
`brand_id`	string	nullable
`variables`	map<string, string>

Response 201 application/json

Name	Type	Description
`id`required	string
`project_id`required	string	nullable
`kind`required	string
`name`required	string
`version`required	integer
`created_at`required	number
`updated_at`required	number
`data`required	object
`data.status`required	string	One of: `planning` `ready` `needs_input` `unavailable`
`data.request`required	object
`data.assets`	array<object>
`data.routing`	object	nullable
`data.requirements`	array<object>
`data.reason`	string	nullable
`data.job_id`	string	The production this plan started; a plan starts at most one; nullable

Example

curl -X POST "https://azimo.ai/v1/plans" \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "<prompt>", "assets": ["<asset id>"]}'

Get Plan

GET/v1/plans/{plan_id}

API key requiredSuccess 200

Parameters

Name	Type	Description
`plan_id`requiredpath	string
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Response 200 application/json

Name	Type	Description
`id`required	string
`project_id`required	string	nullable
`kind`required	string
`name`required	string
`version`required	integer
`created_at`required	number
`updated_at`required	number
`data`required	object
`data.status`required	string	One of: `planning` `ready` `needs_input` `unavailable`
`data.request`required	object
`data.assets`	array<object>
`data.routing`	object	nullable
`data.requirements`	array<object>
`data.reason`	string	nullable
`data.job_id`	string	The production this plan started; a plan starts at most one; nullable

Example

curl "https://azimo.ai/v1/plans/<plan_id>" \
  -H "Authorization: Bearer $AZIMO_API_KEY"

Preview Route

POST/v1/route

API key requiredSuccess 200

Parameters

Name	Type	Description
`Idempotency-Key`header	string	A unique value you generate and keep; reuse it when retrying so the request never runs twice; length 1–128; nullable
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Request body application/json

Name	Type	Description
`prompt`	string	length ≤ 4000
`assets`	array<string>	up to 30 items
`options`	object
`options.workflow`	string	One of: `auto` `explainer` `short_drama` `creative_video` `motion_explainer` `profile_card` `product_pitch`; Default `explainer`
`options.goal`	string	length ≤ 2000
`options.audience`	string	length ≤ 1000
`options.duration_max`	integer	Default `60`; range 5–180
`options.width`	integer	Default `1920`; range 640–3840
`options.height`	integer	Default `1080`; range 360–2160
`options.fps`	integer	Default `30`; range 24–60
`options.subtitles`	boolean	Default `false`
`options.music`	boolean	Default `true`
`options.skill_id`	string	length ≤ 200; nullable
`options.credit_budget`	integer	range 1–1000000; nullable
`options.video_type`	string	One of: `project` `product` `personal` `corporate`; nullable
`options.content_data`	map<string, string>
`options.style_preset`	string	One of: `cinematic_realism` `clean_3d` `product_studio`; Default `cinematic_realism`
`options.brand`	object
`options.motion_style`	string	One of: `mono` `photo`; Default `mono`
`options.photo_subject`	string	length ≤ 120
`options.photo_license`	string	One of: `strict` `sharealike`; Default `strict`
`webhook_url`	string	length ≤ 2000; nullable
`plan_id`	string	nullable
`template_id`	string	nullable
`brand_id`	string	nullable
`variables`	map<string, string>

Response 200 application/json

Name	Type	Description
`plan_id`required	string
`workflow`	string	nullable
`requirements`	array<object>

Example

curl -X POST "https://azimo.ai/v1/route" \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "<prompt>", "assets": ["<asset id>"]}'

Videos

Produce a video from a confirmed plan, follow its progress, download it, resume, revise or cancel it.

List Videos

GET/v1/videos

API key requiredSuccess 200

Parameters

Name	Type	Description
`limit`query	integer	Default `50`; range 1–200
`cursor`query	string	length ≤ 256; nullable
`after`query	string	length ≤ 256; nullable
`status`query	string	One of: `queued` `running` `needs_input` `complete` `rejected` `failed` `cancelled`; nullable
`batch_id`query	string	length ≤ 32; nullable
`created_after`query	number	range ≥ 0; nullable
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Response 200 application/json

Name	Type	Description
`data`required	array<object>
`data[].id`required	string
`data[].project_id`required	string	nullable
`data[].batch_id`	string	nullable
`data[].parent_id`	string	nullable
`data[].status`required	string	One of: `queued` `running` `needs_input` `complete` `rejected` `failed` `cancelled`
`data[].stage`required	string	nullable
`data[].progress`required	integer	nullable
`data[].error`	string	nullable
`data[].created_at`required	number	nullable
`data[].updated_at`	number	nullable
`data[].started_at`	number	nullable
`data[].finished_at`	number	nullable
`data[].deleted_at`	number	nullable
`data[].recovery`required	object
`data[].recovery.attempt`required	integer
`data[].recovery.max_attempts`required	integer
`data[].recovery.retry_at`	number	nullable
`data[].result`	object	nullable
`data[].result.files`	map<string, string>	Signed download links; present on GET once complete/rejected; nullable
`data[].result.duration`	number	nullable
`data[].result.shot_count`	integer	nullable
`data[].result.visual_mix`	any
`data[].result.qa`	any
`data[].result.brief`	any
`data[].result.workflow`	string	nullable
`data[].result.routing`	any
`data[].result.input_required`	object	Why the job is `needs_input`: `code`, `actor`, `message` and what to send to /resume. A spending stop has `code: budget_approval` and `approvable: true` and carries no amounts; answer it with `POST /v1/videos/{id}/resume {"approve_budget": true}`; nullable
`data[].result.native_project`	any
`data[].requested_workflow`required	string
`next_cursor`	string	Opaque; pass as `cursor` (or the `after` alias) for the next page; nullable
`has_more`	boolean	Default `false`

Example

curl "https://azimo.ai/v1/videos" \
  -H "Authorization: Bearer $AZIMO_API_KEY"

Create Video

POST/v1/videos

API key requiredSuccess 202

Parameters

Name	Type	Description
`Idempotency-Key`header	string	A unique value you generate and keep; reuse it when retrying so the request never runs twice; length 1–128; nullable
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Request body application/json

Name	Type	Description
`prompt`	string	length ≤ 4000
`assets`	array<string>	up to 30 items
`options`	object
`options.workflow`	string	One of: `auto` `explainer` `short_drama` `creative_video` `motion_explainer` `profile_card` `product_pitch`; Default `explainer`
`options.goal`	string	length ≤ 2000
`options.audience`	string	length ≤ 1000
`options.duration_max`	integer	Default `60`; range 5–180
`options.width`	integer	Default `1920`; range 640–3840
`options.height`	integer	Default `1080`; range 360–2160
`options.fps`	integer	Default `30`; range 24–60
`options.subtitles`	boolean	Default `false`
`options.music`	boolean	Default `true`
`options.skill_id`	string	length ≤ 200; nullable
`options.credit_budget`	integer	range 1–1000000; nullable
`options.video_type`	string	One of: `project` `product` `personal` `corporate`; nullable
`options.content_data`	map<string, string>
`options.style_preset`	string	One of: `cinematic_realism` `clean_3d` `product_studio`; Default `cinematic_realism`
`options.brand`	object
`options.motion_style`	string	One of: `mono` `photo`; Default `mono`
`options.photo_subject`	string	length ≤ 120
`options.photo_license`	string	One of: `strict` `sharealike`; Default `strict`
`webhook_url`	string	length ≤ 2000; nullable
`plan_id`	string	nullable
`template_id`	string	nullable
`brand_id`	string	nullable
`variables`	map<string, string>

Response 202 application/json

Name	Type	Description
`id`required	string
`project_id`required	string	nullable
`batch_id`	string	nullable
`parent_id`	string	nullable
`status`required	string	One of: `queued` `running` `needs_input` `complete` `rejected` `failed` `cancelled`
`stage`required	string	nullable
`progress`required	integer	nullable
`error`	string	nullable
`created_at`required	number	nullable
`updated_at`	number	nullable
`started_at`	number	nullable
`finished_at`	number	nullable
`deleted_at`	number	nullable
`recovery`required	object
`recovery.attempt`required	integer
`recovery.max_attempts`required	integer
`recovery.retry_at`	number	nullable
`result`	object	nullable
`result.files`	map<string, string>	Signed download links; present on GET once complete/rejected; nullable
`result.duration`	number	nullable
`result.shot_count`	integer	nullable
`result.visual_mix`	any
`result.qa`	any
`result.brief`	any
`result.workflow`	string	nullable
`result.routing`	any
`result.input_required`	object	Why the job is `needs_input`: `code`, `actor`, `message` and what to send to /resume. A spending stop has `code: budget_approval` and `approvable: true` and carries no amounts; answer it with `POST /v1/videos/{id}/resume {"approve_budget": true}`; nullable
`result.native_project`	any
`requested_workflow`required	string
`webhook_signing_secret`	string	Only present when the request set `webhook_url`: the project secret that signs that per-job callback (`Vidgen-Signature`). Store it; verify deliveries with it; nullable

Example

curl -X POST "https://azimo.ai/v1/videos" \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "<prompt>", "assets": ["<asset id>"]}'

Resume

POST/v1/videos/{job_id}/resume

API key requiredSuccess 202

Parameters

Name	Type	Description
`job_id`requiredpath	string
`Idempotency-Key`header	string	A unique value you generate and keep; reuse it when retrying so the request never runs twice; length 1–128; nullable
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Request body application/json

Name	Type	Description
`message`	string	length ≤ 4000
`questionnaire_id`	string	length ≤ 200; nullable
`answers`	array<object>	up to 30 items
`assets`	array<string>	up to 9 items
`approve_budget`	boolean	Approve the pending budget stop; the server computes the new limit; Default `false`
`credit_budget`	integer	Legacy: explicit new Vikoo credit budget for a credit budget stop; range 1–1000000; nullable
`budget_usd`	number	Legacy: explicit new total USD limit for a budget stop; range 0–100000; nullable

Response 202 application/json

Name	Type	Description
`id`required	string
`project_id`required	string	nullable
`batch_id`	string	nullable
`parent_id`	string	nullable
`status`required	string	One of: `queued` `running` `needs_input` `complete` `rejected` `failed` `cancelled`
`stage`required	string	nullable
`progress`required	integer	nullable
`error`	string	nullable
`created_at`required	number	nullable
`updated_at`	number	nullable
`started_at`	number	nullable
`finished_at`	number	nullable
`deleted_at`	number	nullable
`recovery`required	object
`recovery.attempt`required	integer
`recovery.max_attempts`required	integer
`recovery.retry_at`	number	nullable
`result`	object	nullable
`result.files`	map<string, string>	Signed download links; present on GET once complete/rejected; nullable
`result.duration`	number	nullable
`result.shot_count`	integer	nullable
`result.visual_mix`	any
`result.qa`	any
`result.brief`	any
`result.workflow`	string	nullable
`result.routing`	any
`result.input_required`	object	Why the job is `needs_input`: `code`, `actor`, `message` and what to send to /resume. A spending stop has `code: budget_approval` and `approvable: true` and carries no amounts; answer it with `POST /v1/videos/{id}/resume {"approve_budget": true}`; nullable
`result.native_project`	any
`requested_workflow`required	string

Example

curl -X POST "https://azimo.ai/v1/videos/<job_id>/resume" \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"message": "<message>", "questionnaire_id": "<questionnaire_id>"}'

Revise Video

POST/v1/videos/{job_id}/revisions

API key requiredSuccess 202

Parameters

Name	Type	Description
`job_id`requiredpath	string
`Idempotency-Key`header	string	A unique value you generate and keep; reuse it when retrying so the request never runs twice; length 1–128; nullable
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Request body application/json

Name	Type	Description
`prompt`	string	length 10–4000; nullable
`assets`	array<string>	up to 30 items; nullable
`options`	object
`options.workflow`	string	One of: `auto` `explainer` `short_drama` `creative_video` `motion_explainer` `profile_card` `product_pitch`; Default `explainer`
`options.goal`	string	length ≤ 2000
`options.audience`	string	length ≤ 1000
`options.duration_max`	integer	Default `60`; range 5–180
`options.width`	integer	Default `1920`; range 640–3840
`options.height`	integer	Default `1080`; range 360–2160
`options.fps`	integer	Default `30`; range 24–60
`options.subtitles`	boolean	Default `false`
`options.music`	boolean	Default `true`
`options.skill_id`	string	length ≤ 200; nullable
`options.credit_budget`	integer	range 1–1000000; nullable
`options.video_type`	string	One of: `project` `product` `personal` `corporate`; nullable
`options.content_data`	map<string, string>
`options.style_preset`	string	One of: `cinematic_realism` `clean_3d` `product_studio`; Default `cinematic_realism`
`options.brand`	object
`options.motion_style`	string	One of: `mono` `photo`; Default `mono`
`options.photo_subject`	string	length ≤ 120
`options.photo_license`	string	One of: `strict` `sharealike`; Default `strict`

Response 202 application/json

Name	Type	Description
`id`required	string
`project_id`required	string	nullable
`batch_id`	string	nullable
`parent_id`	string	nullable
`status`required	string	One of: `queued` `running` `needs_input` `complete` `rejected` `failed` `cancelled`
`stage`required	string	nullable
`progress`required	integer	nullable
`error`	string	nullable
`created_at`required	number	nullable
`updated_at`	number	nullable
`started_at`	number	nullable
`finished_at`	number	nullable
`deleted_at`	number	nullable
`recovery`required	object
`recovery.attempt`required	integer
`recovery.max_attempts`required	integer
`recovery.retry_at`	number	nullable
`result`	object	nullable
`result.files`	map<string, string>	Signed download links; present on GET once complete/rejected; nullable
`result.duration`	number	nullable
`result.shot_count`	integer	nullable
`result.visual_mix`	any
`result.qa`	any
`result.brief`	any
`result.workflow`	string	nullable
`result.routing`	any
`result.input_required`	object	Why the job is `needs_input`: `code`, `actor`, `message` and what to send to /resume. A spending stop has `code: budget_approval` and `approvable: true` and carries no amounts; answer it with `POST /v1/videos/{id}/resume {"approve_budget": true}`; nullable
`result.native_project`	any
`requested_workflow`required	string
`webhook_signing_secret`	string	Only present when the request set `webhook_url`: the project secret that signs that per-job callback (`Vidgen-Signature`). Store it; verify deliveries with it; nullable

Example

curl -X POST "https://azimo.ai/v1/videos/<job_id>/revisions" \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "<prompt>", "assets": ["<asset id>"]}'

Get Video

GET/v1/videos/{job_id}

API key requiredSuccess 200

Parameters

Name	Type	Description
`job_id`requiredpath	string
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Response 200 application/json

Name	Type	Description
`id`required	string
`project_id`required	string	nullable
`batch_id`	string	nullable
`parent_id`	string	nullable
`status`required	string	One of: `queued` `running` `needs_input` `complete` `rejected` `failed` `cancelled`
`stage`required	string	nullable
`progress`required	integer	nullable
`error`	string	nullable
`created_at`required	number	nullable
`updated_at`	number	nullable
`started_at`	number	nullable
`finished_at`	number	nullable
`deleted_at`	number	nullable
`recovery`required	object
`recovery.attempt`required	integer
`recovery.max_attempts`required	integer
`recovery.retry_at`	number	nullable
`result`	object	nullable
`result.files`	map<string, string>	Signed download links; present on GET once complete/rejected; nullable
`result.duration`	number	nullable
`result.shot_count`	integer	nullable
`result.visual_mix`	any
`result.qa`	any
`result.brief`	any
`result.workflow`	string	nullable
`result.routing`	any
`result.input_required`	object	Why the job is `needs_input`: `code`, `actor`, `message` and what to send to /resume. A spending stop has `code: budget_approval` and `approvable: true` and carries no amounts; answer it with `POST /v1/videos/{id}/resume {"approve_budget": true}`; nullable
`result.native_project`	any
`requested_workflow`required	string

Example

curl "https://azimo.ai/v1/videos/<job_id>" \
  -H "Authorization: Bearer $AZIMO_API_KEY"

Delete Video

DELETE/v1/videos/{job_id}

API key requiredSuccess 200

Purge a finished job's films, uploads copies and diagnostics; the job record stays for usage history.

Parameters

Name	Type	Description
`job_id`requiredpath	string
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Response 200 application/json

Name	Type	Description
`id`required	string
`deleted`	boolean	Default `true`

Example

curl -X DELETE "https://azimo.ai/v1/videos/<job_id>" \
  -H "Authorization: Bearer $AZIMO_API_KEY"

Cancel Video

POST/v1/videos/{job_id}/cancel

API key requiredSuccess 200

queued / needs_input jobs cancel at once; a running job stops before its next paid step (cancelling).

Parameters

Name	Type	Description
`job_id`requiredpath	string
`Idempotency-Key`header	string	A unique value you generate and keep; reuse it when retrying so the request never runs twice; length 1–128; nullable
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Response 200 application/json

Name	Type	Description
`id`required	string
`status`required	string	One of: `cancelled` `cancelling`

Example

curl -X POST "https://azimo.ai/v1/videos/<job_id>/cancel" \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Get File

GET/v1/videos/{job_id}/files/{name}

Signed link, no keySuccess 200

Parameters

Name	Type	Description
`job_id`requiredpath	string
`name`requiredpath	string
`expires`requiredquery	integer
`sig`requiredquery	string

Response 200 application/octet-stream

Returns the file bytes.

Example

curl "https://azimo.ai/v1/videos/<job_id>/files/<name>?expires=<expires>&sig=<sig>"

Batches

Submit several videos at once.

List Batches

GET/v1/batches

API key requiredSuccess 200

Parameters

Name	Type	Description
`limit`query	integer	Default `50`; range 1–200
`cursor`query	string	length ≤ 256; nullable
`after`query	string	length ≤ 256; nullable
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Response 200 application/json

Name	Type	Description
`data`required	array<object>
`data[].id`required	string
`data[].name`required	string
`data[].created_at`required	number
`next_cursor`	string	Opaque; pass as `cursor` (or the `after` alias) for the next page; nullable
`has_more`	boolean	Default `false`

Example

curl "https://azimo.ai/v1/batches" \
  -H "Authorization: Bearer $AZIMO_API_KEY"

Create Batch

POST/v1/batches

API key requiredSuccess 202

Parameters

Name	Type	Description
`Idempotency-Key`header	string	A unique value you generate and keep; reuse it when retrying so the request never runs twice; length 1–128; nullable
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Request body application/json

Name	Type	Description
`name`	string	Default `Batch`; length 1–160
`items`required	array<object>	up to 50 items
`items[].prompt`	string	length ≤ 4000
`items[].assets`	array<string>	up to 30 items
`items[].options`	object
`items[].options.workflow`	string	One of: `auto` `explainer` `short_drama` `creative_video` `motion_explainer` `profile_card` `product_pitch`; Default `explainer`
`items[].options.goal`	string	length ≤ 2000
`items[].options.audience`	string	length ≤ 1000
`items[].options.duration_max`	integer	Default `60`; range 5–180
`items[].options.width`	integer	Default `1920`; range 640–3840
`items[].options.height`	integer	Default `1080`; range 360–2160
`items[].options.fps`	integer	Default `30`; range 24–60
`items[].options.subtitles`	boolean	Default `false`
`items[].options.music`	boolean	Default `true`
`items[].options.skill_id`	string	length ≤ 200; nullable
`items[].options.credit_budget`	integer	range 1–1000000; nullable
`items[].options.video_type`	string	One of: `project` `product` `personal` `corporate`; nullable
`items[].options.content_data`	map<string, string>
`items[].options.style_preset`	string	One of: `cinematic_realism` `clean_3d` `product_studio`; Default `cinematic_realism`
`items[].options.brand`	object
`items[].options.motion_style`	string	One of: `mono` `photo`; Default `mono`
`items[].options.photo_subject`	string	length ≤ 120
`items[].options.photo_license`	string	One of: `strict` `sharealike`; Default `strict`
`items[].webhook_url`	string	length ≤ 2000; nullable
`items[].plan_id`	string	nullable
`items[].template_id`	string	nullable
`items[].brand_id`	string	nullable
`items[].variables`	map<string, string>

Response 202 application/json

Name	Type	Description
`id`required	string
`name`required	string
`jobs`required	array<object>
`jobs[].id`required	string
`jobs[].project_id`required	string	nullable
`jobs[].batch_id`	string	nullable
`jobs[].parent_id`	string	nullable
`jobs[].status`required	string	One of: `queued` `running` `needs_input` `complete` `rejected` `failed` `cancelled`
`jobs[].stage`required	string	nullable
`jobs[].progress`required	integer	nullable
`jobs[].error`	string	nullable
`jobs[].created_at`required	number	nullable
`jobs[].updated_at`	number	nullable
`jobs[].started_at`	number	nullable
`jobs[].finished_at`	number	nullable
`jobs[].deleted_at`	number	nullable
`jobs[].recovery`required	object
`jobs[].recovery.attempt`required	integer
`jobs[].recovery.max_attempts`required	integer
`jobs[].recovery.retry_at`	number	nullable
`jobs[].result`	object	nullable
`jobs[].result.files`	map<string, string>	Signed download links; present on GET once complete/rejected; nullable
`jobs[].result.duration`	number	nullable
`jobs[].result.shot_count`	integer	nullable
`jobs[].result.visual_mix`	any
`jobs[].result.qa`	any
`jobs[].result.brief`	any
`jobs[].result.workflow`	string	nullable
`jobs[].result.routing`	any
`jobs[].result.input_required`	object	Why the job is `needs_input`: `code`, `actor`, `message` and what to send to /resume. A spending stop has `code: budget_approval` and `approvable: true` and carries no amounts; answer it with `POST /v1/videos/{id}/resume {"approve_budget": true}`; nullable
`jobs[].result.native_project`	any
`jobs[].requested_workflow`required	string
`data`required	array<object>	Alias of `jobs`, kept for v0.3 clients
`data[].id`required	string
`data[].project_id`required	string	nullable
`data[].batch_id`	string	nullable
`data[].parent_id`	string	nullable
`data[].status`required	string	One of: `queued` `running` `needs_input` `complete` `rejected` `failed` `cancelled`
`data[].stage`required	string	nullable
`data[].progress`required	integer	nullable
`data[].error`	string	nullable
`data[].created_at`required	number	nullable
`data[].updated_at`	number	nullable
`data[].started_at`	number	nullable
`data[].finished_at`	number	nullable
`data[].deleted_at`	number	nullable
`data[].recovery`required	object
`data[].recovery.attempt`required	integer
`data[].recovery.max_attempts`required	integer
`data[].recovery.retry_at`	number	nullable
`data[].result`	object	nullable
`data[].result.files`	map<string, string>	Signed download links; present on GET once complete/rejected; nullable
`data[].result.duration`	number	nullable
`data[].result.shot_count`	integer	nullable
`data[].result.visual_mix`	any
`data[].result.qa`	any
`data[].result.brief`	any
`data[].result.workflow`	string	nullable
`data[].result.routing`	any
`data[].result.input_required`	object	Why the job is `needs_input`: `code`, `actor`, `message` and what to send to /resume. A spending stop has `code: budget_approval` and `approvable: true` and carries no amounts; answer it with `POST /v1/videos/{id}/resume {"approve_budget": true}`; nullable
`data[].result.native_project`	any
`data[].requested_workflow`required	string
`counts`required	map<string, integer>
`webhook_signing_secret`	string	Set when an item carried `webhook_url`: the project secret that signs those per-job callbacks (`Vidgen-Signature`). Store it; verify deliveries with it; nullable

Example

curl -X POST "https://azimo.ai/v1/batches" \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"items": [{}]}'

Get Batch

GET/v1/batches/{batch_id}

API key requiredSuccess 200

Parameters

Name	Type	Description
`batch_id`requiredpath	string
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Response 200 application/json

Name	Type	Description
`id`required	string
`name`required	string
`jobs`required	array<object>
`jobs[].id`required	string
`jobs[].project_id`required	string	nullable
`jobs[].batch_id`	string	nullable
`jobs[].parent_id`	string	nullable
`jobs[].status`required	string	One of: `queued` `running` `needs_input` `complete` `rejected` `failed` `cancelled`
`jobs[].stage`required	string	nullable
`jobs[].progress`required	integer	nullable
`jobs[].error`	string	nullable
`jobs[].created_at`required	number	nullable
`jobs[].updated_at`	number	nullable
`jobs[].started_at`	number	nullable
`jobs[].finished_at`	number	nullable
`jobs[].deleted_at`	number	nullable
`jobs[].recovery`required	object
`jobs[].recovery.attempt`required	integer
`jobs[].recovery.max_attempts`required	integer
`jobs[].recovery.retry_at`	number	nullable
`jobs[].result`	object	nullable
`jobs[].result.files`	map<string, string>	Signed download links; present on GET once complete/rejected; nullable
`jobs[].result.duration`	number	nullable
`jobs[].result.shot_count`	integer	nullable
`jobs[].result.visual_mix`	any
`jobs[].result.qa`	any
`jobs[].result.brief`	any
`jobs[].result.workflow`	string	nullable
`jobs[].result.routing`	any
`jobs[].result.input_required`	object	Why the job is `needs_input`: `code`, `actor`, `message` and what to send to /resume. A spending stop has `code: budget_approval` and `approvable: true` and carries no amounts; answer it with `POST /v1/videos/{id}/resume {"approve_budget": true}`; nullable
`jobs[].result.native_project`	any
`jobs[].requested_workflow`required	string
`data`required	array<object>	Alias of `jobs`, kept for v0.3 clients
`data[].id`required	string
`data[].project_id`required	string	nullable
`data[].batch_id`	string	nullable
`data[].parent_id`	string	nullable
`data[].status`required	string	One of: `queued` `running` `needs_input` `complete` `rejected` `failed` `cancelled`
`data[].stage`required	string	nullable
`data[].progress`required	integer	nullable
`data[].error`	string	nullable
`data[].created_at`required	number	nullable
`data[].updated_at`	number	nullable
`data[].started_at`	number	nullable
`data[].finished_at`	number	nullable
`data[].deleted_at`	number	nullable
`data[].recovery`required	object
`data[].recovery.attempt`required	integer
`data[].recovery.max_attempts`required	integer
`data[].recovery.retry_at`	number	nullable
`data[].result`	object	nullable
`data[].result.files`	map<string, string>	Signed download links; present on GET once complete/rejected; nullable
`data[].result.duration`	number	nullable
`data[].result.shot_count`	integer	nullable
`data[].result.visual_mix`	any
`data[].result.qa`	any
`data[].result.brief`	any
`data[].result.workflow`	string	nullable
`data[].result.routing`	any
`data[].result.input_required`	object	Why the job is `needs_input`: `code`, `actor`, `message` and what to send to /resume. A spending stop has `code: budget_approval` and `approvable: true` and carries no amounts; answer it with `POST /v1/videos/{id}/resume {"approve_budget": true}`; nullable
`data[].result.native_project`	any
`data[].requested_workflow`required	string
`counts`required	map<string, integer>

Example

curl "https://azimo.ai/v1/batches/<batch_id>" \
  -H "Authorization: Bearer $AZIMO_API_KEY"

Events and webhooks

Instead of polling, receive status changes through signed webhooks or the event list.

List Events

GET/v1/events

API key requiredSuccess 200

Parameters

Name	Type	Description
`after`query	integer	Default `0`; range ≥ 0
`limit`query	integer	Default `50`; range 1–200
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Response 200 application/json

Name	Type	Description
`data`required	array<object>
`data[].id`required	string
`data[].sequence`required	integer
`data[].type`required	string
`data[].created_at`required	number
`data[].api_version`required	string
`data[].project_id`required	string	nullable
`data[].data`required	object
`next_cursor`required	integer	Sequence number to pass as `after`; unchanged when the page is empty
`has_more`	boolean	Default `false`

Example

curl "https://azimo.ai/v1/events" \
  -H "Authorization: Bearer $AZIMO_API_KEY"

List Webhooks

GET/v1/webhooks

API key requiredSuccess 200

Parameters

Name	Type	Description
`limit`query	integer	Default `50`; range 1–200
`cursor`query	string	length ≤ 256; nullable
`after`query	string	length ≤ 256; nullable
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Response 200 application/json

Name	Type	Description
`data`required	array<object>
`data[].id`required	string
`data[].project_id`required	string	nullable
`data[].kind`required	string
`data[].name`required	string
`data[].version`required	integer
`data[].created_at`required	number
`data[].updated_at`required	number
`data[].data`required	object
`data[].data.name`required	string
`data[].data.url`required	string
`data[].data.active`	boolean	Default `true`
`data[].data.has_secret`required	boolean
`next_cursor`	string	Opaque; pass as `cursor` (or the `after` alias) for the next page; nullable
`has_more`	boolean	Default `false`

Example

curl "https://azimo.ai/v1/webhooks" \
  -H "Authorization: Bearer $AZIMO_API_KEY"

Create Webhook

POST/v1/webhooks

API key requiredSuccess 201

Parameters

Name	Type	Description
`Idempotency-Key`header	string	A unique value you generate and keep; reuse it when retrying so the request never runs twice; length 1–128; nullable
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Request body application/json

Name	Type	Description
`name`	string	Default `Webhook`; length ≤ 160
`url`required	string	length ≤ 2000
`active`	boolean	Default `true`

Response 201 application/json

Name	Type	Description
`id`required	string
`project_id`required	string	nullable
`kind`required	string
`name`required	string
`version`required	integer
`created_at`required	number
`updated_at`required	number
`data`required	object
`data.name`required	string
`data.url`required	string
`data.active`	boolean	Default `true`
`data.has_secret`required	boolean
`signing_secret`required	string	Shown at creation/rotation and for the same actor's idempotent retry within 24 hours; nullable

Example

curl -X POST "https://azimo.ai/v1/webhooks" \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"url": "<url>"}'

Rotate Webhook Secret

POST/v1/webhooks/{webhook_id}/rotate-secret

API key requiredSuccess 200

Parameters

Name	Type	Description
`webhook_id`requiredpath	string
`expected_version`requiredquery	integer	range ≥ 1
`Idempotency-Key`header	string	A unique value you generate and keep; reuse it when retrying so the request never runs twice; length 1–128; nullable
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Response 200 application/json

Name	Type	Description
`id`required	string
`project_id`required	string	nullable
`kind`required	string
`name`required	string
`version`required	integer
`created_at`required	number
`updated_at`required	number
`data`required	object
`data.name`required	string
`data.url`required	string
`data.active`	boolean	Default `true`
`data.has_secret`required	boolean
`signing_secret`required	string	Shown at creation/rotation and for the same actor's idempotent retry within 24 hours; nullable

Example

curl -X POST "https://azimo.ai/v1/webhooks/<webhook_id>/rotate-secret?expected_version=<expected_version>" \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Update Webhook

PUT/v1/webhooks/{webhook_id}

API key requiredSuccess 200

Parameters

Name	Type	Description
`webhook_id`requiredpath	string
`expected_version`requiredquery	integer	range ≥ 1
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Request body application/json

Name	Type	Description
`name`	string	Default `Webhook`; length ≤ 160
`url`required	string	length ≤ 2000
`active`	boolean	Default `true`

Response 200 application/json

Name	Type	Description
`id`required	string
`project_id`required	string	nullable
`kind`required	string
`name`required	string
`version`required	integer
`created_at`required	number
`updated_at`required	number
`data`required	object
`data.name`required	string
`data.url`required	string
`data.active`	boolean	Default `true`
`data.has_secret`required	boolean

Example

curl -X PUT "https://azimo.ai/v1/webhooks/<webhook_id>?expected_version=<expected_version>" \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "<url>"}'

Delete Webhook

DELETE/v1/webhooks/{webhook_id}

API key requiredSuccess 200

Parameters

Name	Type	Description
`webhook_id`requiredpath	string
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Response 200 application/json

Name	Type	Description
`id`required	string
`deleted`	boolean	Default `true`

Example

curl -X DELETE "https://azimo.ai/v1/webhooks/<webhook_id>" \
  -H "Authorization: Bearer $AZIMO_API_KEY"

List Deliveries

GET/v1/webhook-deliveries

API key requiredSuccess 200

Parameters

Name	Type	Description
`limit`query	integer	Default `50`; range 1–200
`cursor`query	string	length ≤ 256; nullable
`after`query	string	length ≤ 256; nullable
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Response 200 application/json

Name	Type	Description
`data`required	array<object>
`data[].id`required	string
`data[].event_id`required	string
`data[].url`required	string
`data[].status`required	string
`data[].attempts`required	integer
`data[].last_error`required	string	nullable
`data[].delivered_at`required	number	nullable
`next_cursor`	string	Opaque; pass as `cursor` (or the `after` alias) for the next page; nullable
`has_more`	boolean	Default `false`

Example

curl "https://azimo.ai/v1/webhook-deliveries" \
  -H "Authorization: Bearer $AZIMO_API_KEY"

Replay

POST/v1/webhook-deliveries/{delivery_id}/replay

API key requiredSuccess 202

Parameters

Name	Type	Description
`delivery_id`requiredpath	string
`webhook_id`query	string	length ≤ 32; nullable
`Idempotency-Key`header	string	A unique value you generate and keep; reuse it when retrying so the request never runs twice; length 1–128; nullable
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Response 202 application/json

Name	Type	Description
`id`required	string
`status`required	string	One of: `pending`

Example

curl -X POST "https://azimo.ai/v1/webhook-deliveries/<delivery_id>/replay" \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Brands and templates

Save brand kits and reusable templates, then reference them when producing.

Listing

GET/v1/brands

API key requiredSuccess 200

Parameters

Name	Type	Description
`limit`query	integer	Default `50`; range 1–200
`cursor`query	string	length ≤ 256; nullable
`after`query	string	length ≤ 256; nullable
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Response 200 application/json

Name	Type	Description
`data`required	array<object>
`data[].id`required	string
`data[].project_id`required	string	nullable
`data[].kind`required	string
`data[].name`required	string
`data[].version`required	integer
`data[].created_at`required	number
`data[].updated_at`required	number
`data[].data`required	object
`next_cursor`	string	Opaque; pass as `cursor` (or the `after` alias) for the next page; nullable
`has_more`	boolean	Default `false`

Example

curl "https://azimo.ai/v1/brands" \
  -H "Authorization: Bearer $AZIMO_API_KEY"

Create

POST/v1/brands

API key requiredSuccess 201

Parameters

Name	Type	Description
`Idempotency-Key`header	string	A unique value you generate and keep; reuse it when retrying so the request never runs twice; length 1–128; nullable
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Request body application/json

Name	Type	Description
`name`required	string	length 1–120
`slogan`	string	length ≤ 500
`primary_color`	string	Default `#0F4C81`
`theme`	string	One of: `light` `dark`; Default `dark`
`assets`	array<string>	up to 30 items
`notes`	string	length ≤ 2000

Response 201 application/json

Name	Type	Description
`id`required	string
`project_id`required	string	nullable
`kind`required	string
`name`required	string
`version`required	integer
`created_at`required	number
`updated_at`required	number
`data`required	object

Example

curl -X POST "https://azimo.ai/v1/brands" \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "<name>"}'

Get

GET/v1/brands/{resource_id}

API key requiredSuccess 200

Parameters

Name	Type	Description
`resource_id`requiredpath	string
`version`query	integer	range ≥ 1; nullable
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Response 200 application/json

Name	Type	Description
`id`required	string
`project_id`required	string	nullable
`kind`required	string
`name`required	string
`version`required	integer
`created_at`required	number
`updated_at`required	number
`data`required	object

Example

curl "https://azimo.ai/v1/brands/<resource_id>" \
  -H "Authorization: Bearer $AZIMO_API_KEY"

Revise

PUT/v1/brands/{resource_id}

API key requiredSuccess 200

Parameters

Name	Type	Description
`resource_id`requiredpath	string
`expected_version`requiredquery	integer	range ≥ 1
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Request body application/json

Name	Type	Description
`name`required	string	length 1–120
`slogan`	string	length ≤ 500
`primary_color`	string	Default `#0F4C81`
`theme`	string	One of: `light` `dark`; Default `dark`
`assets`	array<string>	up to 30 items
`notes`	string	length ≤ 2000

Response 200 application/json

Name	Type	Description
`id`required	string
`project_id`required	string	nullable
`kind`required	string
`name`required	string
`version`required	integer
`created_at`required	number
`updated_at`required	number
`data`required	object

Example

curl -X PUT "https://azimo.ai/v1/brands/<resource_id>?expected_version=<expected_version>" \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "<name>"}'

Remove

DELETE/v1/brands/{resource_id}

API key requiredSuccess 200

Parameters

Name	Type	Description
`resource_id`requiredpath	string
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Response 200 application/json

Name	Type	Description
`id`required	string
`deleted`	boolean	Default `true`

Example

curl -X DELETE "https://azimo.ai/v1/brands/<resource_id>" \
  -H "Authorization: Bearer $AZIMO_API_KEY"

Listing

GET/v1/templates

API key requiredSuccess 200

Parameters

Name	Type	Description
`limit`query	integer	Default `50`; range 1–200
`cursor`query	string	length ≤ 256; nullable
`after`query	string	length ≤ 256; nullable
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Response 200 application/json

Name	Type	Description
`data`required	array<object>
`data[].id`required	string
`data[].project_id`required	string	nullable
`data[].kind`required	string
`data[].name`required	string
`data[].version`required	integer
`data[].created_at`required	number
`data[].updated_at`required	number
`data[].data`required	object
`next_cursor`	string	Opaque; pass as `cursor` (or the `after` alias) for the next page; nullable
`has_more`	boolean	Default `false`

Example

curl "https://azimo.ai/v1/templates" \
  -H "Authorization: Bearer $AZIMO_API_KEY"

Create

POST/v1/templates

API key requiredSuccess 201

Parameters

Name	Type	Description
`Idempotency-Key`header	string	A unique value you generate and keep; reuse it when retrying so the request never runs twice; length 1–128; nullable
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Request body application/json

Name	Type	Description
`name`required	string	length 1–160
`prompt`required	string	Use $variable or ${variable} placeholders; length 10–4000
`options`	object
`options.workflow`	string	One of: `auto` `explainer` `short_drama` `creative_video` `motion_explainer` `profile_card` `product_pitch`; Default `explainer`
`options.goal`	string	length ≤ 2000
`options.audience`	string	length ≤ 1000
`options.duration_max`	integer	Default `60`; range 5–180
`options.width`	integer	Default `1920`; range 640–3840
`options.height`	integer	Default `1080`; range 360–2160
`options.fps`	integer	Default `30`; range 24–60
`options.subtitles`	boolean	Default `false`
`options.music`	boolean	Default `true`
`options.skill_id`	string	length ≤ 200; nullable
`options.credit_budget`	integer	range 1–1000000; nullable
`options.video_type`	string	One of: `project` `product` `personal` `corporate`; nullable
`options.content_data`	map<string, string>
`options.style_preset`	string	One of: `cinematic_realism` `clean_3d` `product_studio`; Default `cinematic_realism`
`options.brand`	object
`options.motion_style`	string	One of: `mono` `photo`; Default `mono`
`options.photo_subject`	string	length ≤ 120
`options.photo_license`	string	One of: `strict` `sharealike`; Default `strict`
`assets`	array<string>	up to 30 items
`brand_id`	string	nullable

Response 201 application/json

Name	Type	Description
`id`required	string
`project_id`required	string	nullable
`kind`required	string
`name`required	string
`version`required	integer
`created_at`required	number
`updated_at`required	number
`data`required	object

Example

curl -X POST "https://azimo.ai/v1/templates" \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "<name>", "prompt": "<prompt>"}'

Get

GET/v1/templates/{resource_id}

API key requiredSuccess 200

Parameters

Name	Type	Description
`resource_id`requiredpath	string
`version`query	integer	range ≥ 1; nullable
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Response 200 application/json

Name	Type	Description
`id`required	string
`project_id`required	string	nullable
`kind`required	string
`name`required	string
`version`required	integer
`created_at`required	number
`updated_at`required	number
`data`required	object

Example

curl "https://azimo.ai/v1/templates/<resource_id>" \
  -H "Authorization: Bearer $AZIMO_API_KEY"

Revise

PUT/v1/templates/{resource_id}

API key requiredSuccess 200

Parameters

Name	Type	Description
`resource_id`requiredpath	string
`expected_version`requiredquery	integer	range ≥ 1
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Request body application/json

Name	Type	Description
`name`required	string	length 1–160
`prompt`required	string	Use $variable or ${variable} placeholders; length 10–4000
`options`	object
`options.workflow`	string	One of: `auto` `explainer` `short_drama` `creative_video` `motion_explainer` `profile_card` `product_pitch`; Default `explainer`
`options.goal`	string	length ≤ 2000
`options.audience`	string	length ≤ 1000
`options.duration_max`	integer	Default `60`; range 5–180
`options.width`	integer	Default `1920`; range 640–3840
`options.height`	integer	Default `1080`; range 360–2160
`options.fps`	integer	Default `30`; range 24–60
`options.subtitles`	boolean	Default `false`
`options.music`	boolean	Default `true`
`options.skill_id`	string	length ≤ 200; nullable
`options.credit_budget`	integer	range 1–1000000; nullable
`options.video_type`	string	One of: `project` `product` `personal` `corporate`; nullable
`options.content_data`	map<string, string>
`options.style_preset`	string	One of: `cinematic_realism` `clean_3d` `product_studio`; Default `cinematic_realism`
`options.brand`	object
`options.motion_style`	string	One of: `mono` `photo`; Default `mono`
`options.photo_subject`	string	length ≤ 120
`options.photo_license`	string	One of: `strict` `sharealike`; Default `strict`
`assets`	array<string>	up to 30 items
`brand_id`	string	nullable

Response 200 application/json

Name	Type	Description
`id`required	string
`project_id`required	string	nullable
`kind`required	string
`name`required	string
`version`required	integer
`created_at`required	number
`updated_at`required	number
`data`required	object

Example

curl -X PUT "https://azimo.ai/v1/templates/<resource_id>?expected_version=<expected_version>" \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "<name>", "prompt": "<prompt>"}'

Remove

DELETE/v1/templates/{resource_id}

API key requiredSuccess 200

Parameters

Name	Type	Description
`resource_id`requiredpath	string
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Response 200 application/json

Name	Type	Description
`id`required	string
`deleted`	boolean	Default `true`

Example

curl -X DELETE "https://azimo.ai/v1/templates/<resource_id>" \
  -H "Authorization: Bearer $AZIMO_API_KEY"

Projects, keys and audit

Manage projects and API keys, and read the change log.

List Projects

GET/v1/projects

API key requiredSuccess 200

Parameters

Name	Type	Description
`limit`query	integer	Default `50`; range 1–200
`cursor`query	string	length ≤ 256; nullable
`after`query	string	length ≤ 256; nullable
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Response 200 application/json

Name	Type	Description
`data`required	array<object>
`data[].id`required	string
`data[].organization_id`required	string
`data[].name`required	string
`data[].created_at`required	number
`next_cursor`	string	Opaque; pass as `cursor` (or the `after` alias) for the next page; nullable
`has_more`	boolean	Default `false`

Example

curl "https://azimo.ai/v1/projects" \
  -H "Authorization: Bearer $AZIMO_API_KEY"

Create Project

POST/v1/projects

API key requiredSuccess 201

Parameters

Name	Type	Description
`Idempotency-Key`header	string	A unique value you generate and keep; reuse it when retrying so the request never runs twice; length 1–128; nullable
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Request body application/json

Name	Type	Description
`name`required	string	length 1–120

Response 201 application/json

Name	Type	Description
`id`required	string
`organization_id`required	string
`name`required	string
`created_at`required	number

Example

curl -X POST "https://azimo.ai/v1/projects" \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "<name>"}'

Delete Project

DELETE/v1/projects/{project_id}

API key requiredSuccess 200

Parameters

Name	Type	Description
`project_id`requiredpath	string
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Response 200 application/json

Name	Type	Description
`id`required	string
`deleted`	boolean	Default `true`

Example

curl -X DELETE "https://azimo.ai/v1/projects/<project_id>" \
  -H "Authorization: Bearer $AZIMO_API_KEY"

List Keys

GET/v1/api-keys

API key requiredSuccess 200

Parameters

Name	Type	Description
`limit`query	integer	Default `50`; range 1–200
`cursor`query	string	length ≤ 256; nullable
`after`query	string	length ≤ 256; nullable
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Response 200 application/json

Name	Type	Description
`data`required	array<object>
`data[].id`required	string
`data[].name`required	string	Label given at creation (also returned as `owner`)
`data[].owner`required	string
`data[].prefix`required	string	nullable
`data[].organization_id`required	string	nullable
`data[].project_id`	string	Set when the key is bound to one project; nullable
`data[].role`required	string	One of: `owner` `editor` `viewer`
`data[].active`required	boolean
`data[].created_at`required	number	nullable
`data[].last_used_at`	number	nullable
`data[].expires_at`	number	nullable
`data[].revoked_at`	number	nullable
`next_cursor`	string	Opaque; pass as `cursor` (or the `after` alias) for the next page; nullable
`has_more`	boolean	Default `false`

Example

curl "https://azimo.ai/v1/api-keys" \
  -H "Authorization: Bearer $AZIMO_API_KEY"

Create Key

POST/v1/api-keys

API key requiredSuccess 201

Parameters

Name	Type	Description
`Idempotency-Key`header	string	A unique value you generate and keep; reuse it when retrying so the request never runs twice; length 1–128; nullable
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Request body application/json

Name	Type	Description
`name`required	string	length 1–120
`role`	string	One of: `owner` `editor` `viewer`; Default `editor`
`project_id`	string	nullable
`monthly_budget_usd`	number	range ≥ 0; nullable
`rate_per_hour`	integer	range ≥ 1; nullable

Response 201 application/json

Name	Type	Description
`id`required	string
`name`required	string	Label given at creation (also returned as `owner`)
`owner`required	string
`prefix`required	string	nullable
`organization_id`required	string	nullable
`project_id`	string	Set when the key is bound to one project; nullable
`role`required	string	One of: `owner` `editor` `viewer`
`active`required	boolean
`created_at`required	number	nullable
`last_used_at`	number	nullable
`expires_at`	number	nullable
`revoked_at`	number	nullable
`key`required	string	The bearer secret; shown once (an idempotent replay returns the same value)

Example

curl -X POST "https://azimo.ai/v1/api-keys" \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "<name>"}'

Rotate Key

POST/v1/api-keys/{key_id}/rotate

API key requiredSuccess 200

The old secret dies at once, or after grace_seconds so running fleets can switch without downtime.

Parameters

Name	Type	Description
`key_id`requiredpath	string
`grace_seconds`query	integer	Default `0`; range 0–604800
`Idempotency-Key`header	string	A unique value you generate and keep; reuse it when retrying so the request never runs twice; length 1–128; nullable
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Response 200 application/json

Name	Type	Description
`id`required	string
`key`required	string
`previous_id`required	string
`previous_expires_in`required	integer	nullable

Example

curl -X POST "https://azimo.ai/v1/api-keys/<key_id>/rotate" \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Revoke Key

DELETE/v1/api-keys/{key_id}

API key requiredSuccess 200

Parameters

Name	Type	Description
`key_id`requiredpath	string
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Response 200 application/json

Name	Type	Description
`id`required	string
`active`	boolean	Default `false`

Example

curl -X DELETE "https://azimo.ai/v1/api-keys/<key_id>" \
  -H "Authorization: Bearer $AZIMO_API_KEY"

Audit Log

GET/v1/audit

API key requiredSuccess 200

Identity and configuration changes for this organization (keys, projects, webhooks), oldest first from after.

Parameters

Name	Type	Description
`after`query	integer	Default `0`; range ≥ 0
`limit`query	integer	Default `50`; range 1–200
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Response 200 application/json

Name	Type	Description
`data`required	array<object>
`data[].id`required	string
`data[].sequence`required	integer
`data[].type`required	string
`data[].created_at`required	number
`data[].api_version`required	string
`data[].project_id`required	string	nullable
`data[].data`required	object
`next_cursor`required	integer	Sequence number to pass as `after`; unchanged when the page is empty
`has_more`	boolean	Default `false`

Example

curl "https://azimo.ai/v1/audit" \
  -H "Authorization: Bearer $AZIMO_API_KEY"

Wallet and usage

Balance, statement and usage, and online top-up.

Wallet

GET/v1/wallet

API key requiredSuccess 200

Parameters

Name	Type	Description
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Response 200 application/json

Name	Type	Description
`balance_cents`required	integer
`held_cents`required	integer
`available_cents`required	integer
`low_balance_cents`required	integer	nullable
`currency`required	string
`organization_id`required	string

Example

curl "https://azimo.ai/v1/wallet" \
  -H "Authorization: Bearer $AZIMO_API_KEY"

Wallet Entries

GET/v1/wallet/entries

API key requiredSuccess 200

Parameters

Name	Type	Description
`after`query	string	length ≤ 64; nullable
`limit`query	integer	Default `50`; range 1–200
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Response 200 application/json

Name	Type	Description
`data`required	array<object>
`data[].id`required	string
`data[].organization_id`required	string
`data[].kind`required	string
`data[].amount_cents`required	integer
`data[].hold_cents`required	integer
`data[].job_id`required	string	nullable
`data[].note`required	string	nullable
`data[].actor`required	string	nullable
`data[].created_at`required	number
`next_cursor`	string	Opaque; pass as `cursor` (or the `after` alias) for the next page; nullable
`has_more`	boolean	Default `false`

Example

curl "https://azimo.ai/v1/wallet/entries" \
  -H "Authorization: Bearer $AZIMO_API_KEY"

Checkout

POST/v1/wallet/checkout

API key requiredSuccess 201

Parameters

Name	Type	Description
`Idempotency-Key`requiredheader	string	A unique value you generate and keep; reuse it when retrying so the request never runs twice; length 1–128
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Request body application/json

Name	Type	Description
`amount_cents`required	integer	USD cents, $5–$10,000; range 500–1000000

Response 201 application/json

Name	Type	Description
`id`required	string
`url`required	string
`amount_cents`required	integer
`currency`	string	Default `USD`

Example

curl -X POST "https://azimo.ai/v1/wallet/checkout" \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents": 500}'

Usage

GET/v1/usage

API key requiredSuccess 200

The amount billed for this project's paid calls in [from, to) (default: the last 30 days), plus job counts, grouped on request. group_by=job pages by job id with after; group_by=workflow reads at most 5000 jobs' request options.

Parameters

Name	Type	Description
`from`query	number	range ≥ 0; nullable
`to`query	number	range ≥ 0; nullable
`group_by`query	string	Default `none`
`limit`query	integer	Default `50`; range 1–200
`after`query	string	length ≤ 32; nullable
`X-Project-ID`header	string	The project to act on; the default project when omitted; nullable

Response 200 application/json

Name	Type	Description
`project_id`required	string
`range`required	map<string, number>
`jobs`required	map<string, integer>
`list_usd`required	number	Amount billed for the paid calls in the range
`group_by`required	string
`groups`required	array<object>	nullable
`next_cursor`required	string	nullable

Example

curl "https://azimo.ai/v1/usage" \
  -H "Authorization: Bearer $AZIMO_API_KEY"

Service health

Health checks; no key needed.

Healthz

GET/healthz

No authSuccess 200

Response 200 application/json

Example

curl "https://azimo.ai/healthz"

Readyz

GET/readyz

No authSuccess 200

Response 200 application/json

Name	Type	Description
`ok`required	boolean
`db`required	boolean
`version`required	string
`queue_depth`required	integer
`running`required	integer
`worker_seen_at`	number	Latest job start or running-job heartbeat; nullable
`worker_alive`required	boolean	A worker sent a durable heartbeat within the last 5 minutes

Other status codes

503 Service Unavailable

Example

curl "https://azimo.ai/readyz"

Basics#

Errors

Account and capabilities#

Parameters

Response 200 application/json

Example

Parameters

Response 200 application/json

Example

Parameters

Response 200 application/json

Example

Parameters

Response 200 application/json

Example

Parameters

Response 200 application/json

Example

Assets#

Parameters

Response 200 application/json

Example

Parameters

Request body multipart/form-data

Response 201 application/json

Example

Parameters

Response 200 application/json

Example

Parameters

Response 200 application/json

Example

Parameters

Response 200 application/octet-stream

Example

Plans#

Parameters

Response 200 application/json

Example

Parameters

Request body application/json

Response 201 application/json

Example

Parameters

Response 200 application/json

Example

Parameters

Request body application/json

Response 200 application/json

Example

Videos#

Parameters

Response 200 application/json

Example

Parameters

Request body application/json

Response 202 application/json

Example

Parameters

Request body application/json

Response 202 application/json

Example

Parameters

Request body application/json

Response 202 application/json

Example

Parameters

Response 200 application/json

Example

Parameters

Response 200 application/json

Example

Parameters

Response 200 application/json

Example

Parameters

Response 200 application/octet-stream

Example

Batches#

Parameters

Basics

Account and capabilities

Assets

Plans

Videos

Batches

Events and webhooks