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


---

# Azimo 开发者文档（全部）

---

## 快速开始

来源: https://axiomlab.online/developers/quickstart

大约 5 分钟，从拿到 API Key 到提交第一条视频：上传资料、创建方案、确认制作、等待并下载成片。

### 先方案，后制作

方案（plan）是免费的：它检查你的请求并把它冻结下来；只有基于方案开始制作时，才会使用你的账户余额。

所以每次都分两步：先 `POST /v1/plans`，看方案是不是 `ready`；满意了再 `POST /v1/videos` 开始制作。

### 第 1 步：获取 API Key

1. 登录 [https://axiomlab.online/login](https://axiomlab.online/login)。公测期间注册需要邀请码，请发邮件到 sales@azimo.ai 索取。
2. 打开 **开发者 → 概览 → API 密钥**，创建一把密钥。Key 只显示一次，请马上保存。
3. 在终端里设置环境变量，后面的例子都会用到：

```bash
export AZIMO_API_KEY="你的 API Key"
```

每个请求都带上请求头 `Authorization: Bearer $AZIMO_API_KEY`。不要把 Key 写进代码或提交到代码仓库。

### 第 2 步：用 curl 走一遍

**上传资料（可选）。** 支持 PDF、PPTX、TXT、MD、PNG、JPG、JPEG、WEBP、MP4、MOV、WEBM、MP3、WAV、M4A，单个文件最多 60 MB。

```bash
curl -s https://axiomlab.online/v1/assets \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Idempotency-Key: upload-brief-001" \
  -F "file=@brief.pdf"
```

返回里的 `id` 就是素材 ID，例如 `"id": "744c8c43aa494843"`。

**创建方案。** `prompt` 写清楚：片子讲什么、给谁看、看完要做什么。

```bash
curl -s https://axiomlab.online/v1/plans \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: kettle-plan-001" \
  -d '{
    "prompt": "给经常出差住酒店的人做一条 30 秒产品视频：普利瓦折叠旅行水壶，折叠后能放进电脑包，一次烧两杯水，结尾引导到官方商店搜索。",
    "assets": ["744c8c43aa494843"],
    "options": {"workflow": "explainer", "duration_max": 30, "subtitles": true}
  }'
```

**看方案。** `data.status` 为 `ready` 才能制作。如果是 `needs_input`，`data.requirements` 会说明缺什么、哪里不支持；改好后重新创建方案。

```json
{"id": "0bb27ba1d9d84b1a", "data": {"status": "ready", "requirements": [], "request": {"prompt": "…", "options": {"…": "…"}}}}
```

**开始制作。** 只传方案 ID。这一步会使用账户余额，返回 `202` 和视频 ID。

```bash
curl -s https://axiomlab.online/v1/videos \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: kettle-video-001" \
  -d '{"plan_id": "0bb27ba1d9d84b1a"}'
```

**等待。** 制作通常需要几分钟，每 10 秒左右查一次即可：

```bash
curl -s https://axiomlab.online/v1/videos/b6bf4689035d474f \
  -H "Authorization: Bearer $AZIMO_API_KEY"
```

`status` 先是 `queued`、`running`，最后停在下面其中一种：

| 状态 | 含义 | 下一步 |
| --- | --- | --- |
| `complete` | 成片已通过检查 | 下载 |
| `needs_input` | 需要你补充信息或批准继续 | 看 `result.input_required`，见 [进阶用法](https://axiomlab.online/developers/advanced) |
| `rejected` | 成片没有通过质量检查 | 看 `result.qa`，调整后重新制作 |
| `failed` / `cancelled` | 制作失败或已取消 | 看 `error` |

**下载。** 视频 `complete` 后，`result.files` 里有签名下载链接：`film` 是成片 MP4，另外可能有 `srt`（字幕）和 `cover`（封面）。下载时不需要带 Key：

```bash
curl -L -o film.mp4 "<result.files.film 里的链接>"
```

链接有有效期。过期了就再查询一次视频，拿新链接。

### 同样的流程：Python SDK

需要 Python 3.9 及以上。安装方法见 [命令行与 MCP](https://axiomlab.online/developers/cli-mcp)，同一个包 `vidgen-sdk` 里既有 SDK，也有 `azimo` 命令行。

```python
import os
from vidgen_sdk import Vidgen

with Vidgen("https://axiomlab.online", os.environ["AZIMO_API_KEY"]) as azimo:
    asset = azimo.upload_asset("brief.pdf", idempotency_key="upload-brief-001")

    plan = azimo.create_plan({
        "prompt": "给经常出差住酒店的人做一条 30 秒产品视频：普利瓦折叠旅行水壶，"
                  "折叠后能放进电脑包，一次烧两杯水，结尾引导到官方商店搜索。",
        "assets": [asset["id"]],
        "options": {"workflow": "explainer", "duration_max": 30, "subtitles": True},
    }, idempotency_key="kettle-plan-001")
    print(plan["data"]["status"], plan["data"]["requirements"])

    if plan["data"]["status"] == "ready":
        video = azimo.create_video(plan_id=plan["id"], idempotency_key="kettle-video-001")
        video = azimo.wait(video["id"], timeout=3600)  # needs_input 时也会返回
        if video["status"] == "complete":
            with open("film.mp4", "wb") as f:
                f.write(azimo.download_file(video["result"]["files"]["film"]))
        else:
            print(video["status"], video.get("result", {}).get("input_required"))
```

出错时 SDK 抛出 `VidgenError`，其中有 `status`、`code`、`message` 和 `request_id`。

### 同样的流程：azimo 命令行

```bash
echo "$AZIMO_API_KEY" | azimo login        # 先验证 Key，通过后保存
azimo assets upload brief.pdf               # 打印素材 ID
azimo plan --prompt "给经常出差住酒店的人做一条 30 秒产品视频：普利瓦折叠旅行水壶……" \
  --duration 30 --subtitles --asset 744c8c43aa494843
azimo create --plan 0bb27ba1d9d84b1a        # 开始制作（使用余额）
azimo wait b6bf4689035d474f                 # 等到结束；没有完成时退出码为 3
azimo download b6bf4689035d474f --name all  # 下载成片、字幕和封面
```

`azimo plan` 只创建方案，不会开始制作。更多命令见 [命令行与 MCP](https://axiomlab.online/developers/cli-mcp)。

### 两个好习惯

- **每个写请求都带上幂等 Key。** 在请求头 `Idempotency-Key` 里放一个你自己保存的值。网络超时后用同一个 Key 重试，会拿回原来的结果，不会重复制作。反过来，同一个方案换一个新 Key 再提交，会再做一条视频。
- **请求超时不等于制作失败。** 先查询视频状态，再决定要不要重新提交。

### 价格与余额

制作会使用你的账户余额（港币）。每支视频按固定价格收费，只有成功交付才扣费，未通过质检、失败或取消都不收费，制作中途也不会要求追加费用。价格请联系 sales@azimo.ai。

### 下一步

- [工作流与视频类型](https://axiomlab.online/developers/workflows)：六种片型各需要什么资料、请求怎么写。
- [命令行与 MCP](https://axiomlab.online/developers/cli-mcp)：在终端或 AI 助手里使用 Azimo。
- [进阶用法](https://axiomlab.online/developers/advanced)：Webhook、错误码、限流、预算批准和修改版本。
- [API 参考](https://axiomlab.online/developers/api)：全部接口和字段。

---

## 工作流与视频类型

来源: https://axiomlab.online/developers/workflows

Azimo 提供六种现成的工作流，每种对应一类商业视频；本页说明各自适合做什么、要准备什么，以及最小的请求怎么写。

### 先看目录

| 工作流 | id | 画幅 | 时长（默认 / 范围） | 请求里怎么选 |
| --- | --- | --- | --- | --- |
| 项目介绍 | `project` | 16:9 | 60 秒 / 20–180 秒 | `workflow: explainer` + `video_type: project` |
| 人物名片 | `profile_card` | 9:16 | 60 秒 / 30–90 秒 | `workflow: profile_card` |
| 产品介绍 | `product` | 16:9 | 30 秒 / 20–180 秒 | `workflow: explainer` + `video_type: product` |
| 企业介绍 | `corporate` | 16:9 | 60 秒 / 20–180 秒 | `workflow: explainer` + `video_type: corporate` |
| 短剧广告 | `short_drama` | 9:16 | 30 秒 / 5–150 秒 | `workflow: short_drama` |
| 电商广告 | `ecommerce_ad` | 9:16 | 30 秒 / 5–120 秒 | `workflow: creative_video` |

自定义工作流即将推出。

`GET /v1/playground`（命令行 `azimo playground`）返回同一份目录，还会告诉你：这个账户现在能不能用（`available`，不能用时 `reason` 说明原因），以及每种工作流一个可以直接运行的示例。加 `?lang=en` 可取英文。

所有请求都发到 `POST /v1/plans`，方案 `ready` 后再用 `POST /v1/videos` 开始制作，见 [快速开始](https://axiomlab.online/developers/quickstart)。时长用 `options.duration_max`（秒），画幅用 `options.width` 和 `options.height`：16:9 是 1920×1080，9:16 是 1080×1920，1:1 是 1080×1080。

### 项目介绍 project

**适合：** 向潜在客户或合作伙伴讲清一个项目。结构固定为“痛点 → 解决方案 → 优势”，最后落到一个下一步。

**要提供：** 用 `options.content_data` 填 7 个字段，缺一个都会返回 422。`project_name` 项目名称，`audience_role` 目标人群，`pain_scenario` 痛点场景，`solution_summary` 方案一句话定义，`solution_steps` 两三个运行步骤，`advantages_with_evidence` 优势及出处，`call_to_action` 下一步。有产品截图、试点总结等资料就一起上传。

```json
{
  "prompt": "语气稳重、清楚。",
  "options": {
    "workflow": "explainer", "video_type": "project", "duration_max": 60,
    "content_data": {
      "project_name": "北叶配送云",
      "audience_role": "拥有 5 至 30 家门店的社区生鲜连锁老板",
      "pain_scenario": "每天早上多家供应商分别送货，卸货口被堵，生鲜上架延迟。",
      "solution_summary": "一个共享送货排程服务，让门店和供应商按片区约定同一送货时段。",
      "solution_steps": "1）门店确认次日订货。2）平台按片区合并订单并推荐时段。3）司机按合并路线送货。",
      "advantages_with_evidence": "分散送货次数减少｜出处：客户提供的试点总结｜卸货口等待更短。",
      "call_to_action": "预约演示。"
    }
  }
}
```

### 人物名片 profile_card

**适合：** 竖版访谈式短片，介绍一个人的经历、专长和联系方式，便于转发。

**要提供：** 在 `prompt` 里写这个人的故事：姓名、职业、做过什么、客户评价、联系方式。上传一张清晰的本人照片，第一张图片会作为这个人的照片；没有照片时，片中人物不会是本人。简历、介绍等 TXT、MD、PDF 文件的内容会并入故事。画幅必须是 1080×1920。

```json
{
  "prompt": "周砚之，云杉木作工作室创始人。做了十二年家具设计，只用本地回收木料做定制家具。客户评价：书桌用了两年，抽屉还是一样顺滑。联系方式：工作室前台预约。",
  "assets": ["<本人照片的素材 ID>"],
  "options": {"workflow": "profile_card", "duration_max": 60, "width": 1080, "height": 1920}
}
```

如果只想要画外音加素材画面、不需要人物出镜，可以改用结构化类型 `personal`（`workflow: explainer`），字段见 `GET /v1/video-types`。

### 产品介绍 product

**适合：** 30 秒讲清产品适合谁、强在哪、怎么用，最后给一个明确的购买或咨询动作。

**要提供：** 7 个字段：`product_name` 产品名称，`audience_role` 适合谁，`usage_scenario` 使用场景，`main_benefits` 最多三个卖点，`demonstration` 可展示的使用动作，`evidence` 卖点依据，`purchase_action` 购买引导。强烈建议上传产品图和规格书；产品外观以你的图片为准。

```json
{
  "assets": ["<产品图的素材 ID>"],
  "options": {
    "workflow": "explainer", "video_type": "product", "duration_max": 30,
    "content_data": {
      "product_name": "普利瓦折叠旅行水壶",
      "audience_role": "经常出差住酒店的商务旅客",
      "usage_scenario": "深夜在酒店房间，想在睡前喝一杯热饮。",
      "main_benefits": "折叠后能放进电脑包；一次烧两杯水；壶盖锁紧不漏水。",
      "demonstration": "展开、接水、烧水、倒进杯子，再折叠压平。",
      "evidence": "客户提供的规格书和实拍测试素材。",
      "purchase_action": "到品牌官方商店搜索“普利瓦折叠旅行水壶”。"
    }
  }
}
```

### 企业介绍 corporate

**适合：** 一分钟呈现企业定位、主营业务、核心能力和实力证明，为合作洽谈开场。

**要提供：** 7 个字段：`company_name` 企业名称，`positioning` 企业定位，`audience_role` 目标受众，`core_business` 主营业务，`capabilities` 核心能力，`evidence` 实力依据，`cooperation_action` 合作方向。案例、资质、产线照片越具体越好。

```json
{
  "options": {
    "workflow": "explainer", "video_type": "corporate", "duration_max": 60,
    "content_data": {
      "company_name": "蕨岭包装科技有限公司",
      "positioning": "为电商和食品品牌提供可回收的保护性包装。",
      "audience_role": "有稳定发货量的电商和食品品牌",
      "core_business": "按产品定制的模塑纸浆托盘、快递内衬和衬垫。",
      "capabilities": "自有结构设计团队、模塑产线和测试实验室。",
      "evidence": "三家客户的合作案例和跌落测试报告，由客户提供。",
      "cooperation_action": "发来产品尺寸，申请样品。"
    }
  }
}
```

### 短剧广告 short_drama

**适合：** 30 秒左右、有起承转合的广告式小短剧，用故事把品牌带进观众记忆。

**要提供：** 在 `prompt` 里写清人物、场景、冲突和转折、语气，以及结尾的产品镜头和品牌语。可以附上 TXT、PDF、PPTX 形式的剧本或品牌资料。支持 16:9、9:16、1:1。

```json
{
  "prompt": "30 秒广告短剧，虚构品牌“暖灯咖啡”。深夜，疲惫的设计师小林发现桌上有一杯手冲咖啡和室友留的便签：“明天的方案我帮你检查过了，去睡吧。”她笑着喝下第一口，灯光变暖。结尾出产品镜头和品牌语。",
  "options": {"workflow": "short_drama", "duration_max": 30, "width": 1080, "height": 1920}
}
```

### 电商广告 ecommerce_ad

**适合：** 竖版电商广告，用商品细节和日常使用场景，让人愿意点进商品页。

**要提供：** 上传商品图和包装图，这是最重要的素材。在 `prompt` 里写商品、画面、色调、旁白风格，以及哪些话不能说（例如不做功效宣传）。素材不够时，视频可能停在 `needs_input` 请你补充。支持 16:9、9:16、1:1。

```json
{
  "prompt": "30 秒竖版电商广告：青叶茶晶，茉莉绿茶和炭焙乌龙两种口味，独立条包，冷热皆可。画面有茶晶在玻璃杯中化开的微距和两款包装并排；温和女声旁白。只使用包装图上有的信息，不做功效宣传。",
  "assets": ["<包装图的素材 ID>"],
  "options": {"workflow": "creative_video", "duration_max": 30, "width": 1080, "height": 1920, "subtitles": true}
}
```

### 交付前我们检查什么

每条视频交付前都要过自动检查，具体检查项随工作流略有不同。结果在视频的 `result.qa` 里。

- **规格：** 分辨率、帧率和时长符合请求，有音轨，整条片子能完整解码。
- **结构：** 结构化片型的每一段都在，顺序正确；需要依据的段落引用了你提供的资料。
- **内容：** 回听成片旁白，核对该讲的内容都讲了，数字和单位没有丢。
- **品牌与文字：** 品牌名读对；片尾的品牌、联系方式和购买引导完整显示，不被裁切。
- **画面：** 逐个镜头检查画面质量，纯文字画面也要过同样的检查；横版素材放进竖版时保留完整画面。
- **声音：** 旁白完整不截断，音画同步，片尾留足阅读时间。
- **不编造：** 没有依据的数字、履历、案例和效果不会出现在片子里。
- 任何一项不通过，视频状态是 `rejected`，不会标成 `complete`。

### 怎样写好 brief

- 一句话说清三件事：讲什么、给谁看、看完做什么。
- 写具体的人和场景（“深夜酒店房间里的出差旅客”），不要写“广大用户”。
- 卖点最多三个，每个都给出处或能拍出来的演示。
- 只写你能证明的数字；没有数据就写实际做法。
- 名称、品牌语、联系方式一字不差地写出来，它们会原样出现在片中。
- 上传真实的产品图、照片和资料；外观和人物以你的素材为准。
- 说明不能出现的内容，例如促销、功效宣传、竞品名称。
- 时长选在工作流支持的范围内；方案返回 `needs_input` 时，先看 `requirements`。

完整字段见 [API 参考](https://axiomlab.online/developers/api)。

---

## 命令行与 MCP

来源: https://axiomlab.online/developers/cli-mcp

用 `azimo` 命令行在终端里做视频，或者通过 MCP 让 Claude、Cursor 等 AI 助手替你完成“上传 → 方案 → 制作 → 下载”。

### 安装

命令行、MCP 服务器和 Python SDK 都在同一个 Python 包 `vidgen-sdk` 里，需要 Python 3.9 及以上，只依赖 `requests`。

这个包还没有发布到 PyPI。公测期间请向 sales@azimo.ai 索取，然后用 pip 或 pipx 安装它所在的目录：

```bash
pipx install ./vidgen-sdk      # 或：pip install ./vidgen-sdk
azimo version
```

### 登录

先在 [https://axiomlab.online/dev](https://axiomlab.online/dev) 的 **开发者 → 概览 → API 密钥** 创建一把密钥，然后：

```bash
azimo login                           # 隐藏输入 Key；验证通过才保存
echo "$AZIMO_API_KEY" | azimo login   # 或者从管道读入
azimo whoami                          # 查看角色、组织和项目
```

Key 保存在 `~/.config/azimo/config.json`，只有你自己能读。也可以不登录，直接设环境变量 `AZIMO_API_KEY`。要切换项目，用 `--project` 或 `AZIMO_PROJECT`。

### 常用命令

一条视频的完整流程：

```bash
azimo playground                        # 看有哪些现成的工作流
azimo assets upload brief.pdf logo.png  # 上传资料，得到素材 ID
azimo plan --prompt "用 30 秒向食品企业采购讲清冷链配送的优势" \
  --duration 30 --ratio 9:16 --subtitles --asset 3f2a9c1b7d6e4a58
azimo create --plan 53f755f4a1b24c0e     # 确认方案后开始制作（使用余额）
azimo wait 188f86a5c3d94e21              # 等到结束
azimo download 188f86a5c3d94e21 --name all --dir ./out
```

结构化片型用 `--type` 加 `--field`，字段名用 `azimo types` 查看：

```bash
azimo plan --type product --duration 30 \
  --field product_name="普利瓦折叠旅行水壶" --field audience_role="出差的商务旅客" \
  --field usage_scenario="深夜酒店房间" --field main_benefits="可折叠；一次两杯；不漏水" \
  --field demonstration="展开、烧水、倒水、折叠" --field evidence="客户提供的规格书" \
  --field purchase_action="到官方商店搜索"
```

| 命令 | 作用 |
| --- | --- |
| `azimo playground` / `azimo types` | 现成工作流；结构化片型和字段 |
| `azimo assets upload FILE...` | 上传资料，打印素材 ID |
| `azimo plan ...` | 创建方案，不开始制作 |
| `azimo create --plan ID` | 基于方案开始制作 |
| `azimo run ...` | 创建方案，在终端里问你确认后开始制作（`--yes` 跳过询问；在脚本里不会询问） |
| `azimo status ID` / `azimo wait ID` / `azimo list` | 查看、等待、列出视频 |
| `azimo download ID --name all` | 下载成片、字幕和封面 |
| `azimo resume ID --message "..."` / `--approve-budget` | 回答 `needs_input`，或批准继续 |
| `azimo cancel ID` / `azimo balance` | 取消视频；查看余额 |

`azimo plan` 常用参数：`--prompt` 或 `--prompt-file`、`--workflow`、`--type`、`--field`、`--duration`（秒）、`--ratio`（`16:9`、`9:16`、`1:1`）、`--asset`（可重复）、`--subtitles`、`--no-music`。

每个命令都支持 `--json`，输出机器可读结果。退出码：`0` 成功，`1` 出错，`2` 用法错误，`3` `wait` 结束但视频没有完成，`4` Key 缺失或无效。

注意：`azimo create` 每次运行都会开始一次新的制作，对同一个方案运行两次会做两条视频。

### 接入 AI 助手（MCP）

有两种接法，工具完全一样：

- **本地（推荐）：** `azimo mcp` 在你的电脑上运行，可以直接上传本机文件。需要先安装上面的包。
- **远程：** `https://axiomlab.online/mcp`，不用安装任何东西，用请求头 `Authorization: Bearer <API Key>` 认证。它读不到你的本机文件，上传时由助手把文件内容发过去，单个文件最多 20 MB。

#### Claude Code

```bash
## 本地；如果已经 azimo login，可以省略 --env
claude mcp add --env AZIMO_API_KEY="$AZIMO_API_KEY" azimo -- azimo mcp

## 远程
claude mcp add --transport http azimo https://axiomlab.online/mcp --header "Authorization: Bearer $AZIMO_API_KEY"
```

#### Claude Desktop

编辑 `claude_desktop_config.json`，用本地版。如果找不到 `azimo`，把 `command` 换成 `which azimo` 输出的完整路径。

```json
{
  "mcpServers": {
    "azimo": {
      "command": "azimo",
      "args": ["mcp"],
      "env": {"AZIMO_API_KEY": "你的 API Key"}
    }
  }
}
```

#### Cursor

编辑 `~/.cursor/mcp.json`。本地版写法和 Claude Desktop 相同；远程版：

```json
{
  "mcpServers": {
    "azimo": {
      "url": "https://axiomlab.online/mcp",
      "headers": {"Authorization": "Bearer ${env:AZIMO_API_KEY}"}
    }
  }
}
```

接好之后直接说：“帮我给普利瓦折叠旅行水壶做一条 30 秒的产品视频。”

### 助手能做什么、不能做什么

**能做：** 列出工作流和片型字段，上传你指定的文件，创建方案，在你同意后开始制作，等待进度，给你下载链接；遇到 `needs_input` 时转达问题，在你同意后批准继续；查看余额，取消视频。

**必须先给你看方案。** 开始制作只能基于一个方案，工具要求助手先展示方案（工作流、时长、画幅）并得到你的明确同意。开始制作、批准继续和取消都标记为需要确认的操作，大多数客户端会在执行前询问你。对同一个方案重复调用，只会返回同一条视频。

**不能做：** 不能查看或报价格（价格请联系 sales@azimo.ai）；不能绕过余额和限额；本地版拒绝读取隐藏文件和目录（例如 `~/.ssh`）；远程版读不到你电脑上的文件。

### 安全建议

- 给每个客户端单独建一把 Key，泄露时只撤销这一把。
- 只想让助手查进度，就用 `viewer` 角色的 Key，它不能创建方案或开始制作。
- 不要把 Key 贴进聊天，放在环境变量或配置文件里。

### 排错

- 退出码 `4` 或 `401`：Key 缺失、错误或已撤销，重新 `azimo login`。
- `403 read-only key`：当前是 `viewer` Key，换 `editor` 或 `owner`。
- `402`：余额或额度不足。
- 方案是 `needs_input`：按 `requirements` 修改，例如 `unsupported_duration` 表示时长超出范围。
- MCP 客户端说服务器启动失败：在终端运行 `azimo mcp`，错误信息会打印在 stderr。

更多内容见 [进阶用法](https://axiomlab.online/developers/advanced) 和 [API 参考](https://axiomlab.online/developers/api)。

---

## 进阶用法

来源: https://axiomlab.online/developers/advanced

接入正式环境前需要了解的几件事：Webhook、安全重试、错误处理、限流、项目与权限、预算批准、修改版本和删除文件。

完整的接口和字段见 [API 参考](https://axiomlab.online/developers/api)，这里只讲怎么用。

### 用 Webhook 接收结果

不想轮询，就登记一个回调地址。视频状态每次变化，Azimo 都会 POST 一个事件过来。登记需要 `owner` 角色的 Key：

```bash
curl -s https://axiomlab.online/v1/webhooks \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: webhook-001" \
  -d '{"url": "https://example.com/hooks/azimo", "name": "Production updates"}'
```

返回里的 `signing_secret`（以 `whsec_` 开头）只显示这一次，请保存好。

事件长这样，`type` 是 `video.` 加上状态，例如 `video.progress`、`video.needs_input`、`video.complete`、`video.rejected`、`video.failed`、`video.cancelled`：

```json
{"id": "d8009f54780243ea", "sequence": 12, "type": "video.complete", "api_version": "v1", "project_id": "c56eb945e4464aec", "created_at": 1790000000, "data": {"id": "b6bf4689035d474f", "status": "complete", "stage": "complete", "progress": 100}}
```

每个请求带两个头：`Vidgen-Event-Id`（事件 ID）和 `Vidgen-Signature: t=<时间戳>,v1=<签名>`。签名是 `HMAC-SHA256(signing_secret, "<时间戳>." + 原始请求体)` 的十六进制。一定要对收到的原始字节验签，不要先解析 JSON 再序列化：

```python
import hashlib, hmac, time

def verify(secret: str, header: str, body: bytes, tolerance: int = 300) -> bool:
    try:
        parts = dict(item.split("=", 1) for item in header.split(","))
        timestamp = int(parts["t"])
    except (KeyError, ValueError):
        return False
    if abs(time.time() - timestamp) > tolerance:  # 拒绝 5 分钟以前的请求
        return False
    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))
```

Python SDK 自带同样的函数 `Vidgen.verify_webhook(secret, header, body)`，TypeScript SDK 是 `Vidgen.verifyWebhook(secret, header, body)`。

收到事件后：

- 验签通过就尽快返回 2xx，耗时的处理放到自己的队列里。
- 投递失败会自动重试，最长持续约 72 小时，所以同一个事件可能到达多次：请按事件 `id` **去重**。
- 事件不保证按顺序到达。拿不准时，用 `GET /v1/videos/{id}` 查最新状态。
- 以后可能增加新的事件类型，遇到不认识的 `type` 直接忽略即可。
- 下载链接会过期；需要时重新查询视频，拿新链接。

也可以只给某一条视频设回调：在 `POST /v1/videos` 里加 `webhook_url`，响应里的 `webhook_signing_secret` 就是验签用的密钥。不用 Webhook 的话，可以用 `GET /v1/events?after=<sequence>` 按顺序拉取事件。

### 安全重试：Idempotency-Key

所有创建类的 POST（上传、方案、制作、修改、取消、回答、Webhook 等）都接受请求头 `Idempotency-Key`，长度 1–128 个字符。

- 同一个 Key、同样的请求体：返回第一次的结果，不会再做一次。
- 同一个 Key、不同的请求体：返回 `409`，错误码 `idempotency_conflict`。
- 换一个新 Key：就是一个新请求。对同一个方案换 Key 再提交，会再做一条视频。

做法：在发请求前生成 Key，和你的业务记录一起保存；超时或断线后，用同一个 Key 重试。

### 处理错误

所有错误都是同一种格式：

```json
{"error": {"code": "validation_error", "message": "request validation failed", "details": [{"loc": ["body", "options", "duration_max"], "msg": "Input should be less than or equal to 180", "type": "less_than_equal"}], "request_id": "64ceb19e540b438f8b9a4df3bfe62ba7"}}
```

按 `code` 判断，不要按 `message` 的文字判断。每个响应都有 `X-Request-ID` 头；联系我们时请附上 `request_id`。

| HTTP | `code` | 怎么办 |
| --- | --- | --- |
| 401 | `unauthenticated` | Key 缺失、错误或已撤销，换一把有效的 Key |
| 402 | `insufficient_balance` / `budget_exceeded` | 余额不足或达到额度上限；充值或联系 sales@azimo.ai，不要反复重试 |
| 403 | `forbidden` | 角色或项目不允许，例如 `read-only key` |
| 403 | `contact_sales` | 与价格相关的请求，请联系 sales@azimo.ai |
| 404 | `not_found` | ID 不存在，或不在当前项目里 |
| 409 | `conflict` / `idempotency_conflict` | 状态不允许（例如视频已结束），或 Key 被用于不同的请求 |
| 413 | `payload_too_large` / `storage_quota_exceeded` | 文件超过 60 MB，或存储空间已满，删掉不用的素材 |
| 415 | `unsupported_media_type` | 不支持的文件类型 |
| 422 | `validation_error` | 请求字段不对，`details` 列出具体问题 |
| 429 | `rate_limited` | 请求太频繁，按 `Retry-After` 等待后重试 |
| 500 | `internal_error` | 我们这边出错，带上 `request_id` 联系我们 |
| 503 | `backend_unconfigured` | 这个工作流暂时不可用 |

### 限流与 429

- 每把 Key 默认每分钟最多 600 次 API 请求。
- 每个组织每小时能开始的制作数量有上限；Key 也可以单独设更低的上限。
- 超出时返回 `429`，响应头 `Retry-After` 是需要等待的秒数。

Python SDK 会对 GET 和带 `Idempotency-Key` 的 POST 自动重试 429 和 5xx，并遵守 `Retry-After`。轮询视频状态时，每 10 秒左右一次就够了。

### 项目与 Key 的角色

资源（素材、方案、视频、Webhook）都属于某个项目。请求头 `X-Project-ID` 选择项目，不传就用默认项目。组织 owner 可以用 `POST /v1/projects` 新建项目，用 `POST /v1/api-keys` 创建 Key 并指定 `role` 和 `project_id`。

| 角色 | 能做什么 |
| --- | --- |
| `viewer` | 只读：查看视频、方案、素材、事件和余额 |
| `editor` | 另外可以上传、创建方案、开始制作、取消、回答和修改 |
| `owner`（绑定项目） | 另外可以管理本项目的 Webhook |
| `owner`（不绑定项目） | 组织 owner：管理所有项目和 Key |

每个应用或客户端单独用一把 Key，按最小权限选择角色。

### 预算批准

预付费账户按片固定价格收费，价格不随制作用量变化，所以**不会请你批准追加费用**。如果一条视频触发了我们内部的成本复核，它会暂停在 `needs_input`，`result.input_required` 是：

```json
{"code": "budget_approval", "actor": "operator", "message": "…", "approvable": false}
```

这时你不需要做任何事：价格不变，Azimo 团队复核后视频会继续；不想要了可以取消。对它调用 `/resume` 会返回 `409`。

由服务方统一结算（非预付费）的组织，视频要超出花费上限时会暂停，`input_required` 是：

```json
{"code": "budget_approval", "actor": "customer", "message": "…", "approvable": true}
```

同意继续，就回答：

```bash
curl -s https://axiomlab.online/v1/videos/b6bf4689035d474f/resume \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: approve-b6bf-001" \
  -d '{"approve_budget": true}'
```

SDK 是 `azimo.approve_budget(video_id)`，命令行是 `azimo resume ID --approve-budget`。批准后仍受组织额度约束，超出返回 `402`；已经完成的步骤不会重做。

其他 `needs_input` 用文字回答：`{"message": "..."}`，需要补资料时加上 `"assets": ["<素材 ID>"]`。长时间不回应（默认 7 天）的视频会自动取消。

### 修改版本

对已结束的视频（`complete`、`rejected`、`failed`、`cancelled` 或 `needs_input`）可以做一个修改版：

```bash
curl -s https://axiomlab.online/v1/videos/b6bf4689035d474f/revisions \
  -H "Authorization: Bearer $AZIMO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: revise-b6bf-001" \
  -d '{"prompt": "完整的新 brief：同样的产品，结尾强调一次能烧两杯水。", "options": {"subtitles": true}}'
```

- 返回一条新视频，`parent_id` 指向原视频，原视频保留不变。
- `prompt` 会整体替换原来的 brief，请写完整；`options` 只改你传的字段；`assets` 不传就沿用原来的素材（原素材已删除时会返回 `404`，这时请重新上传并传 `assets`）。
- 修改版是一次完整的新制作，会使用余额。视频还在制作中时返回 `409`。

### 取消与删除文件

- 取消：`POST /v1/videos/{id}/cancel`。排队或等待中的视频立即取消；正在制作的会在下一步开始前停下。取消的视频按已经花掉的用量收费。
- 质检不过不收费：以 `rejected`（未通过质检）或 `failed`（系统未能完成）结束的视频不扣余额，冻结额度全部退回，钱包流水里有一条金额为 0 的 `settle` 记录说明原因。
- 删除素材：`DELETE /v1/assets/{id}`。已经用它做好的视频不受影响，但之后基于这条视频做修改版时要重新提供素材。
- 删除视频文件：`DELETE /v1/videos/{id}`，只能删已结束的视频（先取消）。成片、字幕和封面会被清除，下载链接失效，视频记录保留。
- 品牌、模板和 Webhook 也可以用 `DELETE` 删除。
- 成片只保留一段时间，请及时下载保存。

---

## API 参考

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

### 基础约定

- **Base URL**: `https://axiomlab.online`
- **鉴权**: 每个 `/v1` 请求带 `Authorization: Bearer <API key>`。登录后在[个人中心](https://axiomlab.online/dev)创建 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://axiomlab.online/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://axiomlab.online/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://axiomlab.online/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://axiomlab.online/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://axiomlab.online/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://axiomlab.online/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://axiomlab.online/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://axiomlab.online/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://axiomlab.online/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://axiomlab.online/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://axiomlab.online/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://axiomlab.online/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://axiomlab.online/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://axiomlab.online/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 carries no amounts. With `approvable: true` answer it with `POST /v1/videos/{id}/resume {"approve_budget": true}`; with `approvable: false` (`actor: operator`, prepaid flat-priced jobs) it is an internal review: nothing to approve, the price does not change; 可为 null |
| `data[].result.native_project` | any |  |  |
| `data[].requested_workflow` | string | 是 |  |
| `data[].video_type` | string |  | The video type within the workflow, e.g. `project`, when the request set one; 可为 null |
| `data[].title` | string |  | A short name for lists: the subject named in the brief (e.g. the project name) or the start of the prompt; 可为 null |
| `next_cursor` | string |  | Opaque; pass as `cursor` (or the `after` alias) for the next page; 可为 null |
| `has_more` | boolean |  | 默认 `false` |

```bash
curl "https://axiomlab.online/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 carries no amounts. With `approvable: true` answer it with `POST /v1/videos/{id}/resume {"approve_budget": true}`; with `approvable: false` (`actor: operator`, prepaid flat-priced jobs) it is an internal review: nothing to approve, the price does not change; 可为 null |
| `result.native_project` | any |  |  |
| `requested_workflow` | string | 是 |  |
| `video_type` | string |  | The video type within the workflow, e.g. `project`, when the request set one; 可为 null |
| `title` | string |  | A short name for lists: the subject named in the brief (e.g. the project name) or the start of the prompt; 可为 null |
| `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://axiomlab.online/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 a pending budget stop that has `approvable: true`; 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 carries no amounts. With `approvable: true` answer it with `POST /v1/videos/{id}/resume {"approve_budget": true}`; with `approvable: false` (`actor: operator`, prepaid flat-priced jobs) it is an internal review: nothing to approve, the price does not change; 可为 null |
| `result.native_project` | any |  |  |
| `requested_workflow` | string | 是 |  |
| `video_type` | string |  | The video type within the workflow, e.g. `project`, when the request set one; 可为 null |
| `title` | string |  | A short name for lists: the subject named in the brief (e.g. the project name) or the start of the prompt; 可为 null |

```bash
curl -X POST "https://axiomlab.online/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 carries no amounts. With `approvable: true` answer it with `POST /v1/videos/{id}/resume {"approve_budget": true}`; with `approvable: false` (`actor: operator`, prepaid flat-priced jobs) it is an internal review: nothing to approve, the price does not change; 可为 null |
| `result.native_project` | any |  |  |
| `requested_workflow` | string | 是 |  |
| `video_type` | string |  | The video type within the workflow, e.g. `project`, when the request set one; 可为 null |
| `title` | string |  | A short name for lists: the subject named in the brief (e.g. the project name) or the start of the prompt; 可为 null |
| `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://axiomlab.online/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 carries no amounts. With `approvable: true` answer it with `POST /v1/videos/{id}/resume {"approve_budget": true}`; with `approvable: false` (`actor: operator`, prepaid flat-priced jobs) it is an internal review: nothing to approve, the price does not change; 可为 null |
| `result.native_project` | any |  |  |
| `requested_workflow` | string | 是 |  |
| `video_type` | string |  | The video type within the workflow, e.g. `project`, when the request set one; 可为 null |
| `title` | string |  | A short name for lists: the subject named in the brief (e.g. the project name) or the start of the prompt; 可为 null |

```bash
curl "https://axiomlab.online/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://axiomlab.online/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://axiomlab.online/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://axiomlab.online/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://axiomlab.online/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 carries no amounts. With `approvable: true` answer it with `POST /v1/videos/{id}/resume {"approve_budget": true}`; with `approvable: false` (`actor: operator`, prepaid flat-priced jobs) it is an internal review: nothing to approve, the price does not change; 可为 null |
| `jobs[].result.native_project` | any |  |  |
| `jobs[].requested_workflow` | string | 是 |  |
| `jobs[].video_type` | string |  | The video type within the workflow, e.g. `project`, when the request set one; 可为 null |
| `jobs[].title` | string |  | A short name for lists: the subject named in the brief (e.g. the project name) or the start of the prompt; 可为 null |
| `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 carries no amounts. With `approvable: true` answer it with `POST /v1/videos/{id}/resume {"approve_budget": true}`; with `approvable: false` (`actor: operator`, prepaid flat-priced jobs) it is an internal review: nothing to approve, the price does not change; 可为 null |
| `data[].result.native_project` | any |  |  |
| `data[].requested_workflow` | string | 是 |  |
| `data[].video_type` | string |  | The video type within the workflow, e.g. `project`, when the request set one; 可为 null |
| `data[].title` | string |  | A short name for lists: the subject named in the brief (e.g. the project name) or the start of the prompt; 可为 null |
| `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://axiomlab.online/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 carries no amounts. With `approvable: true` answer it with `POST /v1/videos/{id}/resume {"approve_budget": true}`; with `approvable: false` (`actor: operator`, prepaid flat-priced jobs) it is an internal review: nothing to approve, the price does not change; 可为 null |
| `jobs[].result.native_project` | any |  |  |
| `jobs[].requested_workflow` | string | 是 |  |
| `jobs[].video_type` | string |  | The video type within the workflow, e.g. `project`, when the request set one; 可为 null |
| `jobs[].title` | string |  | A short name for lists: the subject named in the brief (e.g. the project name) or the start of the prompt; 可为 null |
| `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 carries no amounts. With `approvable: true` answer it with `POST /v1/videos/{id}/resume {"approve_budget": true}`; with `approvable: false` (`actor: operator`, prepaid flat-priced jobs) it is an internal review: nothing to approve, the price does not change; 可为 null |
| `data[].result.native_project` | any |  |  |
| `data[].requested_workflow` | string | 是 |  |
| `data[].video_type` | string |  | The video type within the workflow, e.g. `project`, when the request set one; 可为 null |
| `data[].title` | string |  | A short name for lists: the subject named in the brief (e.g. the project name) or the start of the prompt; 可为 null |
| `counts` | map<string, integer> | 是 |  |

```bash
curl "https://axiomlab.online/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://axiomlab.online/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://axiomlab.online/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://axiomlab.online/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://axiomlab.online/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://axiomlab.online/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://axiomlab.online/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://axiomlab.online/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://axiomlab.online/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://axiomlab.online/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://axiomlab.online/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://axiomlab.online/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://axiomlab.online/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://axiomlab.online/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://axiomlab.online/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://axiomlab.online/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://axiomlab.online/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://axiomlab.online/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://axiomlab.online/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://axiomlab.online/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://axiomlab.online/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://axiomlab.online/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://axiomlab.online/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://axiomlab.online/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://axiomlab.online/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://axiomlab.online/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://axiomlab.online/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 | 是 | Reserved for videos in production; released or charged when each one ends |
| `available_cents` | integer | 是 |  |
| `low_balance_cents` | integer | 是 | 可为 null |
| `currency` | string | 是 | Always `HKD`: every amount is in Hong Kong dollar cents |
| `organization_id` | string | 是 |  |

```bash
curl "https://axiomlab.online/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 | 是 |  |
| `data[].currency` | string | 是 | Unit of amount_cents and hold_cents: `HKD`, or `USD` for entries written before the wallet switched to HKD (the switch itself is an `adjust` entry whose note states the conversion rate) |
| `next_cursor` | string |  | Opaque; pass as `cursor` (or the `after` alias) for the next page; 可为 null |
| `has_more` | boolean |  | 默认 `false` |

```bash
curl "https://axiomlab.online/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 | 是 | HKD cents, HK$100–HK$100,000; 范围 10000–10000000 |

**返回 201**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 是 |  |
| `url` | string | 是 |  |
| `amount_cents` | integer | 是 | HKD cents credited to the wallet once paid |
| `currency` | string |  | 默认 `HKD` |
| `charge_currency` | string |  | Currency Stripe charges: HKD, the wallet's own currency; 默认 `HKD` |
| `charge_amount` | integer |  | Amount Stripe charges, in charge_currency cents (equal to amount_cents); 默认 `0` |

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

#### GET /v1/usage — Usage

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

The amount billed to this project's wallet in [from, to) (default: the last 30 days) and its paid calls and job counts,
grouped on request. `group_by=job` pages by job id with `after`.

**参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `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> | 是 |  |
| `billed_cents` | integer | 是 | Amount charged to the wallet in the range, in cents of `currency` |
| `currency` | string | 是 | Always `HKD` |
| `group_by` | string | 是 |  |
| `groups` | array<object> | 是 | 可为 null |
| `next_cursor` | string | 是 | 可为 null |

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

### 服务状态

健康检查，不需要 Key。

#### GET /healthz — Healthz

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

```bash
curl "https://axiomlab.online/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://axiomlab.online/readyz"
```


---

## Skills

来源: https://axiomlab.online/developers/skills

Skill 是一份写给 AI 助手的说明书。把它放进 Claude Code 或 Claude 的技能目录，助手就知道什么时候、怎样用 Azimo 做视频：先出方案、确认后再制作、等待并取回成片。

### 安装

1. 先按[命令行与 MCP](https://axiomlab.online/developers/cli-mcp)装好 `azimo` 命令，或接好 MCP。
2. 新建文件 `~/.claude/skills/azimo/SKILL.md`（只给当前项目用，就放在项目的 `.claude/skills/azimo/SKILL.md`），内容复制下面这段。
3. 重开会话后直接说：“用 Azimo 给这个项目做一支 60 秒的路演视频。”

### SKILL.md

```markdown
---
name: azimo
description: 用 Azimo 制作企业视频（项目路演、产品介绍等）。用户要做视频、生成宣传片或路演视频时使用。
---

## 用 Azimo 制作视频

1. 收集信息：视频讲什么、给谁看、看完要做什么；有资料（PDF、PPT、图片）就先上传。
2. 创建方案（不扣费）：`azimo plan --prompt "…" --duration 60 --subtitles`，项目路演视频加上 `--workflow project` 和七个 content_data 字段。
3. 把方案要点给用户看，**得到确认后**再制作：`azimo create --plan <方案 ID>`。每条成片按次计费，质检未通过不收费。
4. 等待：`azimo wait <视频 ID>`，一条片通常 10–40 分钟。
5. 取回：`azimo download <视频 ID> --name all`，告诉用户成片、字幕和封面的位置。

不要在用户确认前开始制作；超时不等于失败，先查状态再决定是否重试。
```

---

## 更新日志

来源: https://axiomlab.online/developers/changelog

面向 API、命令行和控制台用户的变化，按时间倒序。

### 2026-09-30

- **计费改为港币、按条计费**：每条交付的成片固定价格，质检未通过、系统失败或取消不收费；余额以港币显示，在线充值 HK$100–HK$100,000。
- **开发者区**：控制台新增概览（API Key 与快速开始）、账单、用量、模型、Webhook、连接（MCP 配置）。
- **Skills**：提供给 Claude 使用的 Azimo 技能文件，见 [Skills](https://axiomlab.online/developers/skills)。
- **邀请制注册**：内测期间凭邀请码注册。
- **文档**：中英文开发者文档，每页可一键复制为 Markdown 发给 AI 助手。
- **命令行与 MCP**：`azimo` 命令和远程 MCP（`https://axiomlab.online/mcp`）。