图像生成任务

接口概览

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

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

GPT Image 2.6

前端用当前密钥的 GET /v1/models 判断哪些版本可调用，再按精确 ID 从公开目录 /api/catalog/models 读取能力与 pricing_display.rates。可以将三个 ID 合并为一个模型选择项，默认值为 gpt-image-2.6。高级选项中的 Flare 和 Sunburst 分别发送 gpt-image-2.6-flare 和 gpt-image-2.6-sunburst。

子模型选择

版本和输出类型是两个独立控件。两个子模型均可选择静态图或 GIF，采用同一套价格。用户明确选择版本时，把对应 ID 原样传入 model。

推荐交互

1. 模型列表展示 GPT Image 2.6，版本控件显示自动、Flare、Sunburst。
2. 用当前密钥的 /v1/models 过滤可调用版本，不可调用的版本显示不可用状态。
3. 静态图显示分辨率和透明背景。GIF 显示 2–16 帧整数选择器，默认 9 帧，固定 512×512，每次一个结果。
4. 版本或输出参数变化后，按精确 ID 从 pricing_display.rates 的 when 匹配价格。9 帧和 10–12 帧各有独立报价。
5. 提交后保存任务 ID，轮询期间禁用重复提交，完成后显示实际输出文件。

前端参数表单与渠道兼容

静态图片与 GIF 应使用独立的参数状态。不要把其他图像模型的默认参数直接套用到 Image 2.6。

静态图片使用 size 传画幅比例，例如 3:4，使用 resolution 传分辨率；不要在 size、aspect_ratio、aspectRatio 中发送互相冲突的值。多个尺寸比例选项应依据所选模型能力提供，不能把 GIF 的固定方形尺寸套用于静态图片，也不能把静态比例传给 GIF。

生成 GIF 时发送 output_format 为 gif。GRS 支持三个 Image 2.6 模型的 GIF 输出，其接口未列出帧数或每帧时长参数。指定 model_params 时，网关需选择支持动画参数的渠道。

GIF 帧数与帧率

model_params.frame_count 是总帧数，必须为 2–16 的整数，默认 9。model_params.frame_duration_ms 是每帧时长，必须为 20–2000 的整数毫秒；接口不使用 fps 字段。前端可以展示多个播放帧率选项，再转换为每帧时长：

换算公式为 1000 / fps。不能整除时取整数毫秒，并以实际时长计算展示帧率。帧率控制播放速度，总帧数决定动画包含多少帧；不要将两者混用。价格按目录中的帧数条件匹配，不按帧率档位推算。

静态图片请求示例

{
  "model": "gpt-image-2.6-sunburst",
  "prompt": "一只陶瓷小猫，适合作为透明背景素材",
  "output_format": "png",
  "background": "transparent",
  "size": "3:4",
  "resolution": "1K",
  "n": 1
}

有背景图片将 background 改为 opaque。透明输出需要实际检查结果文件，不能仅依据请求字段判断生成结果一定带透明通道。

以下是 GIF 任务的提交请求体：

{
  "model": "gpt-image-2.6-sunburst",
  "size": "512x512",
  "n": 1,
  "prompt": "一只纸风车缓慢转动，镜头固定",
  "output_format": "gif",
  "model_params": { "frame_count": 8, "frame_duration_ms": 160 }
}

用户切换输出类型时，请清除上一次的专用字段。例如，从透明 PNG 切到 GIF 时移除透明背景、分辨率和编辑图层。从 GIF 切回静态图时移除动画参数。提交后保存 task_id 并轮询；完成后按实际文件类型展示结果，保留 GIF 动画。静态图单张美元定价为 1K $0.025、2K $0.05、4K $0.08。GIF 固定为 512×512，每段定价为 2–8 帧 $0.017、9 帧 $0.035、10–12 帧 $0.031、13–16 帧 $0.050。默认 9 帧，用户可选择 2–16 帧。具体可用价格以公开目录为准。

切换模式与错误处理

• 切换为 GIF：设置 output_format: "gif"、size: "512x512"、n: 1，移除 resolution、透明背景、mask_url、markup_url 及旧的比例别名字段。
• 切回静态图片：移除整个 model_params，恢复用户选择的图片格式、背景、分辨率和比例；透明背景不能搭配 JPEG。
• 提交失败时读取 HTTP 状态、响应 code、message 及可用的字段详情；不要把所有参数错误统一映射为 star_task_error:unknown 或“内部错误”。轮询失败也应展示接口提供的具体失败原因。
• 参数错误应引导用户修正后重新提交；保留请求 ID 和已返回的任务 ID 便于排查。网络超时使用原幂等 Key 重试，避免重复创建任务。

当前 EvoLink 适配会将小写分辨率转为大写，并移除 quality: "auto"。因此，仅凭请求含 size: "3:4"、resolution: "1k"、quality: "auto"，不能断定失败原因；排查还需核对实际渠道、部署版本与原始错误响应。前端仍应按上述规范构造请求。

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

提交前请按以下规则构造请求，避免把不同含义的字段混用：

客户端应在发送请求前对 prompt.trim()、mode 枚举和上传完成状态进行校验。服务端返回 HTTP 400 时，应读取顶层 code 以及 data.field、data.action，不要仅匹配英文错误文案。

FLUX 3 Image（Kie 接入）

flux-3-image 使用同一个公开模型 ID 完成文生图与图片编辑：不传参考图时自动文生图，传入 1–10 张参考图时自动编辑，无需切换模型或手动选择渠道。仅接受可由上游下载的 HTTP / HTTPS 图片 URL，不接受 Base64、Data URL 或浏览器 blob: 地址。

{
  "model": "flux-3-image",
  "prompt": "把参考图中的杯子改成蓝色，保留形状和白色背景",
  "image_urls": ["https://example.com/mug.png"],
  "resolution": "2K",
  "aspect_ratio": "1:1",
  "n": 1,
  "enhance_prompt": false
}

• 删除 image_urls 即为文生图；也可使用 images、image（单个 URL 或数组）或 input_reference 提供参考图。
• resolution：1K、2K、4K，默认 1K；n：1–4，默认 1。按实际成功输出张数和分辨率结算，当前单价以模型目录为准。
• aspect_ratio：1:1、16:9、9:16、4:3、3:4、3:2、2:3、21:9、9:21；编辑时可用 auto 跟随参考图。文生图省略或传 auto 时使用 1:1。
• output_format：png、jpeg、webp，默认 png；enhance_prompt 可显式设为 false；seed 可传整数以请求可复现输出。
• 此接入使用 FLUX 3 Klein，不提供 BFL 完整版特有的 grounding、safety_tolerance、布局控制或版本选择能力。
• 使用本页的异步提交及查询流程：提交响应只表示受理，必须查询至成功或失败。网络异常或响应缺少任务 ID 时不要立即重复生成，应保留请求 ID 排查，以免重复收费。

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。

常规生成和局部重绘必须提供非空 prompt；缺失时返回 prompt_required 和 action: "enter_prompt"。mode 传入 fast、turbo 以外的值时返回 invalid_mode，响应同时给出 allowed_values 和 action: "select_mode"。两类错误均在计费前返回 HTTP 400，客户端应直接定位对应表单字段并阻止重复提交。

错误响应示例：

{
  "code": "invalid_mode",
  "message": "Midjourney mode must be fast or turbo",
  "data": {
    "category": "invalid_request",
    "field": "mode",
    "action": "select_mode",
    "allowed_values": ["fast", "turbo"],
    "submission_state": "rejected",
    "charge_status": "not_charged"
  }
}

幂等提交

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。

相关链接

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