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?response_format=base64", 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，按账户的并发额度控制同时运行的任务数。Studio 完整采用站点返回的用户并发额度，同一用户的多个 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高。具体尺寸按像素范围映射到上游档位。

请使用上述基础模型名，通过 size 选择尺寸。若客户端传入本站已识别的 -1k/-2k/-4k 模型别名，显式 size 的档位优先于模型后缀；例如 openai/gpt-image-2.5-sunburst-2k 配合 1824x1024 会按 1K 路由。size=auto 或未识别的模型名称保留请求模型。

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）或 google/gemini-nano-banana-2.1（🍌 Nano Banana 2.1）。

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、complexity、markup、safety_identifier 与 GIF 帧参数，以及 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
  }
}

OpenAI 标注层与 2.6 输出扩展

支持该能力的 GPT Image 2.5 / 2.6 模型可在编辑时附加透明 PNG markup 标注层。公共 images 仍为必填；标注层不能增加或替代参考图。markup.image_url 支持公网 URL 或完整 Data URL，也可在工作台的附加 JSON 字段中传入：

{
  "model": "openai/gpt-image-2.5-flare",
  "prompt": "按标注修改产品，保持其余内容不变",
  "size": "1024x1024",
  "images": [{ "url": "https://your-image-host.example/product.png" }],
  "markup": { "image_url": "data:image/png;base64,<透明 PNG 标注图数据>" }
}

标注图按方向信息解释后的宽高必须与首张参考图一致，必须含透明像素且不超过 50 MiB；两张图均最多 16,777,216 像素。不能与 mask 或 prompt_rewriter 同时使用。本站不支持 markup.file_id（unsupported_file_id，param=markup.file_id）。详见 Native 输入规则 与 编辑错误。

GPT Image 2.6 官方生成与编辑支持 complexity: "low" | "medium" | "high"，上游默认 high；文生图另支持 SVG 和动画 GIF。它们是 OpenAI provider 扩展，不是 Studio 公共字段，也不是 Gemini 参数。官方精确 ID 为 gpt-image-2.6-flare 和 gpt-image-2.6-sunburst；可用性、支持尺寸与价格以所选渠道的当前图片目录为准。

以下有条件适用的 2.6 文生图示例与浏览器、代码生成器共用请求构造器。SVG 每次生成一张；GIF frame_count 为 2–64（默认 9），frame_duration_ms 为 20–2000（默认 200），由上游按 10 ms 取整。SVG/GIF 不能作为编辑输出，不支持 partial_images、自定义 output_compression 或 prompt_rewriter。压缩参数只用于 JPEG/WebP。Studio 对 provider 的调用始终非流式，自己的任务 SSE 仍可报告进度。

{  "complexity": "medium",  "output_format": "svg",  "model": "openai/gpt-image-2.6-flare",  "prompt": "A simple flat vector icon of a white ceramic cup",  "size": "auto"}

{  "complexity": "medium",  "frame_count": 9,  "frame_duration_ms": 200,  "output_format": "gif",  "model": "openai/gpt-image-2.6-flare",  "prompt": "A seamless looping animation of steam rising from a ceramic cup",  "size": "auto"}

SVG/GIF 请保留返回的原始字节与 images[].mimeType（image/svg+xml / image/gif）。原件存储与下载不要经过 canvas 转换，也不要把静态预览当作动画原件；可以单独生成缩略图或剪贴板 PNG，原件继续保留。生图网站和无限画布的具体操作见工作台与生图网站说明和画布保存说明。providerMetadata.openai.outputFormat 和 usage 使用上游实际响应；不按请求帧数在本地推算费用。

创建任务的响应

{
  "jobId": "job_example",
  "phase": "queued",
  "durationGuidance": {
    "tier": "2K",
    "timeoutSeconds": 300,
    "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": 300, "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",
    "revisedPrompt": "<上游实际返回时提供>"
  }],
  "usage": {},
  "providerMetadata": {"openai": {"quality": "high", "outputFormat": "png", "outputCompression": 0, "moderation": "auto", "size": "1536x1024", "model": "gpt-image-2.5-flare"}}
}

默认结果同时提供 url 和 base64，用 mimeType 确定文件类型。OpenAI 可按图片提供 revisedPrompt， 并在 providerMetadata.openai 提供上游实际返回的 quality、background、outputFormat、 outputCompression、moderation、size 和 model；Gemini 使用 providerMetadata.gemini.modelVersion。 这些字段只在上游实际返回时出现，不能用请求值补齐；图片数量读取 images.length，尺寸档位与计费读取 usage.response。 获取结果时使用 query 参数 response_format 选择图片表示：

例如 GET /api/v1/images/jobs/{jobId}/result?response_format=url 只返回图片 URL 与 MIME， 不包含 Base64。不需要的字段省略，不返回 null。空值或其它值返回 400 invalid_value，error.param 为 response_format。

同一任务可以多次读取不同表示，不会重新生图。OpenAI 和 Google 模型使用相同规则； 该 query 不放入提交 JSON，不控制 Gemini 上游的 INLINE / URI。 三种格式均遵守相同的媒体可用性与过期规则。以下保存示例适用于 base64 或 both：

import base64
from pathlib import Path

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

服务端图片与任务结果保留 24 小时，之后清理。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 不等于取消任务。 对于分布式执行，任务首次取得上游许可前可以取消；已经开始执行的任务返回 409 job_not_cancellable，任务继续运行，客户端应继续查询或等待结果。已经进入终态的任务再次取消返回当前 snapshot。

幂等与错误

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

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

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