Studio 统一协议

协议导航

从这里切换协议

让 AI 帮我选

01StudioStudio 统一协议推荐当前五个模型统一调用，查询进度、获取结果和取消任务。02OpenAIOpenAI Images已有 OpenAI Images 工作流或 SDK。03GoogleGemini NativeGoogle SDK、多轮编辑和原生多模态结构。

import jsonimport httpximport timeapi_key = "YOUR_API_KEY"api_base = "https://api.1route.dev"payload = {    "model": "openai/gpt-image-2.5-flare",    "prompt": "Editorial portrait of a woman in profile beside a wind-bent tree, late afternoon light, deep cobalt coat, pale concrete wall, subtle film grain, restrained color palette, clean composition, vertical 4:5.",    "size": "auto"}headers = {"Authorization": f"Bearer {api_key}"}response = httpx.post(    api_base + "/api/v1/images/generations/jobs",    headers=headers,    json=payload,    timeout=1500,)response.raise_for_status()result = response.json()job_url = f"{api_base}/api/v1/images/jobs/{result['jobId']}"while result["phase"] in ("queued", "running"):    time.sleep(1.5)    snapshot = httpx.get(job_url, headers=headers, timeout=30)    snapshot.raise_for_status()    result = snapshot.json()if result["phase"] != "completed":    raise RuntimeError(result)response = httpx.get(f"{job_url}/result", headers=headers, timeout=120)response.raise_for_status()result = response.json()print(json.dumps(result, ensure_ascii=False, indent=2))

OpenAPI 接入

这份 OpenAPI 3.1 文档描述 Studio 的生成、编辑、任务查询、结果、取消、SSE 和媒体接口。导入后使用本页的 Base URL 与 API Key，并按“提交任务、查询状态、获取结果”的顺序调用。

调用流程

提交生成 / 编辑请求
    ↓ 202，返回 jobId
queued → running → completed → 获取结果 → 保存图片
             ├→ failed
             └→ cancelled

每个任务生成一张图片。批量生图时分别提交任务，保存每个 jobId，按 Key 的并发额度控制同时运行的任务数。202 表示任务已创建，不表示图片已生成。

生成图片

认证使用 Authorization: Bearer YOUR_API_KEY，请求体为 JSON。

🎨 GPT Image

{
  "model": "openai/gpt-image-2.5-flare",
  "prompt": "一张白色陶瓷咖啡杯的产品照片，浅灰背景，柔和侧光",
  "size": "1024x1024",
  "quality": "high"
}

model 必填，使用 openai/ 前缀；可选 gpt-image-2、gpt-image-2.5-flare、gpt-image-2.5-sunburst。gpt-image-2.5 是 Flare 的别名。

prompt 是非空的图片描述。size 默认 auto，也支持 1K、2K、4K 和 宽x高。具体尺寸按像素范围映射到上游档位。

quality 是模型扩展字段。Image 2 支持 auto、low、medium、high；2.5 系列另支持 xhigh、max。更高质量可能增加生成耗时。🎨 GPT Image 不使用 resolution 或 aspect_ratio。

🍌 Nano Banana

{
  "model": "google/gemini-3.1-flash-image",
  "prompt": "为咖啡店设计一张春季菜单海报，标题为 SPRING MENU",
  "resolution": "2K",
  "aspect_ratio": "3:4"
}

Google 模型使用 google/gemini-3.1-flash-image（🍌 Nano Banana 2）或 google/gemini-3-pro-image（🍌 Nano Banana Pro）。

resolution 默认 1K，常用值为 1K、2K、4K。aspect_ratio 默认 1:1，常用 3:2、2:3、4:3、3:4、16:9、9:16。Google 模型不发送 size。

参考图与编辑

{
  "model": "openai/gpt-image-2.5-sunburst",
  "prompt": "保持杯子的形状与标识，把背景换成木质桌面",
  "size": "1024x1024",
  "images": [
    { "url": "https://your-image-host.example/product.png" },
    { "dataUrl": "data:image/png;base64,<图片数据>" }
  ]
}

images 至少一项，每项只选择 url 或 dataUrl。列表中可以混合 URL 和 Data URL，顺序会保留。公网 URL 由服务端下载；本地文件在客户端转换为完整 Data URL。Studio 统一协议不使用 multipart。

🎨 GPT Image 局部编辑可附加 mask: { "image_url": "data:image/png;base64,..." }。遮罩对应第一张参考图，透明区域表示需要修改的部分。仍需在提示词里描述具体修改。

模型扩展字段

公共字段以外的顶层字段按所选模型的原生协议处理。例如 🎨 GPT Image 的 quality、output_format、output_compression、background、moderation，以及 Google 的 generationConfig、systemInstruction、safetySettings。

公共 prompt、images 和尺寸字段决定对应内容。Google 扩展示例：

{
  "model": "google/gemini-3-pro-image",
  "prompt": "生成一张横版展览海报，文字为 DESIGN WEEK",
  "resolution": "2K",
  "aspect_ratio": "16:9",
  "generationConfig": {
    "temperature": 0.7
  }
}

创建任务的响应

{
  "jobId": "job_example",
  "phase": "queued",
  "durationGuidance": {
    "tier": "2K",
    "timeoutSeconds": 150,
    "milestones": []
  }
}

jobId 用于后续查询。phase 是当前状态。durationGuidance 提供本任务的尺寸档位、超时时间及耗时提示；示例省略了提示项。milestones[] 包含 percentile、seconds、level、cardMessage、detailTitle、detailBody，用于展示等待时间提示，不是进度百分比。超时时间以实际响应为准。

查询任务

使用提交时的同一个 Key。查询响应的主要字段如下：

{
  "jobId": "job_example",
  "model": "openai/gpt-image-2.5-flare",
  "hasInputImage": false,
  "phase": "running",
  "createdAt": 1788940800000,
  "updatedAt": 1788940802000,
  "startedAt": 1788940801000,
  "durationGuidance": { "tier": "2K", "timeoutSeconds": 150, "milestones": [] }
}

createdAt、updatedAt、startedAt、finishedAt 都是 Unix 毫秒时间戳。尚未产生的可选字段可能省略。

queuePosition 为当前排队位置，message 为进度说明。任务状态以 phase 为准。usage 为已知的用量，error 包含失败详情。

获取并保存图片

{
  "images": [{
    "url": "https://api.1route.dev/api/v1/images/files/media_example",
    "base64": "<完整图片数据>",
    "mimeType": "image/png"
  }],
  "usage": {}
}

结果同时提供 url 和 base64，用 mimeType 确定文件类型。Studio 统一协议没有公共返回格式开关，选择读取需要的字段即可。

import base64
from pathlib import Path

image = result["images"][0]
Path("output.png").write_bytes(base64.b64decode(image["base64"]))

服务端图片与任务结果保留 72 小时，之后清理。URL 适合临时预览；长期使用请下载。媒体接口支持 GET / HEAD，过期返回 410 result_expired。

SSE 进度与取消

GET /api/v1/images/jobs/{jobId}/events 返回 text/event-stream。事件名为状态名（如 running、completed），data 是 snapshot；heartbeat 事件的 data 为 {}。进入终态后连接结束。

event: running
data: {"jobId":"job_example","phase":"running",...}

event: heartbeat
data: {}

DELETE /api/v1/images/jobs/{jobId} 请求取消，返回最终 snapshot。若任务已完成，可能仍返回 completed；应读取实际状态。关闭浏览器等待或断开 SSE 不等于取消任务。

幂等与错误

提交时可携带 Idempotency-Key。同一个 Key、同一个幂等值和相同请求返回原任务；相同幂等值用于不同请求会返回 409。

HTTP 错误结构为 error.status、message、type、code、param。任务已受理后的生成错误放在 snapshot 的 error 中。

请求体上限为 512 MiB，单张输入媒体上限为 80 MiB；模型自身的输入限制仍适用。频繁超时可切换本页列出的备用地址。