模型原子 API

使用前准备

模型原子 API 面向外部应用提供文本、图片、视频、语音和工作流模型调用。请求进入现有任务队列，提交成功返回 202；系统在提交时预占积分，并在任务完成或失败后按实际用量结算或释放。

鉴权与 API Key

网页登录取得的用户 access token 和个人中心创建的 vvk_ API Key 都通过 Authorization: Bearer <credential> 传入。API Key 明文仅在创建时返回一次，服务端只保存摘要。

在个人中心创建 API Key 时，按钮会在请求期间进入加载并禁止重复提交；点击复制后会显示成功或失败提示。

API Key 管理接口仅接受用户 access token：

GET /api/user/api-keys：列表。
POST /api/user/api-keys：创建，传入 name、scopes 和可选 expiresAt。
GET /api/user/api-keys/{keyId}：读取元数据。
PATCH /api/user/api-keys/{keyId}：修改名称、授权范围、启用状态或有效期。
DELETE /api/user/api-keys/{keyId}：删除。

生产环境建议配置长期稳定的随机 API_KEY_SALT；未配置时兼容复用 API_ENCRYPTION_KEY。更换该值会使已有 API Key 失效。

授权范围包括 models:read、models:text、models:image、models:video、models:audio 和 models:workflow。调用能力接口需要对应范围；模型列表和任务查询需要 models:read。

操作步骤

模型与任务接口

GET /api/v1/models/{capability} 返回当前用户可用模型，capability 可取 text、image、video、audio 或 workflow。audio 同时覆盖目录中的 audio 与 tts 模型；工作流目录只返回以 ComfyUI 或 RunningHub 协议发布的图片/视频模型。

POST /api/v1/models/{capability} 至少需要所属用户自己的 projectId 和目录中的 model。常用字段如下：

能力	输入字段
`text`	`messages`，或单条 `prompt`；可传 `options.temperature`、`maxTokens` 等
`image`	`prompt`、可选 `referenceImages` 和 `options`
`video`	`prompt` 或 `imageUrl`，以及可选 `options`
`audio`	`text` 和可选 `options`
`workflow`	与目录中模型的图片或视频类型一致

示例：


curl -X POST "$BASE_URL/api/v1/models/text" \
  -H "Authorization: Bearer $VVICAT_API_KEY" \
  -H "Idempotency-Key: request-20260908-001" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"PROJECT_ID","model":"provider::model-id","prompt":"写一句开场白"}'

结果与状态

响应中的 statusUrl 指向 GET /api/v1/tasks/{taskId}。任务的 status 为 queued、processing、completed、failed 或 canceled；完成后从 task.result 读取文本或站内稳定媒体 URL。图片、视频和语音任务会等待供应商异步生成结束并完成媒体入库后才进入 completed。

付费请求建议传入不超过 200 个字符的 Idempotency-Key。同一用户、同一能力和相同请求内容使用相同键重试时会返回原任务，包括已经结束的任务；相同键对应不同项目、模型或参数时返回 409，避免静默复用错误结果。

媒体输入只接受公网 HTTP(S) URL 和协议默认端口。服务端会在提交及下载时阻止本机、内网和保留地址，逐跳检查最多 3 次重定向，并拒绝超过 100 MB 或非图片、视频、音频类型的响应。

权限和边界

API Key 只能访问其所属用户自己的模型调用任务，不会获得站内其他 API 的访问权。项目必须由调用用户所有，避免协作者替项目所有者发起计费。

文本/分析、图片、视频、音频和其他类别兜底并发由管理员在“后台 → 用户管理 → 基本资料”设置；未配置时五项默认均为 5。口型同步、编辑渲染等不属于前四类的模型任务使用“其他类别”上限。并发限制通过 Redis 在全部 Worker 实例间共享，个人模型设置只展示生效值，不能自行修改；等待期间被取消的任务不会继续调用模型。

常见问题

为什么相同 Idempotency-Key 返回 409？ 该键已用于不同请求。请为新的项目、模型或参数生成新键。

为什么任务长时间处于 processing？ 任务可能正在等待管理员配置的并发名额；无需重复提交，可继续轮询 statusUrl。