图片生成、编辑与异步任务

QuotaAPI 提供同步图片、异步单图任务和批量图片三种工作流。生产环境应根据任务数量和预计耗时选择接口，而不是在客户端超时后立即重复提交。

能力与平台

工作流	主要接口	可用分组	适用场景
同步生成与编辑	/v1/images/generations、/v1/images/edits	OpenAI、Grok	单张图片、交互式等待
异步生成与编辑	/v1/images/generations/async、/v1/images/edits/async	OpenAI、Grok	单张长耗时任务、可靠轮询
批量图片	/v1/images/batches	Gemini	多提示词、批量下载和任务管理

API Key 必须绑定到支持目标接口的分组，且管理员需要为该分组开启图片生成功能。模型名称和具体参数仍受目标平台、账号与后台配置约束。

同步图片生成

curl https://quotarouter.ai/v1/images/generations \
  -H "Authorization: Bearer YOUR_QUOTAAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A quiet product studio with soft daylight.",
    "size": "1024x1024",
    "response_format": "b64_json"
  }'

单图客户端的请求超时应设为至少 120 秒。连接在 120 秒前断开不代表任务一定失败，也不要因此自动重复扣费请求；对耗时不确定的任务，优先使用异步接口。

同步图片编辑

本地文件使用 multipart 上传：

curl https://quotarouter.ai/v1/images/edits \
  -H "Authorization: Bearer YOUR_QUOTAAPI_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=Keep the subject and replace the background with a studio." \
  -F "image=@input.png" \
  -F "size=1024x1024" \
  -F "response_format=b64_json"

目标平台支持时，也可以使用 JSON 中的图片 URL。不要把短期签名 URL 写入可长期重试的任务。

异步单图任务

异步接口接受与对应同步接口相同的请求体，但不支持流式图片请求。提交生成任务：

curl -i https://quotarouter.ai/v1/images/generations/async \
  -H "Authorization: Bearer YOUR_QUOTAAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A precise isometric data center illustration.",
    "size": "1024x1024",
    "response_format": "b64_json"
  }'

编辑任务使用 /v1/images/edits/async。成功提交返回 202 Accepted，响应头包含 Location 和 Retry-After: 3，响应体包含 task_id、status、poll_url、created_at 与 expires_at。

{
  "task_id": "imgtask_EXAMPLE",
  "status": "processing",
  "poll_url": "/v1/images/tasks/imgtask_EXAMPLE",
  "created_at": 1785984000,
  "expires_at": 1786070400
}

使用提交时的同一个 API Key 查询：

参数化查询路径是 GET /v1/images/tasks/{task_id}。

curl https://quotarouter.ai/v1/images/tasks/imgtask_EXAMPLE \
  -H "Authorization: Bearer YOUR_QUOTAAPI_KEY"

任务状态为：

状态	含义	客户端动作
processing	仍在生成	按 Retry-After 等待，默认约 3 秒后重试
completed	已完成	从 result 或受保护的 image_url 读取结果
failed	已失败	读取 http_status 和 error，不要无限重试

异步任务最长执行 30 分钟，记录和结果默认保留 24 小时。结果会存入系统配置的私有对象存储，并通过需要认证的 /media/... 地址提供；请在到期前下载。任务归属同时绑定用户和 API Key，其他 Key 即使属于同一用户也不能查询。

WARNING

客户端超时后先使用已有 task_id 继续轮询。只有明确收到失败状态且错误属于可重试类型时，才创建新任务。

批量图片

批量入口适合大量提示词和统一下载。先查询当前 Key 可用模型：

curl https://quotarouter.ai/v1/images/batches/models \
  -H "Authorization: Bearer YOUR_QUOTAAPI_KEY"

提交时建议始终发送唯一的 Idempotency-Key，防止网络重试重复创建任务：

curl https://quotarouter.ai/v1/images/batches \
  -H "Authorization: Bearer YOUR_QUOTAAPI_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: product-catalog-20260806-01" \
  -d '{
    "task_name": "Product catalog",
    "model": "gemini-2.5-flash-image",
    "aspect_ratio": "1:1",
    "image_size": "1K",
    "items": [
      {
        "custom_id": "cover-001",
        "prompt": "A clean white product background.",
        "output_count": 1
      }
    ]
  }'

批量接口还提供列表、详情、条目、单图下载、ZIP 下载、取消和清理能力。控制台操作流程见后续的批量图片页面；API 路由以 /v1/images/batches 为根路径。

常见错误

状态码	常见原因
400	请求参数、文件格式、模型或流式参数不合法
401	API Key 无效
403	分组未开启图片生成，或没有目标能力
404	平台不支持该接口、异步任务未启用或任务不存在
429	用户、账号或图片并发受限
503	暂无可用账号或任务存储暂不可用

接口支持范围应以平台与端点兼容矩阵和控制台当前模型列表为准。