Skip to main content
POST
POST /v1/images/edits Endpoint для редактирования изображений использует тело запроса multipart/form-data. Загрузите одно или несколько референсных изображений и передайте prompt и параметры как поля формы.
Используйте https://bettertoken.ai/v1 как Base URL. API Key BetterToken передается через Authorization: Bearer YOUR_API_KEY.
В Playground справа можно заполнить поля формы, загрузить референсные изображения и отправить запрос напрямую на https://bettertoken.ai/v1/images/edits.
Не используйте обычное JSON-тело для image-to-image. Передавайте текстовые поля и файлы через multipart/form-data.

Рекомендуемые значения

Передавайте эти поля явно в каждом запросе:
Для одного референсного изображения используйте image. Для нескольких референсных изображений используйте повторяющиеся поля image[].

Одно референсное изображение

Несколько референсных изображений

Локальное редактирование по маске

Добавьте необязательное файловое поле mask, если нужно направить редактирование на выбранную область. Текущий endpoint BetterToken читает один файл mask. Не отправляйте повторяющиеся поля mask[].
  • Исходное изображение и mask должны иметь одинаковый формат и размеры в пикселях. Размер каждого файла должен быть меньше 50 MB. Для максимальной совместимости рекомендуется использовать PNG с Alpha-каналом для исходного изображения и mask.
  • Mask должна содержать Alpha-канал. Полностью прозрачные пиксели (Alpha 0) отмечают область, которую модель может перерисовать. Полностью непрозрачные пиксели (Alpha 255) направляют модель на сохранение области.
  • Обычное чёрно-белое RGB-изображение не является корректной mask, если в файле нет Alpha-канала.
  • Если вы передаёте несколько полей image[], mask применяется к первому входному изображению.
  • Mask служит ориентиром для модели и не гарантирует, что пиксели за пределами прозрачной области останутся абсолютно неизменными.

Редактирование по маске на Python

Откройте оба файла в одном операторе with, чтобы Python закрыл их после запроса:

Проверка файлов перед загрузкой

Этот минимальный пример с Pillow проверяет обязательные требования к формату, размерам и Alpha-каналу. Для обычной локальной mask он также выводит предупреждение, если Alpha-канал не содержит одновременно полностью прозрачные и полностью непрозрачные области:

Пример на Python

Рекомендуемые размеры

size задает ожидаемое соотношение сторон и уровень размера. Фактические пиксели в ответе могут быть сопоставлены или скорректированы сервером. Используйте размеры декодированного изображения, а не принудительную обрезку до запрошенного значения.

Сохранение изображения

Успешный ответ следует OpenAI-совместимой форме image response:
Прочитайте data[0].b64_json и сохраните его как base64 image content. Всегда задавайте output_format: "png", чтобы сохранить декодированное изображение как .png.

Поток ответа

Endpoint синхронный. После отправки POST /images/edits держите текущий HTTP-запрос открытым до ответа сервера. При успешной генерации содержимое изображения возвращается в data[0].b64_json. Endpoint не возвращает task_id; отдельного status query или endpoint для скачивания результата нет.

Смежные документы

Авторизации

Authorization
string
header
обязательно

Используйте API Key BetterToken как bearer token. Не публикуйте API keys во frontend-коде, скриншотах, логах, тикетах или Git-репозиториях.

Тело

multipart/form-data
model
enum<string>
по умолчанию:YOUR_MODEL_ID
обязательно

Используйте фиксированное значение YOUR_MODEL_ID.

Доступные опции:
YOUR_MODEL_ID
Пример:

"YOUR_MODEL_ID"

prompt
string
обязательно

Инструкция для редактирования изображения или генерации по референсному изображению.

Пример:

"На основе этого изображения создай более аккуратное квадратное главное изображение продукта, сохранив общий стиль основного объекта."

image
file

Поле для одного референсного изображения. В этом случае используйте image.

image[]
file[]

Поле для нескольких референсных изображений. Повторяйте image[] для каждого файла.

mask
file

Необязательный одиночный файл mask. Сервер читает только один файл mask. Формат и размеры mask должны совпадать с исходным изображением, размер каждого файла должен быть меньше 50 MB, а mask должна содержать Alpha-канал. Для максимальной совместимости рекомендуется использовать PNG с Alpha-каналом для обоих файлов. При нескольких image[] mask применяется к первому входному изображению.

n
по умолчанию:1

Рекомендуется фиксировать значение 1. Для нескольких изображений отправляйте несколько отдельных запросов.

Пример:

"1"

size
enum<string>
по умолчанию:1024x1024

Размеры и соотношения сторон изображения. auto выбирает размер автоматически; 1024x1024 и 2048x2048 — 1:1; 1536x1024 — 3:2; 1024x1536 — 2:3; 1536x1152 — 4:3; 1152x1536 — 3:4; 2048x1152 и 3840x2160 — 16:9; 2160x3840 — 9:16. Фактический размер может быть сопоставлен или скорректирован сервером, поэтому клиенту следует ориентироваться на реальные размеры декодированного изображения.

Доступные опции:
auto,
1024x1024,
1536x1024,
1024x1536,
1536x1152,
1152x1536,
2048x2048,
2048x1152,
3840x2160,
2160x3840
Пример:

"1024x1024"

response_format
enum<string>
по умолчанию:b64_json

Рекомендуется фиксировать b64_json.

Доступные опции:
b64_json
Пример:

"b64_json"

output_format
enum<string>
по умолчанию:png

Рекомендуется фиксировать png. Не рассчитывайте, что jpeg или webp всегда вернутся напрямую в выбранном формате.

Доступные опции:
png
Пример:

"png"

Ответ

Результат генерации изображения.

OpenAI-совместимый ответ с изображением. Клиентам следует читать data[0].b64_json и учитывать возможные дополнительные поля, например revised_prompt.

created
integer
Пример:

1710000000

data
object[]