图片编辑（上传参考图）

使用参考图 + 文字描述来编辑/生成图片。适合：风格转换、局部修改、图生图、多图融合等场景。

接口地址

POST https://foxapi.chat/v1/images/edits

⚠️ 注意

这个接口使用 multipart/form-data 格式（不是 JSON），需要上传图片文件。

前置条件

拥有一个 FoxAPI Key（获取教程）
Key 分组建议选 codex专用（倍率最低）
准备参考图片（支持 PNG / JPEG / WEBP，最大 50MB）

基本用法（单张参考图）

curl

bash

curl https://foxapi.chat/v1/images/edits \
  -H "Authorization: Bearer sk-你的Key" \
  -F "model=gpt-image-2" \
  -F "image=@/path/to/reference.png" \
  -F "prompt=把背景改成海边日落" \
  -F "size=1024x1024"

Python

python

from openai import OpenAI

client = OpenAI(
    api_key="sk-你的Key",
    base_url="https://foxapi.chat/v1"
)

response = client.images.edit(
    model="gpt-image-2",
    image=open("reference.png", "rb"),
    prompt="把背景改成海边日落",
    size="1024x1024"
)

print(response.data[0].url)

Node.js

javascript

import fs from 'fs';
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-你的Key',
  baseURL: 'https://foxapi.chat/v1',
});

const response = await client.images.edit({
  model: 'gpt-image-2',
  image: fs.createReadStream('reference.png'),
  prompt: '把背景改成海边日落',
  size: '1024x1024',
});

console.log(response.data[0].url);

PHP

php

<?php
$ch = curl_init('https://foxapi.chat/v1/images/edits');

$postData = [
    'model'  => 'gpt-image-2',
    'image'  => new CURLFile('/path/to/reference.png'),
    'prompt' => '把背景改成海边日落',
    'size'   => '1024x1024',
];

curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $postData,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer sk-你的Key'],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 300,
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
echo $data['data'][0]['url'];

多张参考图

可以同时上传多张参考图，AI 会根据所有参考图 + prompt 生成结果。

💡 上传方式

多个文件使用同一个字段名 image，不是分号分隔，不是逗号分隔。

curl

bash

curl https://foxapi.chat/v1/images/edits \
  -H "Authorization: Bearer sk-你的Key" \
  -F "model=gpt-image-2" \
  -F "image=@/path/to/img1.png" \
  -F "image=@/path/to/img2.png" \
  -F "image=@/path/to/img3.png" \
  -F "prompt=把这三张图融合成一个场景"

Python

python

response = client.images.edit(
    model="gpt-image-2",
    image=[
        open("img1.png", "rb"),
        open("img2.png", "rb"),
        open("img3.png", "rb"),
    ],
    prompt="把这三张图融合成一个场景",
)

Node.js

javascript

const response = await client.images.edit({
  model: 'gpt-image-2',
  image: [
    fs.createReadStream('img1.png'),
    fs.createReadStream('img2.png'),
    fs.createReadStream('img3.png'),
  ],
  prompt: '把这三张图融合成一个场景',
});

PHP

php

<?php
$ch = curl_init('https://foxapi.chat/v1/images/edits');

// 多张图：同一个字段名用 [] 数组语法
$postData = [
    'model'  => 'gpt-image-2',
    'prompt' => '把这三张图融合成一个场景',
    'image'  => [
        new CURLFile('/path/to/img1.png'),
        new CURLFile('/path/to/img2.png'),
        new CURLFile('/path/to/img3.png'),
    ],
];

curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $postData,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer sk-你的Key'],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 300,
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
echo $data['data'][0]['url'];

带蒙版（局部编辑）

只修改图片的特定区域，其他部分保持不变：

bash

curl https://foxapi.chat/v1/images/edits \
  -H "Authorization: Bearer sk-你的Key" \
  -F "model=gpt-image-2" \
  -F "image=@/path/to/photo.png" \
  -F "mask=@/path/to/mask.png" \
  -F "prompt=把这个区域改成草地" \
  -F "size=1024x1024"

python

response = client.images.edit(
    model="gpt-image-2",
    image=open("photo.png", "rb"),
    mask=open("mask.png", "rb"),  # 蒙版：白色区域=要修改的部分
    prompt="把这个区域改成草地",
    size="1024x1024"
)

php

<?php
$ch = curl_init('https://foxapi.chat/v1/images/edits');

$postData = [
    'model'  => 'gpt-image-2',
    'image'  => new CURLFile('/path/to/photo.png'),
    'mask'   => new CURLFile('/path/to/mask.png'),
    'prompt' => '把这个区域改成草地',
    'size'   => '1024x1024',
];

curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $postData,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer sk-你的Key'],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 300,
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
echo $data['data'][0]['url'];

💡 蒙版说明

蒙版是一张黑白图片：

白色区域 = 需要修改的部分
黑色区域 = 保持原样不动
蒙版尺寸必须和原图一致

参数说明

参数	类型	必填	默认值	说明
model	string	❌	`gpt-image-2`	模型名称
image	file	✅	—	参考图片，支持上传多张（同名字段）
prompt	string	✅	—	编辑描述，说明想要的效果
mask	file	❌	—	蒙版图片，指定编辑区域
n	integer	❌	1	生成数量，最多 4 张
size	string	❌	`1024x1024`	输出尺寸：`1024x1024`、`1024x1536`、`1536x1024`
quality	string	❌	`standard`	质量：`standard` 或 `hd`
response_format	string	❌	`url`	返回格式：`url` 或 `b64_json`

返回示例

json

{
  "created": 1749000000,
  "data": [
    {
      "url": "https://..."
    }
  ]
}

如果 response_format 设为 b64_json，返回的是 Base64 编码的图片数据：

json

{
  "created": 1749000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgo..."
    }
  ]
}

计费说明

gpt-image-2 按次计费，编辑图片和生图价格相同。codex专用分组成本最低。

💡 省钱技巧

使用 codex专用 分组的 Key，倍率最低。

常见问题

请求超时 (504)

图片编辑需要 30 秒到 3 分钟，取决于图片大小和复杂度。如果超时：

等待几分钟后重试
尝试缩小图片尺寸（建议 1024x1024 以内）
简化 prompt 描述

提示文件太大

参考图建议控制在 20MB 以内。超过 50MB 会被拒绝。

多图上传没效果

确保每个文件都是独立的 -F "image=@file" 字段
不是 -F "image=@file1;file2" 或 -F "image=@file1,file2"
PHP 中使用数组语法：'image' => [new CURLFile(...), new CURLFile(...)]

蒙版不生效

确保蒙版和原图尺寸一致
蒙版必须是 PNG 格式
白色区域 = 要编辑的部分

返回图片和原图差别太大

prompt 写得越具体，效果越可控。建议：

先描述整体风格
再描述要修改的具体内容
避免过于模糊的描述（如"好看一点"）

400 Bad Request

检查：

image 字段是否正确上传了文件（不是 URL，是文件本身）
Content-Type 是否为 multipart/form-data
文件格式是否为 PNG / JPEG / WEBP

图片编辑（上传参考图） ​

接口地址 ​

前置条件 ​

基本用法（单张参考图） ​

curl ​

Python ​

Node.js ​

PHP ​

多张参考图 ​

curl ​

Python ​

Node.js ​

PHP ​

带蒙版（局部编辑） ​

参数说明 ​

返回示例 ​

计费说明 ​

常见问题 ​

请求超时 (504) ​

提示文件太大 ​

多图上传没效果 ​

蒙版不生效 ​

返回图片和原图差别太大 ​

400 Bad Request ​

图片编辑（上传参考图）

接口地址

前置条件

基本用法（单张参考图）

curl

Python

Node.js

PHP

多张参考图

curl

Python

Node.js

PHP

带蒙版（局部编辑）

参数说明

返回示例

计费说明

常见问题

请求超时 (504)

提示文件太大

多图上传没效果

蒙版不生效

返回图片和原图差别太大

400 Bad Request