Skip to main content
POST
Image editing: edit a reference image or fuse several
Интерактивная песочница справа принимает загрузку локальных файлов. Введите ваш ключ API в Authorization (формат: Bearer sk-xxx), выберите файл image, заполните prompt и model, и отправьте.
🔴 Для этого эндпоинта требуется загрузка файла multipart/form-dataОтправка JSON в /v1/images/edits всегда возвращает 400:
Это особенно важно, если вы интегрируетесь из xAI или из документации исходного поставщика: в той документации описывается тело JSON с общедоступным URL изображения ({"image": {"type": "image_url", "url": "..."}}), и такой формат не работает через шлюз APIYI. Вместо этого используйте эту страницу.Преимущество в том, что загрузка файла означает не нужен хостинг изображений — просто отправьте локальный файл, что проще, чем готовить общедоступный URL.Поле файла должно называться image или image[]; images / image_file возвращают 415. prompt требуется — если его не указать, возвращается 400.
Когда использовать эту страницу: редактирование одного референсного изображения или объединение нескольких. Для генерации только по prompt используйте эндпоинт Text-to-Image.
⚠️ Размеры вывода следуют за входным изображением и не могут быть измененыresolution и aspect_ratio принимаются здесь без ошибки, но не влияют ни на что — результат редактирования всегда совпадает с размерами входного референсного изображения (1280x720 на входе дает 1280x720 на выходе; 1024x1024 на входе дает 1024x1024 на выходе).Чтобы изменить размер вывода, обрежьте или измените размер референсного изображения перед загрузкой.
Порядок объединения имеет значение: image[] принимает 1-3 референсных изображения, и порядок загрузки — это то, к чему в prompt относятся «изображение 1 / изображение 2 / изображение 3». Укажите это явно, например: «поместите объект из изображения 1 в сцену из изображения 2, сохранив художественный стиль изображения 2».

Примеры кода

Python (OpenAI SDK, одно изображение)

Python (raw requests, одно изображение)

Python (слияние нескольких изображений, 1-3 файла)

cURL

Node.js (нативный fetch + FormData)

JavaScript в браузере

Справочник параметров

Эта группа не поддерживает inpainting по маске. Чтобы ограничить масштаб изменения, опишите его точно в prompt — например: «измените только шарф на красный, а всё остальное оставьте точно таким же». Модель строго следует таким ограничениям.

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

Эндпоинт редактирования сохраняет художественный стиль, композицию, палитру и идентичность объекта входного изображения, изменяя только то, что указано в prompt. Для стабильных результатов:
Явное указание «сохранить всё остальное без изменений» — это самый эффективный приём при работе с этой моделью. Для слияния всегда ссылайтесь на «изображение 1 / изображение 2» в соответствии с порядком загрузки image[].

Формат ответа

Подводные камни полей ответа
  • Каждая запись data[] содержит либо url или b64_json в зависимости от response_format — никогда оба.
  • revised_prompt не возвращается — не предполагайте, что оно существует.
  • b64_json — это необработанный base64 без префикса data:image/...;base64, — декодируйте его напрямую.
  • created всегда 0 и не может использоваться как временная метка.
  • Размеры вывода определяются входным изображением, поэтому не определяйте ширину/высоту по параметрам запроса.
usage не может использоваться для сверки: prompt_tokens всегда 1000 x n, это заполнитель. Редактирование стоит столько же, сколько text-to-image, по фиксированной ставке за изображение; используйте записи тарификации в APIYI Console для фактических списаний.

Авторизации

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

API Key created in the APIYI Console

Тело

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

Model ID

Доступные опции:
grok-imagine-image,
grok-imagine-image-quality
prompt
string
обязательно

Editing instruction. State what to change and explicitly ask for everything else to stay put, e.g. Change the scarf color to bright RED. Keep everything else exactly the same.

Пример:

"Change the scarf color to bright RED. Keep everything else exactly the same."

image
file
обязательно

Reference image file. For multi-image fusion repeat the image[] field (1-3 files); upload order is what "image 1 / image 2 / image 3" refers to in the prompt. Accepted formats: png / jpg / webp.

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

Number of output images, 1-10. Independent of the number of reference images

Требуемый диапазон: 1 <= x <= 10
Пример:

1

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

Response format. url returns a direct link; b64_json returns raw base64 (no data: prefix)

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

"url"

Ответ

Image generated successfully

created
integer

Creation timestamp. Always 0 for this model — do not use it for timing

Пример:

0

data
object[]

Array of image results, length equals the requested n

usage
object

Placeholder values — do not use for billing reconciliation. prompt_tokens is always 1000 x n