用途：Moda 公开 REST API 位于 https://api.moda.app/v1，适合没有人工介入的场景，例如定时任务、CI 流水线、Webhook 驱动的工作进程、服务端集成和自定义仪表盘。若用户是在与 AI 智能体（如 Claude Desktop、Cursor）对话，应改用 moda-mcp 技能，它处理 OAuth、会话上下文和对话式流程；REST API 与 MCP 可作用于同一 Moda 账户。
主要能力：可创建品牌套件、上传参考资料、启动设计任务、导出画布。认证使用 Bearer 令牌，格式为 moda_live_<suffix>，密钥在 Settings → Developer → REST API 创建，仅显示一次，应存入密钥管理器。每个请求需固定 Moda-Version: 2026-05-01，省略会解析为当前默认版本。
使用方式：典型流程为创建 API 密钥并选择权限范围、确保品牌套件存在、上传参考资料、用 POST /v1/tasks 启动设计任务、通过 Webhook 或轮询 GET /v1/tasks/{id} 获取终态、最后用 POST /v1/canvases/{id}/export 导出。启动任务前需明确 format_category（slides / social / carousel / pdf / diagram / ui / other），否则默认生成幻灯片；可传 idempotency_key 保证重试安全。交付策略可选 callback_url（仅 API 密钥认证可用，OAuth 调用会返回 400）、轮询或 Prefer: wait（最长 30 秒）。JSON 请求体中的 ID 必须带前缀（cvs_、task_、bk_、file_ 等），裸 UUID 会返回 400。
限制：设计任务通常耗时 2–10 分钟，Prefer: wait 常会超时并返回非终态信封。错误需按 error.type 分支处理，仅对 rate_limited、upstream_error、internal_error 重试。列表接口使用游标分页，游标不透明且已签名，不可手工构造。Webhook 仅在终态触发，签名验证为对 {timestamp}.{body} 做 HMAC-SHA256。具体权限范围、版本迁移、错误目录等细节见官方文档。