图像生成任务

接口概览

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

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 的代码无需修改。

创建任务

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 返回为准。

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。

相关链接

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