跳到正文
文档版本 r15
OpenAPIJSONYAML
API 参考 / 生成任务

创建生成任务

createGeneration
POST/v1/generations

下面的接口说明为英文原文。

Each accepted POST durably records a separate generation. While pending_funding the reserved amount is zero. Funding success queues the job; check its status for a funding rejection. Submitting the same request twice can incur two charges. After a lost response, check the generation list before deciding to create another task.

Markdown 文件在 Playground 试运行文档版本 r15

鉴权

在请求头带上项目 Key,例如 Authorization: Bearer $VIZO_API_KEY。Key 只放在服务端。

请求体

JSON 对象,不接受未列出的字段。

请求体
字段说明
inputobject必填

生成参数。具体字段取决于模型和操作,见各模型页。

input 的字段
input 的字段
aspect_ratiostring可选
asset_idstring可选
最多 128 个字符
duration_secondsinteger可选
最小 -1
generate_audioboolean可选
nativeany可选
promptstring可选
至少 1 个字符, 最多 4000 个字符
resolutionstring可选
source_generation_idstring可选
最多 128 个字符
videoobject可选
video 的字段
video 的字段
bitrate_modestring可选
contentobject[], 可为 null可选
content 的字段
content 的字段
asset_idstring可选
draft_generation_idstring可选
rolestring可选
textstring可选
typestring必填
urlstring可选
draftboolean可选
execution_expires_afterinteger可选
moderation_optionsobject可选
moderation_options 的字段
moderation_options 的字段
ipsstring[], 可为 null必填
omni_reference_task_typestring可选
output_formatstring可选
return_last_frameboolean可选
safety_identifierstring可选
seedinteger可选
toolsobject[], 可为 null可选
tools 的字段
tools 的字段
typestring必填
watermarkboolean可选
metadatamap<string, string>可选

你自己的字符串键值,原样返回。建议写入 client_reference,回包丢失时用它找回任务。

modelstring必填

模型 ID,来自 listModels 或模型页。

至少 1 个字符
operationstring必填

生成类型。只接受该模型已发布的操作。

text-to-videoimage-to-videoreference-to-videovideo-editvideo-extendvideo-draftdraft-to-videogenerate-imagegenerate-audioclone-voicegenerate-videoprocess-video
quote_idstring可选
至少 1 个字符
routingobject可选

指定规格。不传时由平台选择该模型已发布的规格。

routing 的字段
routing 的字段
modestring必填
pinned
routestring必填
至少 1 个字符
webhook_endpoint_idstring可选

任务状态变化时通知的 Webhook 端点,在控制台创建。

响应

202 Accepted

202 Accepted
字段说明
allowed_actionsstring[], 可为 null必填

当前可以执行的操作,例如 cancel。以这个列表为准,不要根据状态自行推断。

billing_statusstring必填

Credits 是冻结、已扣费还是已释放。

closed_atdate-time, 可为 null必填

任务关闭时间。不为空即可停止轮询。

customer_resolution_deadlinedate-time必填

受理后 24 小时。到期仍未结算的冻结额度全部释放。

delivery_statusstring必填

结果是否已保存、可下载。ready 表示可以下载。

errorobject, 可为 null必填

任务未产出结果就关闭时才有值,读取 error.code。

error 的字段
error 的字段
codestring必填

任务未产出结果就关闭的原因,例如 insufficient_balance、budget_exceeded 或 spending_blocked。

execution_statusstring必填

模型生成进度。

idstring必填

资源 ID,收到后立即保存。

late_result_availableboolean必填

关闭后才到的结果,免费提供。

metadatamap<string, string>可选

你自己的字符串键值,原样返回。建议写入 client_reference,回包丢失时用它找回任务。

priceobject必填

这个任务的 Credits:quoted 是受理时的价格,reserved 是冻结额度,charged 是实际扣费。结算前 charged 为 0.000。

price 的字段
price 的字段
chargedstring必填
price_versionstring必填
quotedstring必填
reservedstring必填
unitstring必填
credit
resultobject, 可为 null必填

交付后的素材。

result 的字段
result 的字段
asset_idstring可选
last_frame_asset_idstring可选
metadataobject可选
metadata 的字段
metadata 的字段
durationinteger可选
framesinteger可选
framespersecondinteger可选
generate_audioboolean可选
ratiostring可选
resolutionstring可选
seedinteger可选
outputsobject[], 可为 null可选
outputs 的字段
outputs 的字段
asset_idstring必填
content_typestring必填
indexinteger必填
voice_idstring可选
statusstring必填

任务的总体状态。

versioninteger必填

错误

所有错误使用同一种响应体。联系支持时请附上 request_id。

错误响应体

错误响应体
字段说明
errorobject必填

错误详情。

error 的字段
error 的字段
codestring必填

稳定的错误码,用它判断分支。

messagestring必填

可读的说明,不要解析它。

request_idstring必填

联系支持时请附上。

retryableboolean必填

仅 429 和 503 为 true。即便如此,重发创建请求前也要先查看近期任务。

task_idstring可选

错误所属的任务(如果有)。

错误
状态码含义与处理
401

Key 缺失、格式错误、已过期或已撤销。在服务端更正 Key 后继续。

402

可用 Credits 不足以支付这次请求。充值并等待到账后,再查询余额。

403

Key 权限、邮箱验证、预算上限或账户限制阻止了操作。检查 Key 类型、权限和项目预算。

404

模型或资源不存在,或不在当前项目范围内。确认项目、ID 和模型是否已开通。

409

请求与当前状态冲突。重新读取资源,再决定是否重新发送。

422

字段或取值无效。对照字段表和模型页修改请求。

429

请求过于频繁,没有创建任务。等到 Retry-After 指定的时间后再发送。

500

服务端出错,任务可能已经受理。不要直接重发,先查看近期任务。

503

服务暂时不可用。创建请求要先查看近期任务,确认没有受理,再重新提交。

超时或断连

没有响应或连接中断,任务可能已经受理。有任务 ID 就查询原任务;没有就按 client_reference 在任务列表中找回。

请求示例

cURL
curl -X POST "https://api.vizoapi.com/v1/generations" \
  -H "Authorization: Bearer $VIZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_FROM_PROJECT",
    "operation": "text-to-video",
    "input": {
      "prompt": "A paper boat drifting on a pond",
      "duration_seconds": 5
    }
  }'
Python
import os, requests

res = requests.post(
    "https://api.vizoapi.com/v1/generations",
    headers={"Authorization": f"Bearer {os.environ['VIZO_API_KEY']}"},
    json={
      "model": "MODEL_FROM_PROJECT",
      "operation": "text-to-video",
      "input": {
        "prompt": "A paper boat drifting on a pond",
        "duration_seconds": 5
      }
    },
    timeout=60,
)
print(res.status_code, res.json())
Node.js
const res = await fetch("https://api.vizoapi.com/v1/generations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VIZO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "MODEL_FROM_PROJECT",
    "operation": "text-to-video",
    "input": {
      "prompt": "A paper boat drifting on a pond",
      "duration_seconds": 5
    }
  }),
});
console.log(res.status, await res.json());
响应 202
{
  "allowed_actions": [
    "cancel"
  ],
  "billing_status": "held",
  "closed_at": null,
  "customer_resolution_deadline": "2026-11-03T08:00:12Z",
  "delivery_status": "pending",
  "error": null,
  "execution_status": "queued",
  "id": "gen_01JD8Z5QW3XR",
  "late_result_available": false,
  "metadata": {
    "client_reference": "order-1042"
  },
  "price": {
    "charged": "0.000",
    "price_version": "p3",
    "quoted": "1400.000",
    "reserved": "1400.000",
    "unit": "credit"
  },
  "result": null,
  "status": "queued",
  "version": 1
}
响应 401
{
  "error": {
    "code": "invalid_credentials",
    "message": "API key is missing, malformed, expired or revoked.",
    "retryable": false,
    "request_id": "9f2c41d07ab3e5c8"
  }
}
响应 402
{
  "error": {
    "code": "insufficient_balance",
    "message": "Available credits cannot cover the hold.",
    "retryable": false,
    "request_id": "9f2c41d07ab3e5c8"
  }
}
响应 403
{
  "error": {
    "code": "scope_denied",
    "message": "The key does not allow this operation for this project.",
    "retryable": false,
    "request_id": "9f2c41d07ab3e5c8"
  }
}
响应 404
{
  "error": {
    "code": "resource_not_found",
    "message": "The resource is not available to this project.",
    "retryable": false,
    "request_id": "9f2c41d07ab3e5c8"
  }
}
响应 409
{
  "error": {
    "code": "conflict",
    "message": "The request conflicts with the current state of the resource.",
    "retryable": false,
    "request_id": "9f2c41d07ab3e5c8"
  }
}
响应 422
{
  "error": {
    "code": "invalid_input",
    "message": "Input does not match the published schema.",
    "retryable": false,
    "request_id": "9f2c41d07ab3e5c8"
  }
}
响应 429
{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Check Retry-After.",
    "retryable": true,
    "request_id": "9f2c41d07ab3e5c8"
  }
}
响应 500
{
  "error": {
    "code": "request_failed",
    "message": "The request failed. Check recent generations before submitting again.",
    "retryable": false,
    "request_id": "9f2c41d07ab3e5c8"
  }
}
响应 503
{
  "error": {
    "code": "temporarily_unavailable",
    "message": "Service is temporarily unavailable.",
    "retryable": true,
    "request_id": "9f2c41d07ab3e5c8"
  }
}