> 以下是 Azimo 开发者文档「API 参考」的 Markdown 版本，供 AI 助手参考。
> - Azimo（https://azimo.ai）是 AI 商业视频制作服务：一段文字加几份资料，交付一条通过质检的商用视频；提供异步 REST API、Python / TypeScript SDK、命令行 azimo 和 MCP 服务。
> - Base URL：https://azimo.ai
> - 鉴权：每个 /v1 请求带 `Authorization: Bearer <API key>`（在 https://azimo.ai/console#account 创建 Key）；用 `X-Project-ID` 选择项目，省略时使用默认项目。
> - 本页地址：https://azimo.ai/developers/api
> - 价格不公开：请联系 sales@azimo.ai。

# API 参考

每个接口的参数、请求体、返回字段和 curl 示例，由线上接口定义实时生成。

## 基础约定

- **Base URL**: `https://azimo.ai`
- **鉴权**: 每个 `/v1` 请求带 `Authorization: Bearer <API key>`。登录后在[个人中心](https://azimo.ai/console#account)创建 Key，原始 Key 只显示一次。
- **项目**: 用 `X-Project-ID` 选择项目，省略时使用默认项目。
- **幂等**: 创建类请求带 `Idempotency-Key`，超时重试时复用同一个值；同一个值配不同的请求内容会返回 409。
- **异步制作**: `POST /v1/videos` 返回 202 和视频 ID；轮询 `GET /v1/videos/{job_id}` 或用 Webhook 接收结果。`needs_input` 表示还缺材料，不代表完成。
- **分页**: 列表返回 `data`、`next_cursor` 和 `has_more`；把 `next_cursor` 作为 `cursor` 传入即可取下一页。
- **价格**: API 不返回任何价格。报价请联系 sales@azimo.ai。

### 错误

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `error` | object | 是 |  |
| `error.code` | 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` | string | 是 |  |
| `error.details` | any |  | Structured context: validation errors, unmet workflow requirements, or null |
| `error.request_id` | string | 是 | 可为 null |

- `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

## 账户与能力

当前 Key 的身份，以及可用的工作流和视频类型。

### GET /v1/me — Me

需要 API Key。 成功返回: 200.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**返回 200**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 是 |  |
| `key_id` | string | 是 | Same as `id` |
| `organization_id` | string | 是 |  |
| `project_id` | string | 是 |  |
| `role` | string | 是 | 可选值：`owner` `editor` `viewer` |
| `billing_mode` | string | 是 | 可选值：`budget` `prepaid` |
| `wallet` | object | 是 |  |
| `permissions` | map<string, boolean> | 是 |  |

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

### GET /v1/workflows — Workflows

需要 API Key。 成功返回: 200.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**返回 200**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `router` | object | 是 |  |
| `workflows` | map<string, object> | 是 |  |

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

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

需要 API Key。 成功返回: 200.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**返回 200**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `data` | array<any> | 是 |  |

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

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

需要 API Key。 成功返回: 200.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `lang` (query) | string |  | Display language, `zh` (default) or `en`; when absent the first `zh`/`en` entry of `Accept-Language` is used; 长度 ≤ 16; 可为 null |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |
| `accept-language` (header) | string |  | 可为 null |

**返回 200**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `data` | array<object> | 是 |  |
| `data[].id` | string | 是 |  |
| `data[].version` | any | 是 |  |
| `data[].template` | any |  |  |
| `next_cursor` | string |  | Opaque; pass as `cursor` (or the `after` alias) for the next page; 可为 null |
| `has_more` | boolean |  | 默认 `false` |

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

### GET /v1/playground — Playground

需要 API Key。 成功返回: 200.

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

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `lang` (query) | string |  | Display language, `zh` (default) or `en`; when absent the first `zh`/`en` entry of `Accept-Language` is used; 长度 ≤ 16; 可为 null |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |
| `accept-language` (header) | string |  | 可为 null |

**返回 200**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `data` | array<object> | 是 |  |
| `data[].id` | string | 是 | Stable catalogue id |
| `data[].name` | string | 是 |  |
| `data[].summary` | string | 是 | One benefit-oriented sentence |
| `data[].workflow` | string | 是 | Backend routing value for `options.workflow`; null when the entry cannot be started yet; 可为 null |
| `data[].video_type` | string | 是 | `options.video_type` for structured explainers, otherwise null; 可为 null |
| `data[].aspect` | string | 是 | 可选值：`16:9` `9:16` `1:1` |
| `data[].duration` | integer | 是 | Default `options.duration_max` in seconds |
| `data[].duration_range` | array<integer> | 是 | [minimum, maximum] seconds the workflow accepts |
| `data[].needs_assets` | boolean | 是 | Reference material (photos, product pictures) is strongly recommended |
| `data[].available` | boolean | 是 |  |
| `data[].reason` | string | 是 | Why `available` is false: coming_soon, not_configured (this environment) or contact_sales (not sold to this account); 可选值：`coming_soon` `not_configured` `contact_sales`; 可为 null |
| `data[].coming_soon` | boolean | 是 |  |
| `data[].example` | object | 是 |  |
| `data[].example.prompt` | string | 是 | A ready-to-run creative brief for `POST /v1/videos` or `POST /v1/plans` |
| `data[].example.content_data` | map<string, string> | 是 | 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"
```

## 素材

上传 PDF、PPT、图片等素材，拿到素材 ID 后在方案里引用。

### GET /v1/assets — List Assets

需要 API Key。 成功返回: 200.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `limit` (query) | integer |  | 默认 `50`; 范围 1–200 |
| `cursor` (query) | string |  | 长度 ≤ 256; 可为 null |
| `after` (query) | string |  | 长度 ≤ 256; 可为 null |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**返回 200**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `data` | array<object> | 是 |  |
| `data[].id` | string | 是 |  |
| `data[].project_id` | string | 是 | 可为 null |
| `data[].filename` | string | 是 |  |
| `data[].bytes` | integer | 是 |  |
| `data[].sha256` | string | 是 |  |
| `data[].created_at` | number | 是 |  |
| `next_cursor` | string |  | Opaque; pass as `cursor` (or the `after` alias) for the next page; 可为 null |
| `has_more` | boolean |  | 默认 `false` |

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

### POST /v1/assets — Upload Asset

需要 API Key。 成功返回: 201.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `Idempotency-Key` (header) | string |  | 调用方生成并保存的唯一值；超时重试时复用它，同一请求不会被执行两次; 长度 1–128; 可为 null |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**请求体** (multipart/form-data)

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `file` | file | 是 |  |

**返回 201**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 是 |  |
| `project_id` | string | 是 | 可为 null |
| `filename` | string | 是 |  |
| `bytes` | integer | 是 |  |
| `sha256` | string | 是 |  |
| `created_at` | number | 是 |  |

```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

需要 API Key。 成功返回: 200.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `asset_id` (path) | string | 是 |  |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**返回 200**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 是 |  |
| `project_id` | string | 是 | 可为 null |
| `filename` | string | 是 |  |
| `bytes` | integer | 是 |  |
| `sha256` | string | 是 |  |
| `created_at` | number | 是 |  |

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

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

需要 API Key。 成功返回: 200.

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

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `asset_id` (path) | string | 是 |  |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**返回 200**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 是 |  |
| `deleted` | boolean |  | 默认 `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

需要 API Key。 成功返回: 200.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `asset_id` (path) | string | 是 |  |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

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

## 方案

制作前先出方案：冻结工作流、规格、素材和结构，告诉你还缺什么。

### GET /v1/plans — List Plans

需要 API Key。 成功返回: 200.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `limit` (query) | integer |  | 默认 `50`; 范围 1–200 |
| `cursor` (query) | string |  | 长度 ≤ 256; 可为 null |
| `after` (query) | string |  | 长度 ≤ 256; 可为 null |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**返回 200**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `data` | array<object> | 是 |  |
| `data[].id` | string | 是 |  |
| `data[].project_id` | string | 是 | 可为 null |
| `data[].kind` | string | 是 |  |
| `data[].name` | string | 是 |  |
| `data[].version` | integer | 是 |  |
| `data[].created_at` | number | 是 |  |
| `data[].updated_at` | number | 是 |  |
| `data[].data` | object | 是 |  |
| `data[].data.status` | string | 是 | 可选值：`planning` `ready` `needs_input` `unavailable` |
| `data[].data.request` | object | 是 |  |
| `data[].data.assets` | array<object> |  |  |
| `data[].data.routing` | object |  | 可为 null |
| `data[].data.requirements` | array<object> |  |  |
| `data[].data.reason` | string |  | 可为 null |
| `data[].data.job_id` | string |  | The production this plan started; a plan starts at most one; 可为 null |
| `next_cursor` | string |  | Opaque; pass as `cursor` (or the `after` alias) for the next page; 可为 null |
| `has_more` | boolean |  | 默认 `false` |

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

### POST /v1/plans — Create Plan

需要 API Key。 成功返回: 201.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `Idempotency-Key` (header) | string |  | 调用方生成并保存的唯一值；超时重试时复用它，同一请求不会被执行两次; 长度 1–128; 可为 null |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**请求体** (application/json)

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `prompt` | string |  | 长度 ≤ 4000 |
| `assets` | array<string> |  | 最多 30 项 |
| `options` | object |  |  |
| `options.workflow` | string |  | 可选值：`auto` `explainer` `short_drama` `creative_video` `motion_explainer` `profile_card` `product_pitch`; 默认 `explainer` |
| `options.goal` | string |  | 长度 ≤ 2000 |
| `options.audience` | string |  | 长度 ≤ 1000 |
| `options.duration_max` | integer |  | 默认 `60`; 范围 5–180 |
| `options.width` | integer |  | 默认 `1920`; 范围 640–3840 |
| `options.height` | integer |  | 默认 `1080`; 范围 360–2160 |
| `options.fps` | integer |  | 默认 `30`; 范围 24–60 |
| `options.subtitles` | boolean |  | 默认 `false` |
| `options.music` | boolean |  | 默认 `true` |
| `options.skill_id` | string |  | 长度 ≤ 200; 可为 null |
| `options.credit_budget` | integer |  | 范围 1–1000000; 可为 null |
| `options.video_type` | string |  | 可选值：`project` `product` `personal` `corporate`; 可为 null |
| `options.content_data` | map<string, string> |  |  |
| `options.style_preset` | string |  | 可选值：`cinematic_realism` `clean_3d` `product_studio`; 默认 `cinematic_realism` |
| `options.brand` | object |  |  |
| `options.motion_style` | string |  | 可选值：`mono` `photo`; 默认 `mono` |
| `options.photo_subject` | string |  | 长度 ≤ 120 |
| `options.photo_license` | string |  | 可选值：`strict` `sharealike`; 默认 `strict` |
| `webhook_url` | string |  | 长度 ≤ 2000; 可为 null |
| `plan_id` | string |  | 可为 null |
| `template_id` | string |  | 可为 null |
| `brand_id` | string |  | 可为 null |
| `variables` | map<string, string> |  |  |

**返回 201**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 是 |  |
| `project_id` | string | 是 | 可为 null |
| `kind` | string | 是 |  |
| `name` | string | 是 |  |
| `version` | integer | 是 |  |
| `created_at` | number | 是 |  |
| `updated_at` | number | 是 |  |
| `data` | object | 是 |  |
| `data.status` | string | 是 | 可选值：`planning` `ready` `needs_input` `unavailable` |
| `data.request` | object | 是 |  |
| `data.assets` | array<object> |  |  |
| `data.routing` | object |  | 可为 null |
| `data.requirements` | array<object> |  |  |
| `data.reason` | string |  | 可为 null |
| `data.job_id` | string |  | The production this plan started; a plan starts at most one; 可为 null |

```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

需要 API Key。 成功返回: 200.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `plan_id` (path) | string | 是 |  |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**返回 200**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 是 |  |
| `project_id` | string | 是 | 可为 null |
| `kind` | string | 是 |  |
| `name` | string | 是 |  |
| `version` | integer | 是 |  |
| `created_at` | number | 是 |  |
| `updated_at` | number | 是 |  |
| `data` | object | 是 |  |
| `data.status` | string | 是 | 可选值：`planning` `ready` `needs_input` `unavailable` |
| `data.request` | object | 是 |  |
| `data.assets` | array<object> |  |  |
| `data.routing` | object |  | 可为 null |
| `data.requirements` | array<object> |  |  |
| `data.reason` | string |  | 可为 null |
| `data.job_id` | string |  | The production this plan started; a plan starts at most one; 可为 null |

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

### POST /v1/route — Preview Route

需要 API Key。 成功返回: 200.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `Idempotency-Key` (header) | string |  | 调用方生成并保存的唯一值；超时重试时复用它，同一请求不会被执行两次; 长度 1–128; 可为 null |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**请求体** (application/json)

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `prompt` | string |  | 长度 ≤ 4000 |
| `assets` | array<string> |  | 最多 30 项 |
| `options` | object |  |  |
| `options.workflow` | string |  | 可选值：`auto` `explainer` `short_drama` `creative_video` `motion_explainer` `profile_card` `product_pitch`; 默认 `explainer` |
| `options.goal` | string |  | 长度 ≤ 2000 |
| `options.audience` | string |  | 长度 ≤ 1000 |
| `options.duration_max` | integer |  | 默认 `60`; 范围 5–180 |
| `options.width` | integer |  | 默认 `1920`; 范围 640–3840 |
| `options.height` | integer |  | 默认 `1080`; 范围 360–2160 |
| `options.fps` | integer |  | 默认 `30`; 范围 24–60 |
| `options.subtitles` | boolean |  | 默认 `false` |
| `options.music` | boolean |  | 默认 `true` |
| `options.skill_id` | string |  | 长度 ≤ 200; 可为 null |
| `options.credit_budget` | integer |  | 范围 1–1000000; 可为 null |
| `options.video_type` | string |  | 可选值：`project` `product` `personal` `corporate`; 可为 null |
| `options.content_data` | map<string, string> |  |  |
| `options.style_preset` | string |  | 可选值：`cinematic_realism` `clean_3d` `product_studio`; 默认 `cinematic_realism` |
| `options.brand` | object |  |  |
| `options.motion_style` | string |  | 可选值：`mono` `photo`; 默认 `mono` |
| `options.photo_subject` | string |  | 长度 ≤ 120 |
| `options.photo_license` | string |  | 可选值：`strict` `sharealike`; 默认 `strict` |
| `webhook_url` | string |  | 长度 ≤ 2000; 可为 null |
| `plan_id` | string |  | 可为 null |
| `template_id` | string |  | 可为 null |
| `brand_id` | string |  | 可为 null |
| `variables` | map<string, string> |  |  |

**返回 200**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `plan_id` | string | 是 |  |
| `workflow` | string |  | 可为 null |
| `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>"]}'
```

## 视频

确认方案后制作视频，查询进度，取回成片，续跑、修改或取消。

### GET /v1/videos — List Videos

需要 API Key。 成功返回: 200.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `limit` (query) | integer |  | 默认 `50`; 范围 1–200 |
| `cursor` (query) | string |  | 长度 ≤ 256; 可为 null |
| `after` (query) | string |  | 长度 ≤ 256; 可为 null |
| `status` (query) | string |  | 可选值：`queued` `running` `needs_input` `complete` `rejected` `failed` `cancelled`; 可为 null |
| `batch_id` (query) | string |  | 长度 ≤ 32; 可为 null |
| `created_after` (query) | number |  | 范围 ≥ 0; 可为 null |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**返回 200**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `data` | array<object> | 是 |  |
| `data[].id` | string | 是 |  |
| `data[].project_id` | string | 是 | 可为 null |
| `data[].batch_id` | string |  | 可为 null |
| `data[].parent_id` | string |  | 可为 null |
| `data[].status` | string | 是 | 可选值：`queued` `running` `needs_input` `complete` `rejected` `failed` `cancelled` |
| `data[].stage` | string | 是 | 可为 null |
| `data[].progress` | integer | 是 | 可为 null |
| `data[].error` | string |  | 可为 null |
| `data[].created_at` | number | 是 | 可为 null |
| `data[].updated_at` | number |  | 可为 null |
| `data[].started_at` | number |  | 可为 null |
| `data[].finished_at` | number |  | 可为 null |
| `data[].deleted_at` | number |  | 可为 null |
| `data[].recovery` | object | 是 |  |
| `data[].recovery.attempt` | integer | 是 |  |
| `data[].recovery.max_attempts` | integer | 是 |  |
| `data[].recovery.retry_at` | number |  | 可为 null |
| `data[].result` | object |  | 可为 null |
| `data[].result.files` | map<string, string> |  | Signed download links; present on GET once complete/rejected; 可为 null |
| `data[].result.duration` | number |  | 可为 null |
| `data[].result.shot_count` | integer |  | 可为 null |
| `data[].result.visual_mix` | any |  |  |
| `data[].result.qa` | any |  |  |
| `data[].result.brief` | any |  |  |
| `data[].result.workflow` | string |  | 可为 null |
| `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}`; 可为 null |
| `data[].result.native_project` | any |  |  |
| `data[].requested_workflow` | string | 是 |  |
| `next_cursor` | string |  | Opaque; pass as `cursor` (or the `after` alias) for the next page; 可为 null |
| `has_more` | boolean |  | 默认 `false` |

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

### POST /v1/videos — Create Video

需要 API Key。 成功返回: 202.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `Idempotency-Key` (header) | string |  | 调用方生成并保存的唯一值；超时重试时复用它，同一请求不会被执行两次; 长度 1–128; 可为 null |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**请求体** (application/json)

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `prompt` | string |  | 长度 ≤ 4000 |
| `assets` | array<string> |  | 最多 30 项 |
| `options` | object |  |  |
| `options.workflow` | string |  | 可选值：`auto` `explainer` `short_drama` `creative_video` `motion_explainer` `profile_card` `product_pitch`; 默认 `explainer` |
| `options.goal` | string |  | 长度 ≤ 2000 |
| `options.audience` | string |  | 长度 ≤ 1000 |
| `options.duration_max` | integer |  | 默认 `60`; 范围 5–180 |
| `options.width` | integer |  | 默认 `1920`; 范围 640–3840 |
| `options.height` | integer |  | 默认 `1080`; 范围 360–2160 |
| `options.fps` | integer |  | 默认 `30`; 范围 24–60 |
| `options.subtitles` | boolean |  | 默认 `false` |
| `options.music` | boolean |  | 默认 `true` |
| `options.skill_id` | string |  | 长度 ≤ 200; 可为 null |
| `options.credit_budget` | integer |  | 范围 1–1000000; 可为 null |
| `options.video_type` | string |  | 可选值：`project` `product` `personal` `corporate`; 可为 null |
| `options.content_data` | map<string, string> |  |  |
| `options.style_preset` | string |  | 可选值：`cinematic_realism` `clean_3d` `product_studio`; 默认 `cinematic_realism` |
| `options.brand` | object |  |  |
| `options.motion_style` | string |  | 可选值：`mono` `photo`; 默认 `mono` |
| `options.photo_subject` | string |  | 长度 ≤ 120 |
| `options.photo_license` | string |  | 可选值：`strict` `sharealike`; 默认 `strict` |
| `webhook_url` | string |  | 长度 ≤ 2000; 可为 null |
| `plan_id` | string |  | 可为 null |
| `template_id` | string |  | 可为 null |
| `brand_id` | string |  | 可为 null |
| `variables` | map<string, string> |  |  |

**返回 202**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 是 |  |
| `project_id` | string | 是 | 可为 null |
| `batch_id` | string |  | 可为 null |
| `parent_id` | string |  | 可为 null |
| `status` | string | 是 | 可选值：`queued` `running` `needs_input` `complete` `rejected` `failed` `cancelled` |
| `stage` | string | 是 | 可为 null |
| `progress` | integer | 是 | 可为 null |
| `error` | string |  | 可为 null |
| `created_at` | number | 是 | 可为 null |
| `updated_at` | number |  | 可为 null |
| `started_at` | number |  | 可为 null |
| `finished_at` | number |  | 可为 null |
| `deleted_at` | number |  | 可为 null |
| `recovery` | object | 是 |  |
| `recovery.attempt` | integer | 是 |  |
| `recovery.max_attempts` | integer | 是 |  |
| `recovery.retry_at` | number |  | 可为 null |
| `result` | object |  | 可为 null |
| `result.files` | map<string, string> |  | Signed download links; present on GET once complete/rejected; 可为 null |
| `result.duration` | number |  | 可为 null |
| `result.shot_count` | integer |  | 可为 null |
| `result.visual_mix` | any |  |  |
| `result.qa` | any |  |  |
| `result.brief` | any |  |  |
| `result.workflow` | string |  | 可为 null |
| `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}`; 可为 null |
| `result.native_project` | any |  |  |
| `requested_workflow` | 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; 可为 null |

```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

需要 API Key。 成功返回: 202.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `job_id` (path) | string | 是 |  |
| `Idempotency-Key` (header) | string |  | 调用方生成并保存的唯一值；超时重试时复用它，同一请求不会被执行两次; 长度 1–128; 可为 null |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**请求体** (application/json)

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `message` | string |  | 长度 ≤ 4000 |
| `questionnaire_id` | string |  | 长度 ≤ 200; 可为 null |
| `answers` | array<object> |  | 最多 30 项 |
| `assets` | array<string> |  | 最多 9 项 |
| `approve_budget` | boolean |  | Approve the pending budget stop; the server computes the new limit; 默认 `false` |
| `credit_budget` | integer |  | Legacy: explicit new Vikoo credit budget for a credit budget stop; 范围 1–1000000; 可为 null |
| `budget_usd` | number |  | Legacy: explicit new total USD limit for a budget stop; 范围 0–100000; 可为 null |

**返回 202**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 是 |  |
| `project_id` | string | 是 | 可为 null |
| `batch_id` | string |  | 可为 null |
| `parent_id` | string |  | 可为 null |
| `status` | string | 是 | 可选值：`queued` `running` `needs_input` `complete` `rejected` `failed` `cancelled` |
| `stage` | string | 是 | 可为 null |
| `progress` | integer | 是 | 可为 null |
| `error` | string |  | 可为 null |
| `created_at` | number | 是 | 可为 null |
| `updated_at` | number |  | 可为 null |
| `started_at` | number |  | 可为 null |
| `finished_at` | number |  | 可为 null |
| `deleted_at` | number |  | 可为 null |
| `recovery` | object | 是 |  |
| `recovery.attempt` | integer | 是 |  |
| `recovery.max_attempts` | integer | 是 |  |
| `recovery.retry_at` | number |  | 可为 null |
| `result` | object |  | 可为 null |
| `result.files` | map<string, string> |  | Signed download links; present on GET once complete/rejected; 可为 null |
| `result.duration` | number |  | 可为 null |
| `result.shot_count` | integer |  | 可为 null |
| `result.visual_mix` | any |  |  |
| `result.qa` | any |  |  |
| `result.brief` | any |  |  |
| `result.workflow` | string |  | 可为 null |
| `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}`; 可为 null |
| `result.native_project` | any |  |  |
| `requested_workflow` | string | 是 |  |

```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

需要 API Key。 成功返回: 202.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `job_id` (path) | string | 是 |  |
| `Idempotency-Key` (header) | string |  | 调用方生成并保存的唯一值；超时重试时复用它，同一请求不会被执行两次; 长度 1–128; 可为 null |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**请求体** (application/json)

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `prompt` | string |  | 长度 10–4000; 可为 null |
| `assets` | array<string> |  | 最多 30 项; 可为 null |
| `options` | object |  |  |
| `options.workflow` | string |  | 可选值：`auto` `explainer` `short_drama` `creative_video` `motion_explainer` `profile_card` `product_pitch`; 默认 `explainer` |
| `options.goal` | string |  | 长度 ≤ 2000 |
| `options.audience` | string |  | 长度 ≤ 1000 |
| `options.duration_max` | integer |  | 默认 `60`; 范围 5–180 |
| `options.width` | integer |  | 默认 `1920`; 范围 640–3840 |
| `options.height` | integer |  | 默认 `1080`; 范围 360–2160 |
| `options.fps` | integer |  | 默认 `30`; 范围 24–60 |
| `options.subtitles` | boolean |  | 默认 `false` |
| `options.music` | boolean |  | 默认 `true` |
| `options.skill_id` | string |  | 长度 ≤ 200; 可为 null |
| `options.credit_budget` | integer |  | 范围 1–1000000; 可为 null |
| `options.video_type` | string |  | 可选值：`project` `product` `personal` `corporate`; 可为 null |
| `options.content_data` | map<string, string> |  |  |
| `options.style_preset` | string |  | 可选值：`cinematic_realism` `clean_3d` `product_studio`; 默认 `cinematic_realism` |
| `options.brand` | object |  |  |
| `options.motion_style` | string |  | 可选值：`mono` `photo`; 默认 `mono` |
| `options.photo_subject` | string |  | 长度 ≤ 120 |
| `options.photo_license` | string |  | 可选值：`strict` `sharealike`; 默认 `strict` |

**返回 202**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 是 |  |
| `project_id` | string | 是 | 可为 null |
| `batch_id` | string |  | 可为 null |
| `parent_id` | string |  | 可为 null |
| `status` | string | 是 | 可选值：`queued` `running` `needs_input` `complete` `rejected` `failed` `cancelled` |
| `stage` | string | 是 | 可为 null |
| `progress` | integer | 是 | 可为 null |
| `error` | string |  | 可为 null |
| `created_at` | number | 是 | 可为 null |
| `updated_at` | number |  | 可为 null |
| `started_at` | number |  | 可为 null |
| `finished_at` | number |  | 可为 null |
| `deleted_at` | number |  | 可为 null |
| `recovery` | object | 是 |  |
| `recovery.attempt` | integer | 是 |  |
| `recovery.max_attempts` | integer | 是 |  |
| `recovery.retry_at` | number |  | 可为 null |
| `result` | object |  | 可为 null |
| `result.files` | map<string, string> |  | Signed download links; present on GET once complete/rejected; 可为 null |
| `result.duration` | number |  | 可为 null |
| `result.shot_count` | integer |  | 可为 null |
| `result.visual_mix` | any |  |  |
| `result.qa` | any |  |  |
| `result.brief` | any |  |  |
| `result.workflow` | string |  | 可为 null |
| `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}`; 可为 null |
| `result.native_project` | any |  |  |
| `requested_workflow` | 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; 可为 null |

```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

需要 API Key。 成功返回: 200.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `job_id` (path) | string | 是 |  |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**返回 200**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 是 |  |
| `project_id` | string | 是 | 可为 null |
| `batch_id` | string |  | 可为 null |
| `parent_id` | string |  | 可为 null |
| `status` | string | 是 | 可选值：`queued` `running` `needs_input` `complete` `rejected` `failed` `cancelled` |
| `stage` | string | 是 | 可为 null |
| `progress` | integer | 是 | 可为 null |
| `error` | string |  | 可为 null |
| `created_at` | number | 是 | 可为 null |
| `updated_at` | number |  | 可为 null |
| `started_at` | number |  | 可为 null |
| `finished_at` | number |  | 可为 null |
| `deleted_at` | number |  | 可为 null |
| `recovery` | object | 是 |  |
| `recovery.attempt` | integer | 是 |  |
| `recovery.max_attempts` | integer | 是 |  |
| `recovery.retry_at` | number |  | 可为 null |
| `result` | object |  | 可为 null |
| `result.files` | map<string, string> |  | Signed download links; present on GET once complete/rejected; 可为 null |
| `result.duration` | number |  | 可为 null |
| `result.shot_count` | integer |  | 可为 null |
| `result.visual_mix` | any |  |  |
| `result.qa` | any |  |  |
| `result.brief` | any |  |  |
| `result.workflow` | string |  | 可为 null |
| `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}`; 可为 null |
| `result.native_project` | any |  |  |
| `requested_workflow` | string | 是 |  |

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

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

需要 API Key。 成功返回: 200.

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

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `job_id` (path) | string | 是 |  |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**返回 200**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 是 |  |
| `deleted` | boolean |  | 默认 `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

需要 API Key。 成功返回: 200.

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

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `job_id` (path) | string | 是 |  |
| `Idempotency-Key` (header) | string |  | 调用方生成并保存的唯一值；超时重试时复用它，同一请求不会被执行两次; 长度 1–128; 可为 null |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**返回 200**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 是 |  |
| `status` | string | 是 | 可选值：`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

签名链接，无需 Key。 成功返回: 200.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `job_id` (path) | string | 是 |  |
| `name` (path) | string | 是 |  |
| `expires` (query) | integer | 是 |  |
| `sig` (query) | string | 是 |  |

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

## 批量

一次提交多条视频。

### GET /v1/batches — List Batches

需要 API Key。 成功返回: 200.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `limit` (query) | integer |  | 默认 `50`; 范围 1–200 |
| `cursor` (query) | string |  | 长度 ≤ 256; 可为 null |
| `after` (query) | string |  | 长度 ≤ 256; 可为 null |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**返回 200**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `data` | array<object> | 是 |  |
| `data[].id` | string | 是 |  |
| `data[].name` | string | 是 |  |
| `data[].created_at` | number | 是 |  |
| `next_cursor` | string |  | Opaque; pass as `cursor` (or the `after` alias) for the next page; 可为 null |
| `has_more` | boolean |  | 默认 `false` |

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

### POST /v1/batches — Create Batch

需要 API Key。 成功返回: 202.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `Idempotency-Key` (header) | string |  | 调用方生成并保存的唯一值；超时重试时复用它，同一请求不会被执行两次; 长度 1–128; 可为 null |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**请求体** (application/json)

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `name` | string |  | 默认 `Batch`; 长度 1–160 |
| `items` | array<object> | 是 | 最多 50 项 |
| `items[].prompt` | string |  | 长度 ≤ 4000 |
| `items[].assets` | array<string> |  | 最多 30 项 |
| `items[].options` | object |  |  |
| `items[].options.workflow` | string |  | 可选值：`auto` `explainer` `short_drama` `creative_video` `motion_explainer` `profile_card` `product_pitch`; 默认 `explainer` |
| `items[].options.goal` | string |  | 长度 ≤ 2000 |
| `items[].options.audience` | string |  | 长度 ≤ 1000 |
| `items[].options.duration_max` | integer |  | 默认 `60`; 范围 5–180 |
| `items[].options.width` | integer |  | 默认 `1920`; 范围 640–3840 |
| `items[].options.height` | integer |  | 默认 `1080`; 范围 360–2160 |
| `items[].options.fps` | integer |  | 默认 `30`; 范围 24–60 |
| `items[].options.subtitles` | boolean |  | 默认 `false` |
| `items[].options.music` | boolean |  | 默认 `true` |
| `items[].options.skill_id` | string |  | 长度 ≤ 200; 可为 null |
| `items[].options.credit_budget` | integer |  | 范围 1–1000000; 可为 null |
| `items[].options.video_type` | string |  | 可选值：`project` `product` `personal` `corporate`; 可为 null |
| `items[].options.content_data` | map<string, string> |  |  |
| `items[].options.style_preset` | string |  | 可选值：`cinematic_realism` `clean_3d` `product_studio`; 默认 `cinematic_realism` |
| `items[].options.brand` | object |  |  |
| `items[].options.motion_style` | string |  | 可选值：`mono` `photo`; 默认 `mono` |
| `items[].options.photo_subject` | string |  | 长度 ≤ 120 |
| `items[].options.photo_license` | string |  | 可选值：`strict` `sharealike`; 默认 `strict` |
| `items[].webhook_url` | string |  | 长度 ≤ 2000; 可为 null |
| `items[].plan_id` | string |  | 可为 null |
| `items[].template_id` | string |  | 可为 null |
| `items[].brand_id` | string |  | 可为 null |
| `items[].variables` | map<string, string> |  |  |

**返回 202**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 是 |  |
| `name` | string | 是 |  |
| `jobs` | array<object> | 是 |  |
| `jobs[].id` | string | 是 |  |
| `jobs[].project_id` | string | 是 | 可为 null |
| `jobs[].batch_id` | string |  | 可为 null |
| `jobs[].parent_id` | string |  | 可为 null |
| `jobs[].status` | string | 是 | 可选值：`queued` `running` `needs_input` `complete` `rejected` `failed` `cancelled` |
| `jobs[].stage` | string | 是 | 可为 null |
| `jobs[].progress` | integer | 是 | 可为 null |
| `jobs[].error` | string |  | 可为 null |
| `jobs[].created_at` | number | 是 | 可为 null |
| `jobs[].updated_at` | number |  | 可为 null |
| `jobs[].started_at` | number |  | 可为 null |
| `jobs[].finished_at` | number |  | 可为 null |
| `jobs[].deleted_at` | number |  | 可为 null |
| `jobs[].recovery` | object | 是 |  |
| `jobs[].recovery.attempt` | integer | 是 |  |
| `jobs[].recovery.max_attempts` | integer | 是 |  |
| `jobs[].recovery.retry_at` | number |  | 可为 null |
| `jobs[].result` | object |  | 可为 null |
| `jobs[].result.files` | map<string, string> |  | Signed download links; present on GET once complete/rejected; 可为 null |
| `jobs[].result.duration` | number |  | 可为 null |
| `jobs[].result.shot_count` | integer |  | 可为 null |
| `jobs[].result.visual_mix` | any |  |  |
| `jobs[].result.qa` | any |  |  |
| `jobs[].result.brief` | any |  |  |
| `jobs[].result.workflow` | string |  | 可为 null |
| `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}`; 可为 null |
| `jobs[].result.native_project` | any |  |  |
| `jobs[].requested_workflow` | string | 是 |  |
| `data` | array<object> | 是 | Alias of `jobs`, kept for v0.3 clients |
| `data[].id` | string | 是 |  |
| `data[].project_id` | string | 是 | 可为 null |
| `data[].batch_id` | string |  | 可为 null |
| `data[].parent_id` | string |  | 可为 null |
| `data[].status` | string | 是 | 可选值：`queued` `running` `needs_input` `complete` `rejected` `failed` `cancelled` |
| `data[].stage` | string | 是 | 可为 null |
| `data[].progress` | integer | 是 | 可为 null |
| `data[].error` | string |  | 可为 null |
| `data[].created_at` | number | 是 | 可为 null |
| `data[].updated_at` | number |  | 可为 null |
| `data[].started_at` | number |  | 可为 null |
| `data[].finished_at` | number |  | 可为 null |
| `data[].deleted_at` | number |  | 可为 null |
| `data[].recovery` | object | 是 |  |
| `data[].recovery.attempt` | integer | 是 |  |
| `data[].recovery.max_attempts` | integer | 是 |  |
| `data[].recovery.retry_at` | number |  | 可为 null |
| `data[].result` | object |  | 可为 null |
| `data[].result.files` | map<string, string> |  | Signed download links; present on GET once complete/rejected; 可为 null |
| `data[].result.duration` | number |  | 可为 null |
| `data[].result.shot_count` | integer |  | 可为 null |
| `data[].result.visual_mix` | any |  |  |
| `data[].result.qa` | any |  |  |
| `data[].result.brief` | any |  |  |
| `data[].result.workflow` | string |  | 可为 null |
| `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}`; 可为 null |
| `data[].result.native_project` | any |  |  |
| `data[].requested_workflow` | string | 是 |  |
| `counts` | 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; 可为 null |

```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

需要 API Key。 成功返回: 200.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `batch_id` (path) | string | 是 |  |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**返回 200**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 是 |  |
| `name` | string | 是 |  |
| `jobs` | array<object> | 是 |  |
| `jobs[].id` | string | 是 |  |
| `jobs[].project_id` | string | 是 | 可为 null |
| `jobs[].batch_id` | string |  | 可为 null |
| `jobs[].parent_id` | string |  | 可为 null |
| `jobs[].status` | string | 是 | 可选值：`queued` `running` `needs_input` `complete` `rejected` `failed` `cancelled` |
| `jobs[].stage` | string | 是 | 可为 null |
| `jobs[].progress` | integer | 是 | 可为 null |
| `jobs[].error` | string |  | 可为 null |
| `jobs[].created_at` | number | 是 | 可为 null |
| `jobs[].updated_at` | number |  | 可为 null |
| `jobs[].started_at` | number |  | 可为 null |
| `jobs[].finished_at` | number |  | 可为 null |
| `jobs[].deleted_at` | number |  | 可为 null |
| `jobs[].recovery` | object | 是 |  |
| `jobs[].recovery.attempt` | integer | 是 |  |
| `jobs[].recovery.max_attempts` | integer | 是 |  |
| `jobs[].recovery.retry_at` | number |  | 可为 null |
| `jobs[].result` | object |  | 可为 null |
| `jobs[].result.files` | map<string, string> |  | Signed download links; present on GET once complete/rejected; 可为 null |
| `jobs[].result.duration` | number |  | 可为 null |
| `jobs[].result.shot_count` | integer |  | 可为 null |
| `jobs[].result.visual_mix` | any |  |  |
| `jobs[].result.qa` | any |  |  |
| `jobs[].result.brief` | any |  |  |
| `jobs[].result.workflow` | string |  | 可为 null |
| `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}`; 可为 null |
| `jobs[].result.native_project` | any |  |  |
| `jobs[].requested_workflow` | string | 是 |  |
| `data` | array<object> | 是 | Alias of `jobs`, kept for v0.3 clients |
| `data[].id` | string | 是 |  |
| `data[].project_id` | string | 是 | 可为 null |
| `data[].batch_id` | string |  | 可为 null |
| `data[].parent_id` | string |  | 可为 null |
| `data[].status` | string | 是 | 可选值：`queued` `running` `needs_input` `complete` `rejected` `failed` `cancelled` |
| `data[].stage` | string | 是 | 可为 null |
| `data[].progress` | integer | 是 | 可为 null |
| `data[].error` | string |  | 可为 null |
| `data[].created_at` | number | 是 | 可为 null |
| `data[].updated_at` | number |  | 可为 null |
| `data[].started_at` | number |  | 可为 null |
| `data[].finished_at` | number |  | 可为 null |
| `data[].deleted_at` | number |  | 可为 null |
| `data[].recovery` | object | 是 |  |
| `data[].recovery.attempt` | integer | 是 |  |
| `data[].recovery.max_attempts` | integer | 是 |  |
| `data[].recovery.retry_at` | number |  | 可为 null |
| `data[].result` | object |  | 可为 null |
| `data[].result.files` | map<string, string> |  | Signed download links; present on GET once complete/rejected; 可为 null |
| `data[].result.duration` | number |  | 可为 null |
| `data[].result.shot_count` | integer |  | 可为 null |
| `data[].result.visual_mix` | any |  |  |
| `data[].result.qa` | any |  |  |
| `data[].result.brief` | any |  |  |
| `data[].result.workflow` | string |  | 可为 null |
| `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}`; 可为 null |
| `data[].result.native_project` | any |  |  |
| `data[].requested_workflow` | string | 是 |  |
| `counts` | map<string, integer> | 是 |  |

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

## 事件与 Webhook

不想轮询时，用带签名的 Webhook 或事件列表接收状态变化。

### GET /v1/events — List Events

需要 API Key。 成功返回: 200.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `after` (query) | integer |  | 默认 `0`; 范围 ≥ 0 |
| `limit` (query) | integer |  | 默认 `50`; 范围 1–200 |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**返回 200**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `data` | array<object> | 是 |  |
| `data[].id` | string | 是 |  |
| `data[].sequence` | integer | 是 |  |
| `data[].type` | string | 是 |  |
| `data[].created_at` | number | 是 |  |
| `data[].api_version` | string | 是 |  |
| `data[].project_id` | string | 是 | 可为 null |
| `data[].data` | object | 是 |  |
| `next_cursor` | integer | 是 | Sequence number to pass as `after`; unchanged when the page is empty |
| `has_more` | boolean |  | 默认 `false` |

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

### GET /v1/webhooks — List Webhooks

需要 API Key。 成功返回: 200.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `limit` (query) | integer |  | 默认 `50`; 范围 1–200 |
| `cursor` (query) | string |  | 长度 ≤ 256; 可为 null |
| `after` (query) | string |  | 长度 ≤ 256; 可为 null |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**返回 200**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `data` | array<object> | 是 |  |
| `data[].id` | string | 是 |  |
| `data[].project_id` | string | 是 | 可为 null |
| `data[].kind` | string | 是 |  |
| `data[].name` | string | 是 |  |
| `data[].version` | integer | 是 |  |
| `data[].created_at` | number | 是 |  |
| `data[].updated_at` | number | 是 |  |
| `data[].data` | object | 是 |  |
| `data[].data.name` | string | 是 |  |
| `data[].data.url` | string | 是 |  |
| `data[].data.active` | boolean |  | 默认 `true` |
| `data[].data.has_secret` | boolean | 是 |  |
| `next_cursor` | string |  | Opaque; pass as `cursor` (or the `after` alias) for the next page; 可为 null |
| `has_more` | boolean |  | 默认 `false` |

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

### POST /v1/webhooks — Create Webhook

需要 API Key。 成功返回: 201.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `Idempotency-Key` (header) | string |  | 调用方生成并保存的唯一值；超时重试时复用它，同一请求不会被执行两次; 长度 1–128; 可为 null |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**请求体** (application/json)

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `name` | string |  | 默认 `Webhook`; 长度 ≤ 160 |
| `url` | string | 是 | 长度 ≤ 2000 |
| `active` | boolean |  | 默认 `true` |

**返回 201**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 是 |  |
| `project_id` | string | 是 | 可为 null |
| `kind` | string | 是 |  |
| `name` | string | 是 |  |
| `version` | integer | 是 |  |
| `created_at` | number | 是 |  |
| `updated_at` | number | 是 |  |
| `data` | object | 是 |  |
| `data.name` | string | 是 |  |
| `data.url` | string | 是 |  |
| `data.active` | boolean |  | 默认 `true` |
| `data.has_secret` | boolean | 是 |  |
| `signing_secret` | string | 是 | Shown at creation/rotation and for the same actor's idempotent retry within 24 hours; 可为 null |

```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

需要 API Key。 成功返回: 200.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `webhook_id` (path) | string | 是 |  |
| `expected_version` (query) | integer | 是 | 范围 ≥ 1 |
| `Idempotency-Key` (header) | string |  | 调用方生成并保存的唯一值；超时重试时复用它，同一请求不会被执行两次; 长度 1–128; 可为 null |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**返回 200**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 是 |  |
| `project_id` | string | 是 | 可为 null |
| `kind` | string | 是 |  |
| `name` | string | 是 |  |
| `version` | integer | 是 |  |
| `created_at` | number | 是 |  |
| `updated_at` | number | 是 |  |
| `data` | object | 是 |  |
| `data.name` | string | 是 |  |
| `data.url` | string | 是 |  |
| `data.active` | boolean |  | 默认 `true` |
| `data.has_secret` | boolean | 是 |  |
| `signing_secret` | string | 是 | Shown at creation/rotation and for the same actor's idempotent retry within 24 hours; 可为 null |

```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

需要 API Key。 成功返回: 200.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `webhook_id` (path) | string | 是 |  |
| `expected_version` (query) | integer | 是 | 范围 ≥ 1 |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**请求体** (application/json)

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `name` | string |  | 默认 `Webhook`; 长度 ≤ 160 |
| `url` | string | 是 | 长度 ≤ 2000 |
| `active` | boolean |  | 默认 `true` |

**返回 200**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 是 |  |
| `project_id` | string | 是 | 可为 null |
| `kind` | string | 是 |  |
| `name` | string | 是 |  |
| `version` | integer | 是 |  |
| `created_at` | number | 是 |  |
| `updated_at` | number | 是 |  |
| `data` | object | 是 |  |
| `data.name` | string | 是 |  |
| `data.url` | string | 是 |  |
| `data.active` | boolean |  | 默认 `true` |
| `data.has_secret` | boolean | 是 |  |

```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

需要 API Key。 成功返回: 200.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `webhook_id` (path) | string | 是 |  |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**返回 200**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 是 |  |
| `deleted` | boolean |  | 默认 `true` |

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

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

需要 API Key。 成功返回: 200.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `limit` (query) | integer |  | 默认 `50`; 范围 1–200 |
| `cursor` (query) | string |  | 长度 ≤ 256; 可为 null |
| `after` (query) | string |  | 长度 ≤ 256; 可为 null |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**返回 200**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `data` | array<object> | 是 |  |
| `data[].id` | string | 是 |  |
| `data[].event_id` | string | 是 |  |
| `data[].url` | string | 是 |  |
| `data[].status` | string | 是 |  |
| `data[].attempts` | integer | 是 |  |
| `data[].last_error` | string | 是 | 可为 null |
| `data[].delivered_at` | number | 是 | 可为 null |
| `next_cursor` | string |  | Opaque; pass as `cursor` (or the `after` alias) for the next page; 可为 null |
| `has_more` | boolean |  | 默认 `false` |

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

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

需要 API Key。 成功返回: 202.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `delivery_id` (path) | string | 是 |  |
| `webhook_id` (query) | string |  | 长度 ≤ 32; 可为 null |
| `Idempotency-Key` (header) | string |  | 调用方生成并保存的唯一值；超时重试时复用它，同一请求不会被执行两次; 长度 1–128; 可为 null |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**返回 202**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 是 |  |
| `status` | string | 是 | 可选值：`pending` |

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

## 品牌与模板

保存品牌素材和常用模板，制作时直接引用。

### GET /v1/brands — Listing

需要 API Key。 成功返回: 200.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `limit` (query) | integer |  | 默认 `50`; 范围 1–200 |
| `cursor` (query) | string |  | 长度 ≤ 256; 可为 null |
| `after` (query) | string |  | 长度 ≤ 256; 可为 null |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**返回 200**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `data` | array<object> | 是 |  |
| `data[].id` | string | 是 |  |
| `data[].project_id` | string | 是 | 可为 null |
| `data[].kind` | string | 是 |  |
| `data[].name` | string | 是 |  |
| `data[].version` | integer | 是 |  |
| `data[].created_at` | number | 是 |  |
| `data[].updated_at` | number | 是 |  |
| `data[].data` | object | 是 |  |
| `next_cursor` | string |  | Opaque; pass as `cursor` (or the `after` alias) for the next page; 可为 null |
| `has_more` | boolean |  | 默认 `false` |

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

### POST /v1/brands — Create

需要 API Key。 成功返回: 201.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `Idempotency-Key` (header) | string |  | 调用方生成并保存的唯一值；超时重试时复用它，同一请求不会被执行两次; 长度 1–128; 可为 null |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**请求体** (application/json)

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `name` | string | 是 | 长度 1–120 |
| `slogan` | string |  | 长度 ≤ 500 |
| `primary_color` | string |  | 默认 `#0F4C81` |
| `theme` | string |  | 可选值：`light` `dark`; 默认 `dark` |
| `assets` | array<string> |  | 最多 30 项 |
| `notes` | string |  | 长度 ≤ 2000 |

**返回 201**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 是 |  |
| `project_id` | string | 是 | 可为 null |
| `kind` | string | 是 |  |
| `name` | string | 是 |  |
| `version` | integer | 是 |  |
| `created_at` | number | 是 |  |
| `updated_at` | number | 是 |  |
| `data` | object | 是 |  |

```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

需要 API Key。 成功返回: 200.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `resource_id` (path) | string | 是 |  |
| `version` (query) | integer |  | 范围 ≥ 1; 可为 null |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**返回 200**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 是 |  |
| `project_id` | string | 是 | 可为 null |
| `kind` | string | 是 |  |
| `name` | string | 是 |  |
| `version` | integer | 是 |  |
| `created_at` | number | 是 |  |
| `updated_at` | number | 是 |  |
| `data` | object | 是 |  |

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

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

需要 API Key。 成功返回: 200.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `resource_id` (path) | string | 是 |  |
| `expected_version` (query) | integer | 是 | 范围 ≥ 1 |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**请求体** (application/json)

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `name` | string | 是 | 长度 1–120 |
| `slogan` | string |  | 长度 ≤ 500 |
| `primary_color` | string |  | 默认 `#0F4C81` |
| `theme` | string |  | 可选值：`light` `dark`; 默认 `dark` |
| `assets` | array<string> |  | 最多 30 项 |
| `notes` | string |  | 长度 ≤ 2000 |

**返回 200**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 是 |  |
| `project_id` | string | 是 | 可为 null |
| `kind` | string | 是 |  |
| `name` | string | 是 |  |
| `version` | integer | 是 |  |
| `created_at` | number | 是 |  |
| `updated_at` | number | 是 |  |
| `data` | object | 是 |  |

```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

需要 API Key。 成功返回: 200.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `resource_id` (path) | string | 是 |  |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**返回 200**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 是 |  |
| `deleted` | boolean |  | 默认 `true` |

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

### GET /v1/templates — Listing

需要 API Key。 成功返回: 200.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `limit` (query) | integer |  | 默认 `50`; 范围 1–200 |
| `cursor` (query) | string |  | 长度 ≤ 256; 可为 null |
| `after` (query) | string |  | 长度 ≤ 256; 可为 null |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**返回 200**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `data` | array<object> | 是 |  |
| `data[].id` | string | 是 |  |
| `data[].project_id` | string | 是 | 可为 null |
| `data[].kind` | string | 是 |  |
| `data[].name` | string | 是 |  |
| `data[].version` | integer | 是 |  |
| `data[].created_at` | number | 是 |  |
| `data[].updated_at` | number | 是 |  |
| `data[].data` | object | 是 |  |
| `next_cursor` | string |  | Opaque; pass as `cursor` (or the `after` alias) for the next page; 可为 null |
| `has_more` | boolean |  | 默认 `false` |

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

### POST /v1/templates — Create

需要 API Key。 成功返回: 201.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `Idempotency-Key` (header) | string |  | 调用方生成并保存的唯一值；超时重试时复用它，同一请求不会被执行两次; 长度 1–128; 可为 null |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**请求体** (application/json)

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `name` | string | 是 | 长度 1–160 |
| `prompt` | string | 是 | Use $variable or ${variable} placeholders; 长度 10–4000 |
| `options` | object |  |  |
| `options.workflow` | string |  | 可选值：`auto` `explainer` `short_drama` `creative_video` `motion_explainer` `profile_card` `product_pitch`; 默认 `explainer` |
| `options.goal` | string |  | 长度 ≤ 2000 |
| `options.audience` | string |  | 长度 ≤ 1000 |
| `options.duration_max` | integer |  | 默认 `60`; 范围 5–180 |
| `options.width` | integer |  | 默认 `1920`; 范围 640–3840 |
| `options.height` | integer |  | 默认 `1080`; 范围 360–2160 |
| `options.fps` | integer |  | 默认 `30`; 范围 24–60 |
| `options.subtitles` | boolean |  | 默认 `false` |
| `options.music` | boolean |  | 默认 `true` |
| `options.skill_id` | string |  | 长度 ≤ 200; 可为 null |
| `options.credit_budget` | integer |  | 范围 1–1000000; 可为 null |
| `options.video_type` | string |  | 可选值：`project` `product` `personal` `corporate`; 可为 null |
| `options.content_data` | map<string, string> |  |  |
| `options.style_preset` | string |  | 可选值：`cinematic_realism` `clean_3d` `product_studio`; 默认 `cinematic_realism` |
| `options.brand` | object |  |  |
| `options.motion_style` | string |  | 可选值：`mono` `photo`; 默认 `mono` |
| `options.photo_subject` | string |  | 长度 ≤ 120 |
| `options.photo_license` | string |  | 可选值：`strict` `sharealike`; 默认 `strict` |
| `assets` | array<string> |  | 最多 30 项 |
| `brand_id` | string |  | 可为 null |

**返回 201**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 是 |  |
| `project_id` | string | 是 | 可为 null |
| `kind` | string | 是 |  |
| `name` | string | 是 |  |
| `version` | integer | 是 |  |
| `created_at` | number | 是 |  |
| `updated_at` | number | 是 |  |
| `data` | object | 是 |  |

```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

需要 API Key。 成功返回: 200.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `resource_id` (path) | string | 是 |  |
| `version` (query) | integer |  | 范围 ≥ 1; 可为 null |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**返回 200**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 是 |  |
| `project_id` | string | 是 | 可为 null |
| `kind` | string | 是 |  |
| `name` | string | 是 |  |
| `version` | integer | 是 |  |
| `created_at` | number | 是 |  |
| `updated_at` | number | 是 |  |
| `data` | object | 是 |  |

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

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

需要 API Key。 成功返回: 200.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `resource_id` (path) | string | 是 |  |
| `expected_version` (query) | integer | 是 | 范围 ≥ 1 |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**请求体** (application/json)

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `name` | string | 是 | 长度 1–160 |
| `prompt` | string | 是 | Use $variable or ${variable} placeholders; 长度 10–4000 |
| `options` | object |  |  |
| `options.workflow` | string |  | 可选值：`auto` `explainer` `short_drama` `creative_video` `motion_explainer` `profile_card` `product_pitch`; 默认 `explainer` |
| `options.goal` | string |  | 长度 ≤ 2000 |
| `options.audience` | string |  | 长度 ≤ 1000 |
| `options.duration_max` | integer |  | 默认 `60`; 范围 5–180 |
| `options.width` | integer |  | 默认 `1920`; 范围 640–3840 |
| `options.height` | integer |  | 默认 `1080`; 范围 360–2160 |
| `options.fps` | integer |  | 默认 `30`; 范围 24–60 |
| `options.subtitles` | boolean |  | 默认 `false` |
| `options.music` | boolean |  | 默认 `true` |
| `options.skill_id` | string |  | 长度 ≤ 200; 可为 null |
| `options.credit_budget` | integer |  | 范围 1–1000000; 可为 null |
| `options.video_type` | string |  | 可选值：`project` `product` `personal` `corporate`; 可为 null |
| `options.content_data` | map<string, string> |  |  |
| `options.style_preset` | string |  | 可选值：`cinematic_realism` `clean_3d` `product_studio`; 默认 `cinematic_realism` |
| `options.brand` | object |  |  |
| `options.motion_style` | string |  | 可选值：`mono` `photo`; 默认 `mono` |
| `options.photo_subject` | string |  | 长度 ≤ 120 |
| `options.photo_license` | string |  | 可选值：`strict` `sharealike`; 默认 `strict` |
| `assets` | array<string> |  | 最多 30 项 |
| `brand_id` | string |  | 可为 null |

**返回 200**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 是 |  |
| `project_id` | string | 是 | 可为 null |
| `kind` | string | 是 |  |
| `name` | string | 是 |  |
| `version` | integer | 是 |  |
| `created_at` | number | 是 |  |
| `updated_at` | number | 是 |  |
| `data` | object | 是 |  |

```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

需要 API Key。 成功返回: 200.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `resource_id` (path) | string | 是 |  |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**返回 200**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 是 |  |
| `deleted` | boolean |  | 默认 `true` |

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

## 项目、Key 与审计

管理项目和 API Key，查看变更记录。

### GET /v1/projects — List Projects

需要 API Key。 成功返回: 200.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `limit` (query) | integer |  | 默认 `50`; 范围 1–200 |
| `cursor` (query) | string |  | 长度 ≤ 256; 可为 null |
| `after` (query) | string |  | 长度 ≤ 256; 可为 null |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**返回 200**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `data` | array<object> | 是 |  |
| `data[].id` | string | 是 |  |
| `data[].organization_id` | string | 是 |  |
| `data[].name` | string | 是 |  |
| `data[].created_at` | number | 是 |  |
| `next_cursor` | string |  | Opaque; pass as `cursor` (or the `after` alias) for the next page; 可为 null |
| `has_more` | boolean |  | 默认 `false` |

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

### POST /v1/projects — Create Project

需要 API Key。 成功返回: 201.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `Idempotency-Key` (header) | string |  | 调用方生成并保存的唯一值；超时重试时复用它，同一请求不会被执行两次; 长度 1–128; 可为 null |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**请求体** (application/json)

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `name` | string | 是 | 长度 1–120 |

**返回 201**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 是 |  |
| `organization_id` | string | 是 |  |
| `name` | string | 是 |  |
| `created_at` | number | 是 |  |

```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

需要 API Key。 成功返回: 200.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `project_id` (path) | string | 是 |  |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**返回 200**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 是 |  |
| `deleted` | boolean |  | 默认 `true` |

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

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

需要 API Key。 成功返回: 200.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `limit` (query) | integer |  | 默认 `50`; 范围 1–200 |
| `cursor` (query) | string |  | 长度 ≤ 256; 可为 null |
| `after` (query) | string |  | 长度 ≤ 256; 可为 null |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**返回 200**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `data` | array<object> | 是 |  |
| `data[].id` | string | 是 |  |
| `data[].name` | string | 是 | Label given at creation (also returned as `owner`) |
| `data[].owner` | string | 是 |  |
| `data[].prefix` | string | 是 | 可为 null |
| `data[].organization_id` | string | 是 | 可为 null |
| `data[].project_id` | string |  | Set when the key is bound to one project; 可为 null |
| `data[].role` | string | 是 | 可选值：`owner` `editor` `viewer` |
| `data[].active` | boolean | 是 |  |
| `data[].created_at` | number | 是 | 可为 null |
| `data[].last_used_at` | number |  | 可为 null |
| `data[].expires_at` | number |  | 可为 null |
| `data[].revoked_at` | number |  | 可为 null |
| `next_cursor` | string |  | Opaque; pass as `cursor` (or the `after` alias) for the next page; 可为 null |
| `has_more` | boolean |  | 默认 `false` |

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

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

需要 API Key。 成功返回: 201.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `Idempotency-Key` (header) | string |  | 调用方生成并保存的唯一值；超时重试时复用它，同一请求不会被执行两次; 长度 1–128; 可为 null |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**请求体** (application/json)

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `name` | string | 是 | 长度 1–120 |
| `role` | string |  | 可选值：`owner` `editor` `viewer`; 默认 `editor` |
| `project_id` | string |  | 可为 null |
| `monthly_budget_usd` | number |  | 范围 ≥ 0; 可为 null |
| `rate_per_hour` | integer |  | 范围 ≥ 1; 可为 null |

**返回 201**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 是 |  |
| `name` | string | 是 | Label given at creation (also returned as `owner`) |
| `owner` | string | 是 |  |
| `prefix` | string | 是 | 可为 null |
| `organization_id` | string | 是 | 可为 null |
| `project_id` | string |  | Set when the key is bound to one project; 可为 null |
| `role` | string | 是 | 可选值：`owner` `editor` `viewer` |
| `active` | boolean | 是 |  |
| `created_at` | number | 是 | 可为 null |
| `last_used_at` | number |  | 可为 null |
| `expires_at` | number |  | 可为 null |
| `revoked_at` | number |  | 可为 null |
| `key` | string | 是 | 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

需要 API Key。 成功返回: 200.

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

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `key_id` (path) | string | 是 |  |
| `grace_seconds` (query) | integer |  | 默认 `0`; 范围 0–604800 |
| `Idempotency-Key` (header) | string |  | 调用方生成并保存的唯一值；超时重试时复用它，同一请求不会被执行两次; 长度 1–128; 可为 null |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**返回 200**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 是 |  |
| `key` | string | 是 |  |
| `previous_id` | string | 是 |  |
| `previous_expires_in` | integer | 是 | 可为 null |

```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

需要 API Key。 成功返回: 200.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `key_id` (path) | string | 是 |  |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**返回 200**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 是 |  |
| `active` | boolean |  | 默认 `false` |

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

### GET /v1/audit — Audit Log

需要 API Key。 成功返回: 200.

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

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `after` (query) | integer |  | 默认 `0`; 范围 ≥ 0 |
| `limit` (query) | integer |  | 默认 `50`; 范围 1–200 |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**返回 200**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `data` | array<object> | 是 |  |
| `data[].id` | string | 是 |  |
| `data[].sequence` | integer | 是 |  |
| `data[].type` | string | 是 |  |
| `data[].created_at` | number | 是 |  |
| `data[].api_version` | string | 是 |  |
| `data[].project_id` | string | 是 | 可为 null |
| `data[].data` | object | 是 |  |
| `next_cursor` | integer | 是 | Sequence number to pass as `after`; unchanged when the page is empty |
| `has_more` | boolean |  | 默认 `false` |

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

## 余额与用量

查看余额、流水和用量，在线充值。

### GET /v1/wallet — Wallet

需要 API Key。 成功返回: 200.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**返回 200**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `balance_cents` | integer | 是 |  |
| `held_cents` | integer | 是 |  |
| `available_cents` | integer | 是 |  |
| `low_balance_cents` | integer | 是 | 可为 null |
| `currency` | string | 是 |  |
| `organization_id` | string | 是 |  |

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

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

需要 API Key。 成功返回: 200.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `after` (query) | string |  | 长度 ≤ 64; 可为 null |
| `limit` (query) | integer |  | 默认 `50`; 范围 1–200 |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**返回 200**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `data` | array<object> | 是 |  |
| `data[].id` | string | 是 |  |
| `data[].organization_id` | string | 是 |  |
| `data[].kind` | string | 是 |  |
| `data[].amount_cents` | integer | 是 |  |
| `data[].hold_cents` | integer | 是 |  |
| `data[].job_id` | string | 是 | 可为 null |
| `data[].note` | string | 是 | 可为 null |
| `data[].actor` | string | 是 | 可为 null |
| `data[].created_at` | number | 是 |  |
| `next_cursor` | string |  | Opaque; pass as `cursor` (or the `after` alias) for the next page; 可为 null |
| `has_more` | boolean |  | 默认 `false` |

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

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

需要 API Key。 成功返回: 201.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `Idempotency-Key` (header) | string | 是 | 调用方生成并保存的唯一值；超时重试时复用它，同一请求不会被执行两次; 长度 1–128 |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**请求体** (application/json)

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `amount_cents` | integer | 是 | USD cents, $5–$10,000; 范围 500–1000000 |

**返回 201**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 是 |  |
| `url` | string | 是 |  |
| `amount_cents` | integer | 是 |  |
| `currency` | string |  | 默认 `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

需要 API Key。 成功返回: 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.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `from` (query) | number |  | 范围 ≥ 0; 可为 null |
| `to` (query) | number |  | 范围 ≥ 0; 可为 null |
| `group_by` (query) | string |  | 默认 `none` |
| `limit` (query) | integer |  | 默认 `50`; 范围 1–200 |
| `after` (query) | string |  | 长度 ≤ 32; 可为 null |
| `X-Project-ID` (header) | string |  | 要操作的项目；省略时使用默认项目; 可为 null |

**返回 200**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `project_id` | string | 是 |  |
| `range` | map<string, number> | 是 |  |
| `jobs` | map<string, integer> | 是 |  |
| `list_usd` | number | 是 | Amount billed for the paid calls in the range |
| `group_by` | string | 是 |  |
| `groups` | array<object> | 是 | 可为 null |
| `next_cursor` | string | 是 | 可为 null |

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

## 服务状态

健康检查，不需要 Key。

### GET /healthz — Healthz

无需鉴权。 成功返回: 200.

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

### GET /readyz — Readyz

无需鉴权。 成功返回: 200.

**返回 200**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `ok` | boolean | 是 |  |
| `db` | boolean | 是 |  |
| `version` | string | 是 |  |
| `queue_depth` | integer | 是 |  |
| `running` | integer | 是 |  |
| `worker_seen_at` | number |  | Latest job start or running-job heartbeat; 可为 null |
| `worker_alive` | boolean | 是 | A worker sent a durable heartbeat within the last 5 minutes |

- `503` Service Unavailable

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