创建生成任务
下面的接口说明为英文原文。
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.
鉴权
在请求头带上项目 Key,例如 Authorization: Bearer $VIZO_API_KEY。Key 只放在服务端。
请求体
JSON 对象,不接受未列出的字段。
| 字段 | 说明 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| inputobject必填 | 生成参数。具体字段取决于模型和操作,见各模型页。 input 的字段
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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 的字段
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| webhook_endpoint_idstring可选 | 任务状态变化时通知的 Webhook 端点,在控制台创建。 |
响应
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 的字段
| ||||||||||||||||||||||||||||||
| execution_statusstring必填 | 模型生成进度。 | ||||||||||||||||||||||||||||||
| idstring必填 | 资源 ID,收到后立即保存。 | ||||||||||||||||||||||||||||||
| late_result_availableboolean必填 | 关闭后才到的结果,免费提供。 | ||||||||||||||||||||||||||||||
| metadatamap<string, string>可选 | 你自己的字符串键值,原样返回。建议写入 client_reference,回包丢失时用它找回任务。 | ||||||||||||||||||||||||||||||
| priceobject必填 | 这个任务的 Credits:quoted 是受理时的价格,reserved 是冻结额度,charged 是实际扣费。结算前 charged 为 0.000。 price 的字段
| ||||||||||||||||||||||||||||||
| resultobject, 可为 null必填 | 交付后的素材。 result 的字段
| ||||||||||||||||||||||||||||||
| statusstring必填 | 任务的总体状态。 | ||||||||||||||||||||||||||||||
| versioninteger必填 |
错误
所有错误使用同一种响应体。联系支持时请附上 request_id。
错误响应体
| 字段 | 说明 | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| errorobject必填 | 错误详情。 error 的字段
|
| 状态码 | 含义与处理 |
|---|---|
| 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"
}
}