创建生成任务
下面的接口说明为英文原文。
Each accepted POST durably records a separate generation. The response has status processing and billing_status pending; the reserved amount is zero until Credits are held. A funding rejection closes the task with error.code set; read it again to see it. Submitting the same request twice can incur two charges. After a lost response, check the generation list before deciding to create another task. HTTP 429 with code concurrency_limited means the organization already has as many unfinished tasks of this media type (video, image, audio or other) as its concurrency limit allows (by default 3 video, 10 image and 10 audio tasks at once per organization; see /docs/rate-limits); nothing is recorded or held, so retry after the Retry-After seconds or queue on your side. Other 429 answers use rate_limited.
鉴权
在请求头带上项目 API Key,例如 Authorization: Bearer $VIZO_API_KEY。API Key 只放在服务端。
请求体
JSON 对象,不接受未列出的字段。
| 字段 | 说明 |
|---|---|
| inputobject必填 | The model input. Its schema is the model's inputSchema in the catalog. |
| metadatamap<string, string>可选 | 你自己的字符串键值,原样返回。建议写入 client_reference,回包丢失时用它找回任务。 |
| modelstring必填 | 模型 ID,来自 listModels 或模型页。 至少 1 个字符 |
| webhook_endpoint_idstring可选 | 任务状态变化时通知的 Webhook 端点,在控制台创建。 |
响应
202 Accepted
| 字段 | 说明 | ||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| allowed_actionsstring[], 可为 null必填 | 当前可以执行的操作,例如 cancel。以这个列表为准,不要根据状态自行推断。 | ||||||||||||||||||||||||||||||
| billing_closed_atdate-time可选 | When the hold was settled or released; absent while Credits are still held. | ||||||||||||||||||||||||||||||
| billing_statusstring必填 | Pending awaits funding; unfunded closed without a hold; held means Credits are held for the task; settled charges verified delivery at the existing pricing rules; released returns the hold after failure, cancellation, timeout or zero-charge delivery; refunded reverses previously consumed generation Credits. pendingunfundedheldsettledreleasedrefunded | ||||||||||||||||||||||||||||||
| closed_atdate-time, 可为 null必填 | 任务关闭时间。不为空即可停止轮询。 | ||||||||||||||||||||||||||||||
| created_atdate-time必填 | When the generation was accepted. Lists are ordered by this time, newest first. | ||||||||||||||||||||||||||||||
| customer_resolution_deadlinedate-time必填 | 受理后 24 小时。到期仍未结算的冻结积分全部释放。 | ||||||||||||||||||||||||||||||
| delivery_statusstring必填 | Output delivery: pending before upstream success; copying into managed storage; ready after verified delivery; failed when delivery cannot complete. pendingcopyingreadyfailed | ||||||||||||||||||||||||||||||
| errorobject, 可为 null必填 | 任务未产出结果就关闭时才有值,读取 error.code。 error 的字段
| ||||||||||||||||||||||||||||||
| execution_statusstring必填 | Supplier execution state, separate from delivery and billing: processing until execution ends. Succeeded means upstream execution finished, not that output delivery is ready. processingsucceededfailedcanceledunresolved | ||||||||||||||||||||||||||||||
| held_atdate-time可选 | When Credits were held for the task; absent while it awaits funding or when it closed unfunded. | ||||||||||||||||||||||||||||||
| idstring必填 | 资源 ID,收到后立即保存。 | ||||||||||||||||||||||||||||||
| inputany可选 | The model input as accepted, after normalization, with media as sent: asset ids or your own URLs. Returned when reading a single task; list entries omit it. | ||||||||||||||||||||||||||||||
| key_idstring可选 | API key that created the task; empty for console tasks. | ||||||||||||||||||||||||||||||
| key_namestring可选 | |||||||||||||||||||||||||||||||
| late_result_availableboolean必填 | 关闭后才到的结果,免费提供。 | ||||||||||||||||||||||||||||||
| metadatamap<string, string>可选 | 你自己的字符串键值,原样返回。建议写入 client_reference,回包丢失时用它找回任务。 | ||||||||||||||||||||||||||||||
| modelstring必填 | Public model id the generation was created with. | ||||||||||||||||||||||||||||||
| priceobject必填 | 这个任务的积分:estimated 是预估额,也就是冻结额,实际扣费按实际用量计算,可能与预估略有差异;reserved 是当前冻结的积分;charged 是按实际用量和固定费率扣的积分,结算前为 0.000;refunded 是退款退回的积分。 price 的字段
| ||||||||||||||||||||||||||||||
| queue_msinteger可选 | Milliseconds from acceptance to first dispatch. | ||||||||||||||||||||||||||||||
| resultobject, 可为 null必填 | 交付后的素材。 result 的字段
| ||||||||||||||||||||||||||||||
| run_msinteger可选 | Milliseconds from first dispatch to close. | ||||||||||||||||||||||||||||||
| sourcestring必填 | Where the generation was created: api (API key) or console (signed-in session). apiconsole | ||||||||||||||||||||||||||||||
| started_atdate-time可选 | When the task was first dispatched to run. | ||||||||||||||||||||||||||||||
| statusstring必填 | processing from acceptance until the task closes, including while it awaits funding and while outputs are copied; succeeded has delivered outputs; failed, canceled and unresolved are closed. Canceled is set by the system only, for example when a task is not funded or not started in time. Unresolved closes after the resolution deadline. A late result may still arrive without a new charge. processingsucceededfailedcanceledunresolved | ||||||||||||||||||||||||||||||
| versioninteger必填 |
错误
所有错误使用同一种响应体。联系支持时请附上 request_id。
错误响应体
| 字段 | 说明 | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| errorobject必填 | 错误详情。 error 的字段
|
| 状态码 | 含义与处理 |
|---|---|
| 401 | API Key 缺失、格式错误、已过期或已撤销。在服务端更正 API Key 后继续。 |
| 402 | 可用积分不足以支付这次请求。充值并等待到账后,再查询余额。 |
| 403 | API Key 权限、邮箱验证、预算上限或账户限制阻止了操作。检查 API 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": "seedance-2-5",
"input": {
"content": [
{
"type": "text",
"text": "A paper boat drifting on a pond"
}
],
"resolution": "720p",
"duration": 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": "seedance-2-5",
"input": {
"content": [
{
"type": "text",
"text": "A paper boat drifting on a pond"
}
],
"resolution": "720p",
"duration": 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": "seedance-2-5",
"input": {
"content": [
{
"type": "text",
"text": "A paper boat drifting on a pond"
}
],
"resolution": "720p",
"duration": 5
}
}),
});
console.log(res.status, await res.json());响应 202
{
"allowed_actions": [],
"billing_closed_at": "2026-11-02T08:00:00Z",
"billing_status": "held",
"closed_at": null,
"created_at": "2026-11-02T08:01:43Z",
"customer_resolution_deadline": "2026-11-03T08:00:12Z",
"delivery_status": "pending",
"error": null,
"execution_status": "processing",
"held_at": "2026-11-02T08:00:00Z",
"id": "gen_01JD8Z5QW3XR",
"input": {},
"key_id": "string",
"key_name": "string",
"late_result_available": false,
"metadata": {
"client_reference": "order-1042"
},
"model": "MODEL_ID",
"price": {
"charged": "0.000",
"estimated": "157.000",
"refunded": "0.000",
"reserved": "157.000",
"unit": "credit"
},
"queue_ms": 1,
"result": null,
"run_ms": 1,
"source": "api",
"started_at": "2026-11-02T08:00:00Z",
"status": "processing",
"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"
}
}