curl --request POST \
--url https://api.apiyi.com/v1/images/edits \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: multipart/form-data' \
--form model=gpt-image-2 \
--form 'prompt=Place subject from image 1 into scene from image 2, using color style from image 3' \
--form 'image=<string>' \
--form image.items='@example-file' \
--form mask='@example-file'import requests
url = "https://api.apiyi.com/v1/images/edits"
files = {
"image.items": ("example-file", open("example-file", "rb")),
"mask": ("example-file", open("example-file", "rb"))
}
payload = {
"model": "gpt-image-2",
"prompt": "Place subject from image 1 into scene from image 2, using color style from image 3",
"image": "<string>"
}
headers = {"Authorization": "Bearer <token>"}
response = requests.post(url, data=payload, files=files, headers=headers)
print(response.text)const form = new FormData();
form.append('model', 'gpt-image-2');
form.append('prompt', 'Place subject from image 1 into scene from image 2, using color style from image 3');
form.append('image', '<string>');
form.append('image.items', '{
"fileName": "example-file"
}');
form.append('mask', '{
"fileName": "example-file"
}');
const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
options.body = form;
fetch('https://api.apiyi.com/v1/images/edits', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.apiyi.com/v1/images/edits",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"model\"\r\n\r\ngpt-image-2\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nPlace subject from image 1 into scene from image 2, using color style from image 3\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"mask\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: multipart/form-data"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.apiyi.com/v1/images/edits"
payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"model\"\r\n\r\ngpt-image-2\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nPlace subject from image 1 into scene from image 2, using color style from image 3\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"mask\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.apiyi.com/v1/images/edits")
.header("Authorization", "Bearer <token>")
.body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"model\"\r\n\r\ngpt-image-2\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nPlace subject from image 1 into scene from image 2, using color style from image 3\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"mask\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.apiyi.com/v1/images/edits")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"model\"\r\n\r\ngpt-image-2\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nPlace subject from image 1 into scene from image 2, using color style from image 3\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"mask\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--"
response = http.request(request)
puts response.read_body{
"created": 1776832476,
"data": [
{
"b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
}
],
"usage": {
"input_tokens": 1280,
"output_tokens": 6240,
"total_tokens": 7520
}
}Справочник API для редактирования изображений
справочник API для редактирования изображений gpt-image-2 и live-тестирование — загрузите референсные изображения (до 16) + инструкции для редактирования одного изображения, слияния нескольких изображений или inpainting по маске
curl --request POST \
--url https://api.apiyi.com/v1/images/edits \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: multipart/form-data' \
--form model=gpt-image-2 \
--form 'prompt=Place subject from image 1 into scene from image 2, using color style from image 3' \
--form 'image=<string>' \
--form image.items='@example-file' \
--form mask='@example-file'import requests
url = "https://api.apiyi.com/v1/images/edits"
files = {
"image.items": ("example-file", open("example-file", "rb")),
"mask": ("example-file", open("example-file", "rb"))
}
payload = {
"model": "gpt-image-2",
"prompt": "Place subject from image 1 into scene from image 2, using color style from image 3",
"image": "<string>"
}
headers = {"Authorization": "Bearer <token>"}
response = requests.post(url, data=payload, files=files, headers=headers)
print(response.text)const form = new FormData();
form.append('model', 'gpt-image-2');
form.append('prompt', 'Place subject from image 1 into scene from image 2, using color style from image 3');
form.append('image', '<string>');
form.append('image.items', '{
"fileName": "example-file"
}');
form.append('mask', '{
"fileName": "example-file"
}');
const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
options.body = form;
fetch('https://api.apiyi.com/v1/images/edits', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.apiyi.com/v1/images/edits",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"model\"\r\n\r\ngpt-image-2\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nPlace subject from image 1 into scene from image 2, using color style from image 3\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"mask\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: multipart/form-data"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.apiyi.com/v1/images/edits"
payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"model\"\r\n\r\ngpt-image-2\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nPlace subject from image 1 into scene from image 2, using color style from image 3\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"mask\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.apiyi.com/v1/images/edits")
.header("Authorization", "Bearer <token>")
.body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"model\"\r\n\r\ngpt-image-2\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nPlace subject from image 1 into scene from image 2, using color style from image 3\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"mask\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.apiyi.com/v1/images/edits")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"model\"\r\n\r\ngpt-image-2\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nPlace subject from image 1 into scene from image 2, using color style from image 3\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"mask\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--"
response = http.request(request)
puts response.read_body{
"created": 1776832476,
"data": [
{
"b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
}
],
"usage": {
"input_tokens": 1280,
"output_tokens": 6240,
"total_tokens": 7520
}
}Bearer sk-xxx), выберите файлы изображения / маски, заполните prompt и model, и отправьте.multipart/form-data. Для чистого text-to-image используйте эндпоинт Text-to-Image.请求时发生错误: unable to complete request после получения ответа — запрос на самом деле успешно выполнен; браузер просто не может отобразить такую длинную base64-строку.Рекомендуемый рабочий процесс (подходит для новичков):- Скопируйте приведенный ниже пример на Python / Node.js / cURL и запустите его локально. Код автоматически
base64.b64decodes ответ и записывает изображение в файл. - Если вам все же нужно использовать встроенную в браузер песочницу, используйте крошечное референсное изображение (< 50KB), установите
sizeна самый низкий уровень (например,1024x1024), иqualityнаlow.
- Не передавайте
input_fidelity—gpt-image-2принудительно включает high-fidelity; при передаче этого параметра возвращается 400 - У запросов на редактирование заметно больше input tokens — референсы превращаются в большое число tokens через тарификацию Vision; закладывайте это в бюджет
background: transparentне поддерживается — используйтеopaqueили выполните постобработку- Слияние нескольких изображений: максимум 16 — повторяйте поле
image[]; при количестве больше 16 возвращается ошибка
image[] принимает несколько референсных изображений. Порядок загрузки соответствует ссылкам на «изображение 1 / изображение 2 / изображение 3» в prompt. Ссылайтесь на них явно:Поместите объект из изображения 1 в сцену из изображения 2, используя цветовой стиль изображения 3Ограничение на файл: менее 50MB для каждого (multipart file upload), форматы:
png / jpg / webp; на практике перед загрузкой сжимайте до не более 1.5MB (см. «Ограничения размера загрузки» ниже).Примеры кода
Python (OpenAI SDK · редактирование одного изображения)
from openai import OpenAI
import base64
client = OpenAI(
api_key="sk-your-api-key",
base_url="https://api.apiyi.com/v1"
)
resp = client.images.edit(
model="gpt-image-2",
image=open("photo.png", "rb"),
prompt="Replace the background with a seaside sunset, preserve subject details",
size="1536x1024",
quality="high"
)
# b64_json is raw base64 (no prefix) — decode manually
with open("edited.png", "wb") as f:
f.write(base64.b64decode(resp.data[0].b64_json))
Python (OpenAI SDK · объединение нескольких изображений)
resp = client.images.edit(
model="gpt-image-2",
image=[
open("person.png", "rb"),
open("scene.png", "rb"),
open("style.png", "rb"),
],
prompt="Place subject from image 1 into scene from image 2, using color style from image 3, keep lighting consistent",
size="1536x1024",
quality="high"
)
with open("fused.png", "wb") as f:
f.write(base64.b64decode(resp.data[0].b64_json))
cURL (объединение нескольких изображений)
curl -X POST "https://api.apiyi.com/v1/images/edits" \
-H "Authorization: Bearer sk-your-api-key" \
-F "model=gpt-image-2" \
-F "prompt=Place subject from image 1 into scene from image 2, using color style from image 3" \
-F "size=1536x1024" \
-F "quality=high" \
-F "image[][email protected]" \
-F "image[][email protected]" \
-F "image[][email protected]"
cURL (дорисовка по маске)
curl -X POST "https://api.apiyi.com/v1/images/edits" \
-H "Authorization: Bearer sk-your-api-key" \
-F "model=gpt-image-2" \
-F "prompt=Replace the sky with pink sunset clouds" \
-F "size=1024x1024" \
-F "quality=high" \
-F "image[][email protected]" \
-F "[email protected]" \
| jq -r '.data[0].b64_json' | base64 -d > photo_edited.png
Node.js (Native fetch + FormData · объединение нескольких изображений)
import fs from 'node:fs';
const form = new FormData();
form.append('model', 'gpt-image-2');
form.append('prompt', 'Place subject from image 1 into scene from image 2');
form.append('size', '1536x1024');
form.append('quality', 'high');
form.append('image[]', new Blob([fs.readFileSync('./person.png')]), 'person.png');
form.append('image[]', new Blob([fs.readFileSync('./scene.png')]), 'scene.png');
const resp = await fetch('https://api.apiyi.com/v1/images/edits', {
method: 'POST',
headers: { 'Authorization': 'Bearer sk-your-api-key' },
body: form
});
const { data } = await resp.json();
fs.writeFileSync('fused.png', Buffer.from(data[0].b64_json, 'base64'));
Справочник параметров
| Поле | Тип | Обязательно | По умолчанию | Описание |
|---|---|---|---|---|
model | text | Yes | — | Фиксировано: gpt-image-2 |
prompt | text | Yes | — | Инструкция для редактирования / слияния |
image[] | file | Yes | — | Референсные изображения, можно повторять (макс. 16) |
mask | file | No | — | Изображение маски (применяется только к первому изображению, требуется alpha channel) |
size | text | No | auto | Размер вывода, как у text-to-image |
quality | text | No | auto | low / medium / high / auto |
output_format | text | No | png | png / jpeg / webp |
output_compression | text | No | — | 0–100, только для jpeg / webp |
background | text | No | auto | auto / opaque (не поддерживается: transparent) |
standard / hd для quality. Принимаются только четыре официальных значения enum low / medium / high / auto. Устаревшие значения ведут себя непоследовательно в разных backend-каналах: иногда они сразу завершаются с 400 (invalid_value), а иногда тихо игнорируются, и запрос выполняется с auto (непредсказуемая стоимость). Всегда явно передавайте одно из четырех официальных значений.Ограничения на размер загрузки
| Пункт | Лимит | Примечания |
|---|---|---|
| Количество reference image | До 16 | Повторите поле image[] |
| На одно изображение (загрузка файла multipart) | Менее 50MB каждое | Форматы: png / jpg / webp |
| На одно изображение (base64 data URL) | Длина поля ~20MiB | Это ограничение длины для URL/base64 строкового поля (схема maxLength: 20971520) — не то же самое, что и лимит 50MB для multipart; base64 увеличивает размер примерно на 1/3, поэтому исходные изображения держите в пределах 15MB |
| Файл mask | PNG до 4MB | Должен совпадать с размерами исходного изображения и содержать alpha-канал |
Требования к формату эталонного изображения и предварительная обработка
/v1/images/edits принимает только стандартные форматы png / jpg / webp. Если вы получаете эту ошибку 400:
{
"error": {
"message": "Invalid image file or mode for image 1, please check your image file. ...",
"type": "shell_api_error",
"code": "invalid_image_file"
}
}
.jpg, полученные прямо с телефонов серии Huawei Mate, содержат вложенный подкадр HDR gain-map и на самом деле являются MPO. Эти файлы начинаются с того же заголовка FFD8 — расширение и команда file оба сообщают JPEG — поэтому их невозможно распознать визуально; определить это может только разбор с учетом кадров (например, Pillow). «изображение 1» в сообщении об ошибке относится к N-му эталонному изображению (нумерация с 1), поэтому используйте индекс, чтобы найти проблемный файл.
Image.open(f).format возвращает "MPO", файл нужно конвертировать. Один шаг повторного кодирования в вашем пайплайне загрузки также покрывает HEIC и другие форматы смартфонов:
from PIL import Image
import io
def normalize_image(path: str) -> bytes:
"""Convert phone photos (MPO/HDR multi-frame etc.) to standard JPEG that passes edits validation"""
im = Image.open(path)
im.load() # for MPO, keeps only the first (full-size) frame
if im.mode not in ("RGB", "RGBA"):
im = im.convert("RGB")
out = io.BytesIO()
im.save(out, format="JPEG", quality=92) # or format="PNG"
return out.getvalue()
Требования к Mask Inpainting
- Тот же размер, что и у оригинала, формат PNG, меньше 4MB
- Обязательно наличие alpha channel: прозрачные области (alpha=0) = область inpaint, непрозрачные = сохранять
- Маска применяется только к первому изображению
- Маска — это «мягкая подсказка»: модель может расширять или сужать область вокруг замаскированного региона
image[] следующего вызова с новой инструкцией для постепенной доработки. Каждый раунд тарифицируется отдельно по tokens — следите за совокупной стоимостью.Формат ответа
{
"created": 1776832476,
"data": [
{
"b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
}
],
"usage": {
"input_tokens": 848,
"input_tokens_details": {
"image_tokens": 832,
"text_tokens": 16
},
"output_tokens": 196,
"output_tokens_details": {
"image_tokens": 196,
"text_tokens": 0
},
"total_tokens": 1044
}
}
b64_json — это необработанный base64, без префикса data:image/...;base64, — в отличие от gpt-image-2-all. Декодируйте его на стороне клиента, чтобы записать файл, или добавьте префикс для отображения в браузере.input_tokens у запросов на редактирование обычно значительно выше, чем у генерации изображений по тексту при том же размере, поскольку опорные изображения тарифицируются по правилам тарификации Vision — точная сумма доступна напрямую в usage.input_tokens_details.image_tokens и учитывается отдельно от текстовой части (text_tokens). Объединение нескольких изображений увеличивает image_tokens строго линейно с каждым дополнительным опорным изображением (проверено в июле 2026: 4 × 1024² изображений = 4 × 1024 tokens) — см. Как несколько входных изображений влияют на стоимость для таблицы измерений. См. Как проверить фактическое количество token для каждого вызова на странице обзора для полной справки по полям.Авторизации
API Key obtained from APIYI Console
Тело
Model name, fixed as gpt-image-2
gpt-image-2 Edit/fusion instruction. For multi-image, use 'image 1 / image 2 / image 3' to reference upload order
"Place subject from image 1 into scene from image 2, using color style from image 3"
Reference images. For a single image, send the field once; for multiple images, repeat the same image field (e.g., -F [email protected] -F [email protected], max 16) — upload order maps to image 1 / image 2 / ... in the prompt. multipart file upload: each under 50MB, formats: png/jpg/webp; compress to within 1.5MB in practice
Mask image (optional, only applies to first image). Requirements:
- Same size as original
- PNG format, under 4MB
- Must have alpha channel (alpha=0 = inpaint area, opaque = preserve)
Output size (same as text-to-image). Preset or constraint-satisfying custom size
"1536x1024"
Quality tier
auto, low, medium, high Output format
png, jpeg, webp Output compression (0–100), only effective for jpeg/webp
0 <= x <= 100Background mode. auto or opaque. Not supported: transparent
auto, opaque Была ли эта страница полезной?