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

# 快速开始

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

## 先方案，后制作

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

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

## 第 1 步：获取 API Key

1. 登录 [https://azimo.ai/console](https://azimo.ai/console)。公测期间注册需要邀请码，请发邮件到 sales@azimo.ai 索取。
2. 打开 **个人中心 → API Key**，创建一把 Key。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://azimo.ai/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://azimo.ai/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://azimo.ai/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://azimo.ai/v1/videos/b6bf4689035d474f \
  -H "Authorization: Bearer $AZIMO_API_KEY"
```

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

| 状态 | 含义 | 下一步 |
| --- | --- | --- |
| `complete` | 成片已通过检查 | 下载 |
| `needs_input` | 需要你补充信息或批准继续 | 看 `result.input_required`，见 [进阶用法](https://azimo.ai/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://azimo.ai/developers/cli-mcp)，同一个包 `vidgen-sdk` 里既有 SDK，也有 `azimo` 命令行。

```python
import os
from vidgen_sdk import Vidgen

with Vidgen("https://azimo.ai", 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://azimo.ai/developers/cli-mcp)。

## 两个好习惯

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

## 价格与余额

制作会使用你的账户余额。价格请联系 sales@azimo.ai。

## 下一步

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