异步生成图片

什么是异步生成

对于耗时的图片生成请求,平台支持异步生成模式:提交请求后立即返回任务 ID,客户端通过轮询获取最终结果,不必保持长连接等待。

异步模式适合生成时间较长的场景,能避免请求超时中断,也便于批量提交多个任务。

使用流程

异步生成分为三步:提交任务 → 轮询状态 → 获取结果。

1. 提交任务

向 https://api.tvtapi.com/v1/images/async 发送 POST 请求,携带 API Key(Bearer 认证)和请求参数:

curl -X POST https://api.tvtapi.com/v1/images/async \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{"model":"模型名称","prompt":"描述文本"}'

返回值中包含 task_id,这是后续查询和下载的唯一凭证。

2. 轮询任务状态

用 task_id 轮询任务状态:

curl https://api.tvtapi.com/v1/images/async/{task_id} \
  -H "Authorization: Bearer sk-你的密钥"

任务状态包括:queued(排队中)、in_progress(生成中)、succeeded(成功)、failed(失败)。建议每隔数秒轮询一次,直到状态变为 succeeded 或 failed。

3. 下载图片

任务成功后,通过以下地址获取图片:

curl -L https://api.tvtapi.com/v1/images/async/{task_id}/content \
  -H "Authorization: Bearer sk-你的密钥"

该端点会返回 302 重定向到图片的实际存储地址。每张图片有下载次数限制,超时后任务会自动过期。

也可在网页端使用

如果不想写代码,可以直接在 /zh-cn/user/image-studio 中使用图片工作台。工作台内置异步模式开关,切换后在页面内自动轮询并展示结果,无需手动调用 API。

注意事项

  • 异步功能需要管理员在后台开启,且用户账户需启用对应权限
  • 任务有有效期,过期后无法下载
  • 如长时间停留在 in_progress,系统会自动超时标记为 failed