图片生成接口

公共约定（基础地址、认证、响应结构、限流）见认证与基础规范。

创建图片

POST/v1/images/generations

认证方式

Authorization: Bearer <API_KEY>，使用控制台「API 密钥」创建的平台 API Key。

请求体 · application/json

Prop

Type

图片模型对尺寸、数量、返回格式的限制各不相同，请先用 /v1/models 确认，并以接口返回的参数校验错误为准。

请求示例

先用 /v1/models 确认当前 Key 可用的图片模型 ID，再把 model 换成它。 size 必须落在该模型支持的档位内——不同模型的最小像素数差异很大，填错会直接返回参数错误，而不是被静默降级。

响应可能是地址形式，也可能是 Base64 形式，取决于模型与渠道。

请求

curl -X POST "https://locopalai.com/v1/images/generations" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "从 /v1/models 选择的图片模型 ID",
  "prompt": "白色桌面上的一个红苹果，柔和自然光，产品摄影",
  "size": "当前模型支持的尺寸",
  "n": 1
}
JSON

响应参数

参数	类型	说明
`created`	integer	生成时间（Unix 秒）
`model`	string	部分模型返回实际执行的模型 ID
`data`	array	生成结果列表
`data[].url`	string	图片地址；返回 URL 形式时存在，可能是短期签名地址
`data[].b64_json`	string	Base64 图片数据；返回 Base64 形式时存在
`data[].size`	string	部分模型返回实际生成尺寸
`size`	string	顶层返回实际生成尺寸，例如 `1024x1024`、`1376x768`
`quality`	string	顶层返回实际画质档位，例如 `auto`、`low`
`output_format`	string	顶层返回实际输出格式，例如 `png`
`background`	string	顶层返回背景处理方式，例如 `auto`、`opaque`
`moderation`	string	顶层返回内容审核档位，部分模型返回
`usage`	object	图片用量；图生图会额外统计输入图片 token

单次请求可能只返回 url 或只返回 b64_json，取决于模型和渠道；请以实际返回字段为准，两种都存在时优先使用 url。

响应体

返回地址（url 形式）：

{
  "created": 1789567052,
  "data": [
    {
      "size": "2048x2048",
      "url": "https://media.example.com/image-public-id.jpeg"
    }
  ],
  "model": "Doubao-Seedream-4.5"
}

返回 Base64（b64_json 形式，节选）：

{
  "background": "auto",
  "created": 1789071752,
  "data": [
    { "b64_json": "iVBORw0KGgoAAAANSUhEUgAABAAAAAQACAIAAADwf7zU..." }
  ]
}

url 形式返回的地址可能是短期签名地址，请及时转存或登记；b64_json 形式请自行解码并妥善存放。不要假设所有图片模型都接受 response_format 或相同尺寸。实测 gpt-image-1-mini 会拒绝 response_format，Doubao-Seedream-4.5 当前要求图片至少 3686400 像素，2048x2048 可受理而 1024x1024 会返回参数错误。

错误响应

{
  "error": {
    "message": "当前图片模型不支持请求的尺寸",
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "param": "size"
  }
}

HTTP	响应 / 原因	处理
`400`	`Model name not specified, model name cannot be empty`	请求体缺少 `model`
`400`	`invalid_parameter`（`param=size`）	改用当前模型支持的尺寸
`400`	`unknown_parameter`（`param=response_format`）	删除该字段，使用模型默认返回格式
`400`	`InvalidParameter` / `upstream_error`	上游模型拒绝尺寸、像素数或其他参数，按 `message` 调整
`400`	`invalid_parameter`（`param=n`）	改为 `n=1`
`400`	`image is required`（`code=convert_request_failed`）	图生图请求没有携带参考图，按下方示例补上 `image`
`400`	`n must be an integer between 1 and 128`（`code=invalid_request`）	`n` 超出范围，改为 `1`–`128`
`429`	`credit_balance_exhausted` / `insufficient_quota`	当前渠道余额不足，换用其他可用渠道或联系平台支持
`401`	`Invalid token`	API Key 缺失、错误或已失效
`500`	`{"error":{"code":"convert_request_failed","message":"not supported model for image generation, only imagen models are supported"}}`	当前模型不支持图片生成接口，改用支持该接口的图片模型
`503`	`model_not_found` / `No available channel`	当前分组没有该模型的可用渠道，改选同类模型

完整说明见错误码与排查。

图生图（图片编辑）

POST/v1/images/edits

在已有图片的基础上生成新图：上传一张或多张参考图，模型按 prompt 改写画面、更换风格或做局部重绘。

请求体 · multipart/form-data

Prop

Type

请求必须携带参考图，缺少时接口直接返回参数错误，不会进入模型。

请求示例

图生图走 multipart/form-data，用 -F 逐个字段提交，不要用 -d。参考图通过 image=@文件路径 上传。

需要多张参考图时，把字段写成数组形式 image[] 并重复。这里没有 JSON 请求体，Content-Type 由 curl -F 自动设置，不要手写。

图生图

curl -X POST "https://locopalai.com/v1/images/edits" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -F "model=从 /v1/models 选择的图片模型 ID" \
  -F "prompt=把这张照片改成柔和的水彩画风格" \
  -F "size=1024x1024" \
  -F "image=@./reference.png"

多张参考图时重复该字段：

  -F "image[]=@./reference-a.png" \
  -F "image[]=@./reference-b.png"

响应体

与创建图片同一结构，图片以 b64_json 或 url 返回：

{
  "background": "opaque",
  "created": 1789651524,
  "data": [
    { "b64_json": "iVBORw0KGgoAAAANSUhEUgAABAAAAAQACAIAAADwf7zU..." }
  ],
  "output_format": "png",
  "quality": "low",
  "size": "1024x1024",
  "usage": {
    "input_tokens": 1041,
    "input_tokens_details": { "image_tokens": 1032, "text_tokens": 9 },
    "output_tokens": 439,
    "total_tokens": 1480
  }
}

usage.input_tokens_details.image_tokens 反映参考图的消耗：参考图越多或尺寸越大，输入 token 越高。

用公网地址传参考图

支持参考图输入的模型也可以在 POST /v1/images/generations 的 JSON 请求体里用 images 传入，元素为公网 https:// 图片地址：

curl -X POST "https://locopalai.com/v1/images/generations" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "从 /v1/models 选择的图片模型 ID",
  "prompt": "把这张照片改成柔和的水彩画风格",
  "images": ["https://example.com/reference.png"]
}
JSON

参考图必须能被服务端直接下载；地址失效或需要登录时请求会以上游下载错误结束。响应结构与创建图片一致。

与素材库的关系

图片生成不会自动进入素材库。若后续视频任务要把图片当作参考图，请先用素材库接口入库并轮询到 Active，再用 asset://<asset_id> 引用。

本页目录