万绘工厂

API / 接入指南

用熟悉的方式接入图像生成

统一的图像生成与编辑接口,支持文生图、参考图改图和异步任务。模型与价格见价格页面。

快速开始

向统一接口发送 JSON 请求。将示例中的服务地址和 API Key 替换为你的实际值。

Base URL
https://your-host
请求方式
POST /v1/images/generations

文生图

curl -X POST https://your-host/v1/images/generations \
  -H "Authorization: Bearer sk-relay-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.6",
    "prompt": "一只坐在窗边的橘猫,柔和的午后光线",
    "size": "1:1"
  }'

参考图改图

在同一请求中传入公网图片地址即可进行图像编辑,最多支持 16 张参考图。

{
  "model": "gpt-image-2.6",
  "prompt": "保留主体,把背景换成雪山日落",
  "images": ["https://your-cdn.com/reference.png"],
  "size": "2:3"
}

参考图需要是公网可访问的 HTTP 或 HTTPS 图片地址,不支持 base64、data URI 或本地文件路径。

鉴权

在请求头中使用用户中心提供的 API Key。请将 Key 保存在服务端环境变量中,不要放进网页前端或公开仓库。

Authorization: Bearer sk-relay-your-key

注册后可在用户中心查看或重置 API Key。

请求参数

参数类型说明
modelstring模型名称:gpt-image-2.6、gpt-image-2.5 或 gpt-image-2.0。
promptstring生成或编辑图片的文字描述。
sizestring画布比例或像素尺寸,例如 1:1、16:9、1024x1024。
resolutionstring输出分辨率:1K、2K 或 4K。
qualitystring画质档位;可用值按所选模型而异。
output_formatstring输出格式,例如 png、jpeg 或 webp;2.6 还支持 gif、svg。
imagesstring[]可选参考图片 URL;传入后执行图像编辑。
asyncboolean设为 true 后立即返回任务 ID,之后轮询任务状态。

支持的尺寸和参数限制会随模型而异;不支持的参数会返回明确的错误信息。

异步任务

大尺寸或耗时较长的请求可使用异步模式。提交成功后保存返回的任务 ID:

POST /v1/images/generations
{
  "model": "gpt-image-2.6",
  "prompt": "海边灯塔与星空",
  "resolution": "4K",
  "async": true
}

使用以下接口查询任务。任务完成后,结果图片地址会出现在响应中。

GET /v1/images/tasks/{id}
Authorization: Bearer sk-relay-your-key

任务状态包括 queued、running、succeeded 和 failed。可间隔数秒轮询,直到任务结束。

响应格式

同步请求成功后返回标准 JSON 与图片 URL。异步请求先返回任务 ID,查询接口在完成后提供结果。

{
  "created": 1710000000,
  "data": [{ "url": "https://your-cdn.com/result.png" }],
  "relay": {
    "request_id": "req_example",
    "model": "gpt-image-2.6",
    "resolution": "1K"
  }
}

relay.price_credits 是本次请求的积分调用价。只有成功生成结果才会扣费,具体金额以当前价格表为准。

错误处理

HTTP 状态含义处理建议
400参数格式或取值不正确根据响应中的错误说明修正请求。
401API Key 无效或缺失检查鉴权请求头,并确认 Key 状态。
402账户积分不足联系站点客服充值后重试。
429并发请求数超限等待正在处理的请求完成后重试。
5xx服务或生成请求失败稍后重试;失败请求不扣除生成积分。

每次调用的状态、耗时和扣费明细都可在用户中心的调用日志查看。