快速开始

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

先方案，后制作#

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

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

第 1 步：获取 API Key#

1. 登录 https://azimo.ai/console。公测期间注册需要邀请码，请发邮件到 sales@azimo.ai 索取。
2. 打开 个人中心 → API Key，创建一把 Key。Key 只显示一次，请马上保存。
3. 在终端里设置环境变量，后面的例子都会用到：

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。

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 写清楚：片子讲什么、给谁看、看完要做什么。

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 会说明缺什么、哪里不支持；改好后重新创建方案。

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

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

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 秒左右查一次即可：

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

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

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

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

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

同样的流程：Python SDK#

需要 Python 3.9 及以上。安装方法见 命令行与 MCP，同一个包 vidgen-sdk 里既有 SDK，也有 azimo 命令行。

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 命令行#

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。

两个好习惯#

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

价格与余额#

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

下一步#

• 工作流与视频类型：六种片型各需要什么资料、请求怎么写。
• 命令行与 MCP：在终端或 AI 助手里使用 Azimo。
• 进阶用法：Webhook、错误码、限流、预算批准和修改版本。
• API 参考：全部接口和字段。