AI API 开发文档 - 一个 Key 调用全部能力

01 · 鉴权

把 Key 放在服务端

在开发者控制台创建 umi_live_… Key，然后通过环境变量注入服务端。不要把 Key 写进网页、App 安装包、公开仓库或日志。

export UMI_API_KEY="umi_live_请替换为你的Key"
# 仅保存在服务端环境变量或密钥管理服务中

02 · 能力发现

先查询当前可调用能力

一个 Key 默认拥有账户下全部已开放能力。新能力通过同一目录出现，无需为不同供应商换 Key。

curl https://umi6.com/api/ai/v1/capabilities \
  -H "Authorization: Bearer $UMI_API_KEY"

03 · 创建任务

所有能力使用统一任务入口

Idempotency-Key 长度为 8–128 字符。网络重试时复用原值，可安全获得同一个任务；相同键配不同请求会返回冲突。平台在内部优先选择已验收的低价供应商，并在满载、熔断或明确故障时自动分流，调用方无需指定供应商。

curl https://umi6.com/api/ai/v1/tasks \
  -H "Authorization: Bearer $UMI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-20260729-001" \
  -d '{
    "capability": "text.chat",
    "input": { "prompt": "把这段内容整理成三点摘要" },
    "parameters": { "max_output_tokens": 800 }
  }'

text.chat文本能力同步完成时直接返回结果。

04 · 查询任务

同步和异步返回同一种 Task

提交可能返回 200（已完成）或 202（处理中）。异步任务每 2–5 秒查询一次；到达终态后停止轮询。

curl "https://umi6.com/api/ai/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $UMI_API_KEY"

queued→running→transferring→succeeded

05 · 错误处理

只依赖稳定错误码

INVALID_REQUEST

修正参数后再提交，不要原样重试。

AUTHORIZATION_REQUIRED

补充素材或人物授权确认。

RATE_LIMIT_EXCEEDED

按提示退避，避免并发重试风暴。

PROVIDER_TIMEOUT

可使用同一幂等键安全重试。

CONTENT_POLICY_VIOLATION

调整输入内容，不自动绕过审核。

PROVIDER_UNAVAILABLE

短暂退避；平台会按已验收路由自动容灾。

CAPACITY_EXHAUSTED

全部供应商梯队暂时满载；保持幂等键并退避重试。

每个响应都带 request_id。联系支持时提供该值和任务 ID，不要发送完整 API Key 或客户原始素材。

一个 Key，调用全部已开放能力