创建生成任务
提交生成任务——积分在提交时检查并预留。
POST/api/v1/generations
提交任务并立即返回。积分在提交时检查并预留，响应会告知确切金额。
请求体
| 字段 | 类型 | 说明 |
|---|---|---|
model | string · 必填 | 来自 GET /api/v1/models 的复合模型 id，例如 "text-to-image:rikcgfbufzdm"。 |
input | object · 必填 | 模型参数，键名见模型的 params 列表；列表里没有的键会以 invalid_request 拒绝（param 指出是哪个）。几乎所有模型都接受 prompt。图片、视频、音频字段只接受存储在本服务上的文件链接——先用 POST /api/v1/uploads 上传，或复用之前任务的结果链接（GET /api/v1/uploads 可以列出两者）；其它链接会以 media_not_uploaded 拒绝。 |
callback_url | string | 任务进入终态时接收 POST 回调的 HTTPS 地址。不允许指向私网或内部地址。 |
curl https://vidocraft.com/api/v1/generations \
-X POST \
-H "Authorization: Bearer sk_test_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "text-to-image:rikcgfbufzdm",
"callback_url": "https://your-app.com/api/hooks/generation",
"input": {
"prompt": "a lighthouse on a cliff at golden hour, cinematic",
"aspect_ratio": "16:9"
}
}'响应
{
"taskId": "3f2ak9mr7xqp4tnz8blc6ywh",
"credits": 1
}credits 是本任务预留的积分数。测试密钥额外返回 sandbox: true。
-
组图（
max_images）。 部分图片模型用max_images设定张数上限，而不是固定张数：模型按提示词要求的张数出图，最多到上限，所以请在提示词里写明张数（如"生成 3 张……"）。积分按上限预留；任务成功后按实际返回的张数结算，多余部分退还，任务查询里的credits即最终金额。部分模型对参考图和max_images设了合计上限，GET /api/v1/models会在该参数上以sharedLimit标出（如{ "with": "image_input", "total": 15 }），超出时请求返回invalid_request。 -
提示词会经过服务端内容审核，被拒绝时返回
moderation_blocked。从批准域名直接引用（未上传）的图片和视频同样会审核。 -
生成的图片和视频结果也会审核。被判违规的结果不会交付：任务以
failed结束，failed_reason为nsfw_output_blocked，积分不退回（billing_status: charged）。 -
高级模型，以及
GET /api/v1/models中标记available: false/premium: true的选项或参数，需要有效订阅，否则返回403 forbidden；选项或参数出错时，错误中的param指明是哪一个。不传这些参数没有问题——会使用你的账户下列出的默认值。 -
订阅账户的生成结果默认私有，免费账户为公开，与工作室行为一致。