首页
开发者
API 参考

参考

API 参考

Azimo REST API 的全部 57 个接口：参数、请求体、返回字段和 curl 示例，由线上接口定义实时生成。接口说明为英文原文。

> 以下是 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"
```

查看 Markdown

基础约定

Base URL: https://azimo.ai
鉴权: 每个 /v1 请求带 Authorization: Bearer <API key>。登录后在个人中心创建 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。

错误

出错时返回 JSON，字段如下；报告问题时请附上 request_id。

名称	类型	说明
`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 的身份，以及可用的工作流和视频类型。

Me

GET/v1/me

需要 API Key成功 200

参数

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

返回 200 application/json

名称	类型	说明
`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>

示例

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

Workflows

GET/v1/workflows

需要 API Key成功 200

参数

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

返回 200 application/json

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

示例

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

Video Skills

GET/v1/workflows/creative_video/skills

需要 API Key成功 200

参数

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

返回 200 application/json

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

示例

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

Video Types

GET/v1/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 application/json

名称	类型	说明
`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`

示例

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

Playground

GET/v1/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 application/json

名称	类型	说明
`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

示例

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

素材

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

List Assets

GET/v1/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 application/json

名称	类型	说明
`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`

示例

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

Upload Asset

POST/v1/assets

需要 API Key成功 201

参数

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

请求体 multipart/form-data

名称	类型	说明
`file`必填	file

返回 201 application/json

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

示例

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成功 200

参数

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

返回 200 application/json

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

示例

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

Delete Asset

DELETE/v1/assets/{asset_id}

需要 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 application/json

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

示例

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成功 200

参数

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

返回 200 application/octet-stream

返回文件内容。

示例

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

方案

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

List Plans

GET/v1/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 application/json

名称	类型	说明
`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`

示例

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

Create Plan

POST/v1/plans

需要 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 application/json

名称	类型	说明
`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

示例

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成功 200

参数

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

返回 200 application/json

名称	类型	说明
`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

示例

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

Preview Route

POST/v1/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 application/json

名称	类型	说明
`plan_id`必填	string
`workflow`	string	可为 null
`requirements`	array<object>

示例

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>"]}'

视频

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

List Videos

GET/v1/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 application/json

名称	类型	说明
`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`

示例

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

Create Video

POST/v1/videos

需要 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 application/json

名称	类型	说明
`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

示例

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成功 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 application/json

名称	类型	说明
`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

示例

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成功 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 application/json

名称	类型	说明
`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

示例

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成功 200

参数

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

返回 200 application/json

名称	类型	说明
`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

示例

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

Delete Video

DELETE/v1/videos/{job_id}

需要 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 application/json

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

示例

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成功 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 application/json

名称	类型	说明
`id`必填	string
`status`必填	string	可选值：`cancelled` `cancelling`

示例

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}

签名链接，无需 Key成功 200

参数

名称	类型	说明
`job_id`必填path	string
`name`必填path	string
`expires`必填query	integer
`sig`必填query	string

返回 200 application/octet-stream

返回文件内容。

示例

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

批量

一次提交多条视频。

List Batches

GET/v1/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 application/json

名称	类型	说明
`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`

示例

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

Create Batch

POST/v1/batches

需要 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 application/json

名称	类型	说明
`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

示例

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成功 200

参数

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

返回 200 application/json

名称	类型	说明
`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>

示例

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

事件与 Webhook

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

List Events

GET/v1/events

需要 API Key成功 200

参数

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

返回 200 application/json

名称	类型	说明
`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`

示例

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

List Webhooks

GET/v1/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 application/json

名称	类型	说明
`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`

示例

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

Create Webhook

POST/v1/webhooks

需要 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 application/json

名称	类型	说明
`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

示例

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成功 200

参数

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

返回 200 application/json

名称	类型	说明
`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

示例

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成功 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 application/json

名称	类型	说明
`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

示例

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成功 200

参数

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

返回 200 application/json

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

示例

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

List Deliveries

GET/v1/webhook-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 application/json

名称	类型	说明
`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`

示例

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

Replay

POST/v1/webhook-deliveries/{delivery_id}/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 application/json

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

示例

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

品牌与模板

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

Listing

GET/v1/brands

需要 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 application/json

名称	类型	说明
`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`

示例

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

Create

POST/v1/brands

需要 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 application/json

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

示例

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成功 200

参数

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

返回 200 application/json

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

示例

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

Revise

PUT/v1/brands/{resource_id}

需要 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 application/json

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

示例

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成功 200

参数

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

返回 200 application/json

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

示例

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

Listing

GET/v1/templates

需要 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 application/json

名称	类型	说明
`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`

示例

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

Create

POST/v1/templates

需要 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 application/json

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

示例

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成功 200

参数

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

返回 200 application/json

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

示例

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

Revise

PUT/v1/templates/{resource_id}

需要 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 application/json

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

示例

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成功 200

参数

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

返回 200 application/json

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

示例

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

项目、Key 与审计

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

List Projects

GET/v1/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 application/json

名称	类型	说明
`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`

示例

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

Create Project

POST/v1/projects

需要 API Key成功 201

参数

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

请求体 application/json

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

返回 201 application/json

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

示例

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成功 200

参数

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

返回 200 application/json

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

示例

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

List Keys

GET/v1/api-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 application/json

名称	类型	说明
`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`

示例

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

Create Key

POST/v1/api-keys

需要 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 application/json

名称	类型	说明
`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)

示例

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成功 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 application/json

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

示例

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成功 200

参数

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

返回 200 application/json

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

示例

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

Audit Log

GET/v1/audit

需要 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 application/json

名称	类型	说明
`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`

示例

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

余额与用量

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

Wallet

GET/v1/wallet

需要 API Key成功 200

参数

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

返回 200 application/json

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

示例

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

Wallet Entries

GET/v1/wallet/entries

需要 API Key成功 200

参数

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

返回 200 application/json

名称	类型	说明
`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`

示例

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

Checkout

POST/v1/wallet/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 application/json

名称	类型	说明
`id`必填	string
`url`必填	string
`amount_cents`必填	integer
`currency`	string	默认 `USD`

示例

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}'

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 application/json

名称	类型	说明
`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

示例

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

服务状态

健康检查，不需要 Key。

Healthz

GET/healthz

无需鉴权成功 200

返回 200 application/json

示例

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

Readyz

GET/readyz

无需鉴权成功 200

返回 200 application/json

名称	类型	说明
`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

示例

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

基础约定#

错误

账户与能力#

参数

返回 200 application/json

示例

参数

返回 200 application/json

示例

参数

返回 200 application/json

示例

参数

返回 200 application/json

示例

参数

返回 200 application/json

示例

素材#

参数

返回 200 application/json

示例

参数

请求体 multipart/form-data

返回 201 application/json

示例

参数

返回 200 application/json

示例

参数

返回 200 application/json

示例

参数

返回 200 application/octet-stream

示例

方案#

参数

返回 200 application/json

示例

参数

请求体 application/json

返回 201 application/json

示例

参数

返回 200 application/json

示例

参数

请求体 application/json

返回 200 application/json

示例

视频#

参数

返回 200 application/json

示例

参数

请求体 application/json

返回 202 application/json

示例

参数

请求体 application/json

返回 202 application/json

示例

参数

请求体 application/json

返回 202 application/json

示例

参数

返回 200 application/json

示例

参数

返回 200 application/json

示例

参数

返回 200 application/json

示例

参数

返回 200 application/octet-stream

示例

批量#

参数

基础约定

账户与能力

素材

方案

视频

批量

事件与 Webhook