估算生成费用

createEstimate

POST/v1/estimates

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

Prices a create body without creating a generation or holding Credits. The body is the same as createGeneration; webhook_endpoint_id and metadata are accepted and ignored. The input and its media are checked and priced exactly as a create would, including measuring a public input video, so a body the estimate refuses gets the same input error from createGeneration. A create can still fail where an estimate succeeds: on funding or budget (402, 403), on the rate and concurrency limits (429) or on a route change (409). An estimate that must measure an input video takes one token from the organization's generation rate limit and answers 429 rate_limited with Retry-After when none is left; other estimates take one token from the organization's generation read limit and answer 429 rate_limited with Retry-After when none is left. Prices can change between an estimate and a create.

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

鉴权

在请求头带上项目 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 端点，在控制台创建。

响应

200 OK

字段说明

basisobject必填

basis 的字段

basis 的字段
autoboolean必填	The model chooses the length (for example duration -1 or an inferred video task), so the hold covers the longest output the tier allows or, for an edit whose source was measured, the source length (capped by the tier).
billed_secondsinteger必填	Per-second models only: seconds billed after the tier's minimum billing rule. 0 on per-image models.
input_imagesinteger必填	Per-image models only: input images counted for the price. Always 0 on per-second (video) models, whatever images the input has.
input_secondsinteger必填	Per-second models only: input video seconds priced, on a tier that bills input video. 0 otherwise.
largeboolean必填	Per-image models only: the large-image surcharge applies. Always false on per-second models.
output_secondsinteger必填	Per-second models only: output seconds priced. 0 on per-image models.
outputsinteger必填	Per-image models only: output images priced. Always 0 on per-second (video) models.

estimateobject必填

estimate 的字段

creditsstring必填

The Credits a create with the same body would hold.

usdobject必填

usd 的字段

usd 的字段
amountstring可选	格式`^(0\|[1-9][0-9]*)([.][0-9]+)?$`
as_ofdate-time可选
basisstring可选	`current_standard_pack`
statusstring必填	Available when a current USD reference pack supplies the estimate; unavailable when no valid reference exists. This is a display estimate, not the charge. `availableunavailable`
tax_includedboolean必填	`false`

错误

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

错误响应体

字段说明

errorobject必填

错误详情。

error 的字段

codestring必填

Stable request error code. invalid_input rejects the request schema; invalid_credentials/scope_denied reject authentication/authorization; ip_not_allowed/model_not_allowed reject API key IP/model restrictions; resource_not_found hides missing or inaccessible resources; conflict rejects incompatible state; insufficient_balance/budget_exceeded/spending_blocked reject funding; balance_negative (402) refuses new tasks while the organization owes Credits from a charge above its hold, until a top-up repays them; rate_limited/concurrency_limited ask for a later retry; temporarily_unavailable is transient service capacity; request_failed covers other HTTP failures. tier_not_sold, draft_not_found, draft_expired and input_duration_out_of_range reject model-specific input. input_media_invalid rejects a detected format/type mismatch; input_media_too_large rejects a probed byte size above the model limit. storage_quota_exceeded rejects an upload when the organization's storage is full. See errors for field-level details.

invalid_inputinvalid_credentialsinsufficient_balancebalance_negativescope_deniedresource_not_foundconflictrate_limitedconcurrency_limitedtemporarily_unavailablerequest_failedip_not_allowedmodel_not_allowedtier_not_solddraft_not_founddraft_expiredinput_duration_out_of_rangeinput_media_invalidinput_media_too_largebudget_exceededspending_blockedstorage_quota_exceeded

errorsobject[], 可为 null可选

errors 的字段

errors 的字段
pathstring必填
rulestring必填

messagestring必填

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

request_idstring必填

联系支持时请附上。

retryableboolean必填

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

task_idstring可选

错误所属的任务（如果有）。

错误
状态码	含义与处理
401	API Key 缺失、格式错误、已过期或已撤销。在服务端更正 API Key 后继续。
403	API Key 权限、邮箱验证、预算上限或账户限制阻止了操作。检查 API Key 类型、权限和项目预算。
404	模型或资源不存在，或不在当前项目范围内。确认项目、ID 和模型是否已开通。
422	字段或取值无效。对照字段表和模型页修改请求。
429	请求过于频繁，没有创建任务。等到 Retry-After 指定的时间后再发送。
500	服务端出错，任务可能已经受理。不要直接重发，先查看近期任务。
503	服务暂时不可用。创建请求要先查看近期任务，确认没有受理，再重新提交。

请求示例

cURL

curl -X POST "https://api.vizoapi.com/v1/estimates" \
  -H "Authorization: Bearer $VIZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {},
    "model": "MODEL_ID"
  }'

Python

import os, requests

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

Node.js

const res = await fetch("https://api.vizoapi.com/v1/estimates", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VIZO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "input": {},
    "model": "MODEL_ID"
  }),
});
console.log(res.status, await res.json());

响应 200

{
  "basis": {
    "auto": false,
    "billed_seconds": 1,
    "input_images": 1,
    "input_seconds": 1,
    "large": false,
    "output_seconds": 1,
    "outputs": 1
  },
  "estimate": {
    "credits": "157.000",
    "usd": {
      "amount": "string",
      "as_of": "2026-11-02T08:00:00Z",
      "basis": "current_standard_pack",
      "status": "available",
      "tax_included": false
    }
  }
}

响应 401

{
  "error": {
    "code": "invalid_credentials",
    "message": "API key is missing, malformed, expired or revoked.",
    "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"
  }
}

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