跳转到主要内容

概述

根据原始图像和提示词创建编辑或扩展的图像。 此端点同时支持:
  • 下方文档中的 OpenAI 兼容 multipart/form-data 上传流程
  • 为支持的图像到图像模型提供 image_urlimage_urls 或官方 images 引用的 JSON 请求
gpt-image-2 已支持此端点。它支持 multipart image 上传、JSON image_url / image_urls,以及官方 images[] 引用(image_urlfile_id),最多 16 张源图。file_id 需先通过 /v1/files 创建。设置 async: true 会先返回任务;官方 FLUX/BFL 编辑模型也使用同一套任务轮询流程。gpt-image-2 编辑不接受 resolutionbackground;输出尺寸请使用 size。多图或高延迟编辑建议设置 async: true 并轮询返回任务。Nano Banana 参考图请求(nano-banananano-banana-2nano-banana-pro)公开在 /v1/images/generations,应使用 operation: "image-to-image"image_urls,不要发送到本 /v1/images/edits 端点。xAI Grok Imagine 图像编辑模型(grok-imagine-imagegrok-imagine-image-quality 以及 legacy grok-imagine-image-pro)最多接受 3 张源图。超过 3 张的请求会在输入校验阶段返回 400 too_many_imagesinput_fidelity 不属于当前 TokenLab 对 gpt-image-2 的支持字段;请省略该字段,否则请求会返回 400 unsupported_parameter

请求体

同步请求超时: 某些图片请求会以内联方式返回最终图片,并等待生成完成。高分辨率或高质量请求可能接近一分钟甚至更久,因此请将 HTTP 客户端超时设置为至少 120s。如果创建响应包含 status: "pending"task_idpoll_url,请改为跟随返回的 poll_url 轮询。 远程图片 URL:当需要 multipart 输入时,TokenLab 会拉取 JSON image_urlimage_urlsimages[].image_url,并把图片字节作为 multipart image 文件发送。URL 必须是公网 http/https,不能包含用户名密码或 fragment,不能解析到 localhost、内网或保留 IP;每次重定向后的目标也会重新校验。拉取到的内容必须是真实 PNG、JPEG 或 WebP 图片。限制为单图 50MB、单次请求 URL 拉取图片总计 200MB、拉取超时 10s、最多 3 次重定向。
image
file
multipart 源图片。需要多张 GPT Image 源图时,可以重复发送 image 字段。文件必须是 PNG、JPEG 或 WebP,最多 16 张源图,每张不超过 50MB。xAI Grok Imagine 编辑模型使用相同输入字段,但源图最多 3 张。
prompt
string
必填
描述所需编辑的文本。
mask
file
一个附加图像,其完全透明的区域指示应编辑图像的位置。必须是有效的 PNG 文件,小于 50MB,且与 image 具有相同的尺寸。对于 JSON 请求,mask 也可以是一个对象,并且只能包含 image_urlfile_id 其中之一;file_id 必须来自 /v1/files,并且绑定到同一套图像编辑配置。
model
string
必填
用于图片编辑的模型。GPT Image 编辑请使用 gpt-image-2,也可以使用 GET /v1/models?recommended_for=image 返回的其他当前图片编辑模型。
n
integer
默认值:"1"
要生成的图像数量。必须在 1 到 10 之间。
size
string
生成图片的尺寸。对于 gpt-image-2,使用 autoWIDTHxHEIGHT;宽高必须是 16 的倍数,最长边不超过 3840px,长边/短边比例不超过 3:1,总像素在 655,3608,294,400 之间。
response_format
string
默认值:"url"
返回生成图像的格式。必须是 urlb64_json,默认 url对于 Azure Official 或 Azure-compatible 的 gpt-image-2 请求,TokenLab 会以 b64_json 接收图片数据。请求 url 时,TokenLab 会把每张图上传到 CDN 并返回 data[].url。如果 CDN 存储不可用或上传失败,请求会失败,而不是改为 Base64 响应;请求 b64_json 时直接返回原始 Base64。
async
boolean
默认值:"false"
gpt-image-2 或官方 FLUX/BFL 编辑模型设置为 true 时,会在最终图片完成前先返回任务。完成后的异步编辑无论请求的 response_format 是什么,都只返回 URL;如果需要 b64_json,请使用同步请求。
user
string
代表终端用户的唯一标识符,用于滥用监控。

响应

created
integer
图像创建时间的 Unix 时间戳。
data
array
生成的图像数组。每个对象包含:
  • url (string): 编辑后图像的 URL(如果 response_format 是 url
  • b64_json (string): Base64 编码的图像(如果 response_format 是 b64_json

异步任务响应

gpt-image-2 或官方 FLUX/BFL 编辑模型设置 async: true 后,请求会先创建任务,而不是等待编辑后的图片完成。响应包含 status: "pending"task_idpoll_url。请轮询 /v1/tasks/{task_id},直到任务进入 completedfailed 异步编辑任务最终只返回图片 URL。如果你需要原始 b64_json 图片数据,请使用同步请求。 任务创建时可能会先预留预计费用。任务完成后按实际用量结算;失败或超时的任务会释放预留费用或退回费用。
curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=gpt-image-2" \
  -F "image=@sunlit_lounge.png" \
  -F "mask=@mask.png" \
  -F "prompt=阳光明媚的室内休息区,带有游泳池" \
  -F "n=1" \
  -F "size=1024x1024"
from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.tokenlab.sh/v1"
)

response = client.images.edit(
    model="gpt-image-2",
    image=open("sunlit_lounge.png", "rb"),
    mask=open("mask.png", "rb"),
    prompt="阳光明媚的室内休息区,带有游泳池",
    n=1,
    size="1024x1024"
)

print(response.data[0].url)
import OpenAI from 'openai';
import fs from 'fs';

const client = new OpenAI({
  apiKey: 'sk-your-api-key',
  baseURL: 'https://api.tokenlab.sh/v1'
});

const response = await client.images.edit({
  model: 'gpt-image-2',
  image: fs.createReadStream('sunlit_lounge.png'),
  mask: fs.createReadStream('mask.png'),
  prompt: '阳光明媚的室内休息区,带有游泳池',
  n: 1,
  size: '1024x1024'
});

console.log(response.data[0].url);
{
  "created": 1706000000,
  "data": [
    {
      "url": "https://..."
    }
  ]
}

注意事项

远程图片拉取失败会在生成开始前作为输入错误返回。URL 不可访问、超时、403/404、私有或内网主机、URL 中包含用户名密码或 fragment、非图片内容、不支持的格式、超过大小限制,都会返回 400413,并指向 image_url / image_urls[n] 输入。私有或需要请求头鉴权的素材,请直接用 multipart image 上传,或创建 /v1/files 引用。