异步生图 API

提交后立即返回任务编号。生成在后台执行，稍后查询状态并领取结果。所有接口均使用本站 API 令牌。

1. 提交文生图

curl https://www.myvigna.top/v1/images/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: your-unique-request-001" \
  -d '{"model":"seedream-5.0-pro","prompt":"一只红色陶瓷茶杯，白色桌面，柔和日光","n":1,"size":"1024x1024","response_format":"url","output_format":"png"}'

也支持 gpt-image-2 等通过本站 Images API 提供的模型；可用模型与参数沿用对应同步接口。每个任务限 1 张图片。

HTTP 202
{
  "object": "image.task",
  "task_id": "imgtask_…",
  "status": "queued",
  "poll_url": "/v1/images/tasks/imgtask_…",
  "result_url": "/v1/images/tasks/imgtask_…/result",
  "poll_after_ms": 2000
}

2. 查询状态

curl https://www.myvigna.top/v1/images/tasks/TASK_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

status	含义
queued / running	等待 / 正在生成；按 poll_after_ms 间隔查询。
success	结果可领取。
failed	任务失败；查看 error.message。
uncertain	传输或服务中断，结果尚未确认；停止轮询，核对使用日志，避免重复生成与计费。

3. 领取结果

curl https://www.myvigna.top/v1/images/tasks/TASK_ID/result \
  -H "Authorization: Bearer YOUR_API_KEY"

成功时 HTTP 200 返回原 Images API 的 data[].url 或 data[].b64_json、usage 等字段。图片链接交给调用方直接下载；服务器不额外下载、压缩或转码。未完成时返回 HTTP 202；失败或结果未确认时返回 HTTP 409。

参考图生成

使用 POST /v1/images/tasks/edits，请求格式与同步 /v1/images/edits 相同。GPT 支持 multipart 图片文件；Seedream 使用 JSON 的 images 数组。

curl https://www.myvigna.top/v1/images/tasks/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: your-unique-edit-001" \
  -F "model=gpt-image-2" -F "prompt=把杯子改成蓝色" \
  -F "image=@reference.png" -F "n=1"

使用说明

查询最近任务：GET /v1/images/tasks?limit=20，最多 100 条，仍需相同令牌。
推荐每次新生成提供唯一 Idempotency-Key。同一次请求网络重试须复用此值和相同参数；服务会返回原任务，不会再次生成。参数冲突返回 409。
结果、失败状态保留 24 小时；请及时保存到用户电脑。上游链接可能更早到期，应尽快下载。过期后同一幂等编号额外保留 7 天以阻止重复提交；此后不能继续用旧编号重试。
请求最大 20 MB，结果最大 64 MB。每令牌最多 20 个等待或执行中的任务，全站最多 100 个；实际执行按服务器与上游能力排队。429 按 Retry-After 重试，507 表示存储不足且本次未提交。
排队和生成共用最长 30 分钟时间预算，上游与网关也有各自限制。任务状态查询不包含大图数据，建议 2 秒查询一次，遇到 429/503 退避。
提交只做令牌校验，模型权限、余额与计费在实际执行时由原网关处理。查询和领取不会再次发起生成。
关闭客户端不影响正在执行的任务。服务重启后，排队任务在使用相同令牌再次查询时恢复；执行中断且未收到完整结果的任务标记 uncertain，不自动重试。
异步功能使用本文的独立任务地址。已有同步生图接口继续按原方式使用。异步任务不支持 stream=true。

返回生图工作台 · API 使用指南