API 参考 / 媒体素材

申请下载素材

downloadAsset

GET/v1/assets/{id}/download

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

鉴权

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

路径参数

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

响应

200 OK

200 OK
字段	说明
urlstring必填	短期有效的链接。请单独请求它，不要附带 API Key。
url_expires_atdate-time必填	链接失效时间。过期后对同一素材重新申请。

错误

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

错误响应体

字段

说明

errorobject必填

错误详情。

error 的字段

error 的字段
codestring必填	稳定的错误码，用它判断分支。
messagestring必填	可读的说明，不要解析它。
request_idstring必填	联系支持时请附上。
retryableboolean必填	仅 429 和 503 为 true。即便如此，重发创建请求前也要先查看近期任务。
task_idstring可选	错误所属的任务（如果有）。

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

请求示例

cURL

curl "https://api.vizoapi.com/v1/assets/$ASSET_ID/download" \
  -H "Authorization: Bearer $VIZO_API_KEY"

Python

import os, requests

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

Node.js

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

响应 200

{
  "url": "https://media.vizoapi.com/d/ast_01JD8Z9M2C4V?sig=…",
  "url_expires_at": "2026-11-02T08:16:43Z"
}

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

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