图片合成 API

把 1~3 张参考图与一段 prompt 组合,让模型综合生成一张新图。常见用法:把人物 A 放进场景 B、把多个产品组合在同一画面、风格迁移合成等。

想做单张图编辑? 用 图片编辑 API — 单图换装、场景替换、变体等。

纯文生图? 用 图片生成 API。

适用场景对比

请求

POST /v1/images/compose

请求头

Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx
Content-Type: application/json

也支持 x-api-key 头(Anthropic SDK 风格)。

请求体

参考图总数:image_keys.length + generation_ids.length + image_urls.length 必须在 1~3 之间。三个数组可以混用。同一张图(包括跨数组)重复引用会被拒绝。

image_urls 安全限制:

• https:// URL 必须使用 HTTPS,Picklyone 会拒绝私网 / loopback / link-local / CGN 等内部地址,拒绝跳转、拒绝携带凭据(user:pass@host 形式),响应 Content-Type 必须是 image/(jpeg\|png\|gif\|webp),30 秒超时,单图最大 25MB。
• data: URI 必须是 data:image/(jpeg\|png\|gif\|webp);base64,... 的合法 base64,字符串长度上限 35MB,解码后字节上限 25MB,Picklyone 会校验文件头魔数是否与声明的 MIME 一致。
• 内联图片直接走 Workers 内存,不会写入 R2、不会消耗你的 200MB 文件配额、也不会出现在 /api/images/history。

完整示例

引用之前生成的两张图做合成:

{
  "model": "gpt-image-2",
  "prompt": "把图1的人物放进图2的场景里,保留服装,光照统一",
  "generation_ids": [
    "00000000-0000-0000-0000-000000000001",
    "00000000-0000-0000-0000-000000000002"
  ],
  "n": 1
}

混用上传图 + 生成图:

{
  "model": "gpt-image-2",
  "prompt": "把这个 logo 印在产品上,在白色木桌背景前展示",
  "image_keys": ["files/<userId>/<key>.png"],
  "generation_ids": ["<uuid>"],
  "n": 1
}

直接传 base64 内联图片(不需要预先上传):

{
  "model": "gpt-image-2",
  "prompt": "把图1的人物放进图2的场景里,保留服装,光照统一",
  "image_urls": [
    "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...",
    "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
  ],
  "n": 1
}

或者传公网 HTTPS URL:

{
  "model": "gpt-image-2",
  "prompt": "把人物放进这个场景",
  "image_urls": [
    "https://example.com/portrait.jpg",
    "https://example.com/scene.jpg"
  ],
  "n": 1
}

响应

{
  "created": 1776864985,
  "data": [
    {
      "b64_json": "iVBORw0KGgo...",
      "revised_prompt": "..."
    }
  ],
  "picklyone_generation_ids": ["00000000-0000-0000-0000-000000000099"]
}

计费

按次计费,与 图片生成 API 一致:actualCount × price_per_image。预扣按请求的 n 冻结,结算按实际返回数量收取,差额自动退回。

Python 示例

import requests, base64

API_KEY = "pk_live_xxxxxxxxxxxxxxxx"
BASE = "https://api.picklyone.com"

resp = requests.post(
    f"{BASE}/v1/images/compose",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "model": "gpt-image-2",
        "prompt": "把图1的人物放进图2的场景里",
        "generation_ids": [
            "00000000-0000-0000-0000-000000000001",
            "00000000-0000-0000-0000-000000000002",
        ],
        "n": 1,
    },
    timeout=300,
).json()

for i, item in enumerate(resp.get("data", [])):
    if item.get("b64_json"):
        with open(f"out_{i}.png", "wb") as f:
            f.write(base64.b64decode(item["b64_json"]))
        print(f"saved out_{i}.png — generation_id: {resp['picklyone_generation_ids'][i]}")

cURL 示例

curl https://api.picklyone.com/v1/images/compose \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "把图1的人物放进图2的场景里",
    "generation_ids": [
      "00000000-0000-0000-0000-000000000001",
      "00000000-0000-0000-0000-000000000002"
    ]
  }'

Node.js 示例

import fs from "fs";

const API_KEY = "pk_live_xxxxxxxxxxxxxxxx";
const BASE = "https://api.picklyone.com";

const resp = await fetch(`${BASE}/v1/images/compose`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "gpt-image-2",
    prompt: "...",
    image_keys: ["files/<userId>/<key>.png"],
    generation_ids: ["<uuid>"],
    n: 1,
  }),
}).then(r => r.json());

for (const [i, item] of resp.data.entries()) {
  if (item.b64_json) {
    fs.writeFileSync(`out_${i}.png`, Buffer.from(item.b64_json, "base64"));
  }
}

限制

错误码

注意事项

• 响应中的 b64_json 是裸 base64(不带 data:image/png;base64, 前缀),可以直接 Buffer.from(b64, "base64") 或 Python base64.b64decode(b64) 解码
• 图片自动入库 — 此端点会把生成的图片自动持久化到 Picklyone 历史记录,可在 /api/images/history 查询。响应里的 picklyone_generation_ids 是入库的 UUID
• 链式合成 — 把上一次返回的 picklyone_generation_ids[i] 作为下一次调用的 generation_id,即可在同一组上下文里逐步迭代

相关端点

• 文件上传(配合 image_keys 用):文件上传 API
• 单图编辑:图片编辑 API
• 传统文生图:图片生成 API