API 参考 / 生成任务

取消生成任务

cancelGeneration

POST/v1/generations/{id}/cancel

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

鉴权

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

路径参数

路径参数
字段	说明
idstring必填	资源 ID，收到后立即保存。

响应

200 OK

字段说明

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 的字段

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	字段或取值无效。对照字段表和模型页修改请求。
500	服务端出错，任务可能已经受理。不要直接重发，先查看近期任务。
503	服务暂时不可用。创建请求要先查看近期任务，确认没有受理，再重新提交。

请求示例

cURL

curl -X POST "https://api.vizoapi.com/v1/generations/$GENERATION_ID/cancel" \
  -H "Authorization: Bearer $VIZO_API_KEY"

Python

import os, requests

generation_id = "…"
res = requests.post(
    f"https://api.vizoapi.com/v1/generations/{generation_id}/cancel",
    headers={"Authorization": f"Bearer {os.environ['VIZO_API_KEY']}"},
    timeout=60,
)
print(res.status_code, res.json())

Node.js

const generation_id = "…";
const res = await fetch(`https://api.vizoapi.com/v1/generations/${generation_id}/cancel`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VIZO_API_KEY}`,
  },
});
console.log(res.status, await res.json());

响应 200

{
  "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"
  }
}

响应 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"
  }
}