图像生成任务

接口概览

图像任务使用统一异步流程：

1. 调用 POST /v1/images/tasks 提交任务
2. 保存响应中的 task_id
3. 调用 GET /v1/tasks/{task_id} 查询状态和结果

Base URL 为 https://api.rokoapi.com/v1。所有请求都要携带 Authorization: Bearer $API_KEY。

提交响应在兼容期同时返回 id 和 task_id，两者值相同。新代码应读取 task_id；原来读取 id 的代码无需修改。

Seedream 结果永久保存

Seedream 系列（包括 seedream-* 与 doubao-seedream-*）生成的图片会自动转存到 RokoAPI 自有 R2 存储，交付的链接使用我们的媒体域名。

• 结果图片在 RokoAPI 自有 R2 中永久保存，不自动过期或清理，可随时访问返回的链接。
• 异步接口在全部图片转存成功前保持 state: "in_progress"，不返回第三方结果地址。完成后从 assets[].url 或 data.results[] 获取全部图片，result_url 为第一张图片。
• expires_at 为 0 或省略，表示没有自动到期时间。

如果使用模型支持的同步 POST /v1/images/generations，接口会等待图片转存完成，随后通过标准 data[].url 返回 R2 地址，并附带 task_id 和 expires_at。Seedream 结果转存要求非流式 URL 响应：省略或设置 stream: false，省略或设置 response_format: "url"；stream: true 和 response_format: "b64_json" 会在请求阶段被拒绝。

生成成功后的转存失败不会重新生成图片，也不会重复收取生成费用。同步请求可能返回 HTTP 502、result_archive_failed 和恢复用的 task_id，此时仍按已完成的生成计费；请轮询 GET /v1/tasks/{task_id} 等待后台重试，不要重复提交生成请求。没有 task_id 或后台重试最终失败时，请联系支持并提供请求 ID。

创建任务

curl https://api.rokoapi.com/v1/images/tasks \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "a calm lake at dawn, photorealistic",
    "size": "1:1",
    "quality": "1K"
  }'

常用字段：

模型可能限制 n、参考图数量、分辨率和尺寸格式。提交前应以对应模型开发页和 /v1/models 返回为准。

GPT Image 2 / 2.5 分辨率

gpt-image-2 和 gpt-image-2.5 均提供 resolution: "1K" | "2K" | "4K"，默认 1K。用 size 选择画幅比例，分辨率与 quality 是两个独立参数。

{
  "model": "gpt-image-2.5",
  "prompt": "a quiet coastal village at sunrise",
  "size": "16:9",
  "resolution": "4K",
  "n": 1
}

也可以将示例的 model 改为 gpt-image-2。网关将档位和画幅转换为渠道支持的尺寸：例如 4K 横图为 3840x2160，4K 方图为 2880x2880，并非所有画幅都是 4096 像素宽。选择分辨率时，size: "auto" 按方图预设处理；直接指定 WIDTHxHEIGHT 时以像素尺寸为准。实际可用性仍取决于对应档位的渠道状态。

Grok Imagine Image 2.0

grok-imagine-image-2.0 使用同一个模型 ID 完成文生图和图像编辑：不传 image_urls 时为文生图，传入 1–3 张公网图片时为参考图编辑。仅支持公网 HTTP / HTTPS 图片 URL，不支持 Base64 或 Data URL。

{
  "model": "grok-imagine-image-2.0",
  "prompt": "Place <IMAGE_0> in a premium product studio",
  "image_urls": ["https://example.com/product.webp"],
  "size": "16:9",
  "resolution": "2K",
  "quality": "medium",
  "n": 1
}

• size：auto 或 13 种预设比例；不接受 1024x1024 等自定义像素尺寸。
• resolution：1K、2K，默认 1K。
• quality：low、medium，默认 medium。
• n：1–10，默认 1；输出价格按生成张数相乘。
• callback_url：可选，必须为最长 2048 字符的公网 HTTPS 地址。

RokoAPI 售价为 EvoLink 成本价加 10% 服务费：1K Low $0.033 /张，1K Medium $0.0495 /张，2K Low $0.0495 /张，2K Medium $0.066 /张；每张输入图片另收 $0.00825 /请求，输入图费用不会随 n 重复计算。最终价格以模型定价和任务结算记录为准。

Midjourney 统一模型

旧的 Midjourney v7 和 Midjourney v8.1 已停止开放，新请求统一使用 midjourney。常规生成示例：

{
  "model": "midjourney",
  "prompt": "a futuristic city at dusk",
  "mode": "fast",
  "quality": "standard"
}

mode 仅支持 fast 和 turbo，不传时默认为 fast。quality: "hd" 会转换为上游 Midjourney 的 --hd 生成参数。其他能力通过 generation_type 选择：blend、describe、seed、inpaint，以及 variation1、upsample1、reroll、upscale2、upscale4 等操作。依赖已有任务的操作需在 metadata.job_id 中传入上一步的上游任务 ID；局部重绘还需提供 metadata.mask。图片混合要求在 images 中传 2–5 个 Base64 Data URL。

幂等提交

Idempotency-Key 是可选请求头，但生产环境强烈建议使用。它只影响统一异步任务端点，不改变未携带该请求头的现有调用。

• Key 最长 128 个字符，同一个 API Token 下必须唯一。
• 幂等记录保留 7 天；超过保留期的业务操作应使用新的 Key。
• 相同 Key 和相同请求重复提交时，RokoAPI 返回第一次请求的响应，不会再次创建上游任务。
• 重放响应带有 Idempotency-Replayed: true。
• 第一次请求仍在处理时，重复请求返回 HTTP 409、idempotency_request_in_progress 和 Retry-After: 2，响应数据包含已预留的 task_id。
• 相同 Key 用于不同请求时返回 HTTP 409 idempotency_key_reused。
• 兼容旧客户端，也接受 X-Idempotency-Key；新接入统一使用 Idempotency-Key。

客户端遇到连接超时后，应使用相同 Key 重试，不能换新 Key 重新提交。

查询任务

curl https://api.rokoapi.com/v1/tasks/task_public_id \
  -H "Authorization: Bearer $API_KEY"

查询响应提供两个状态字段：

• state：推荐新代码使用，固定为 queued、in_progress、completed、failed 或 unknown。
• status：保留的内部/渠道状态字段，供旧客户端继续使用。

任务成功后从 result_url、assets 或 data 读取结果。上游文件链接可能有有效期，生产环境应及时下载并转存。

错误与重试

• 400：参数不符合模型限制，修改请求后使用新的幂等 Key。
• 401：API Key 无效或已禁用。
• 403：余额、分组权限或模型权限不足。
• 409：幂等请求仍在处理，或同一个 Key 被用于不同请求。
• 429：按 Retry-After 或指数退避后，使用原幂等 Key 重试。
• 网络超时或未收到响应：使用原幂等 Key 重试，以取回第一次请求的结果，避免重复任务。
• 已明确收到失败响应：修正问题后如需发起一个新任务，应使用新的幂等 Key。

相关链接

• 认证
• 模型与价格
• 错误码
• 速率限制