Grok Imagine (reverse): генерация и редактирование изображений

Grok Imagine Reverse: генерация и редактирование изображений

Полное руководство по Grok Imagine 2, модели генерации изображений последнего поколения от xAI (grok-imagine-image / grok-imagine-image-quality) на APIYI — 5 соотношений сторон, уровни 1K/2K, до 10 изображений за запрос, полноценное редактирование по референсному изображению, фиксированная цена $0.02 /$ 0.045 за изображение независимо от разрешения — около 64% от базовой цены для 2K. Доступ закрыт по умолчанию — требуется выделенная группа Grok_imagine_Reverse.

Обзор

Grok Imagine 2 — это новейшая модель генерации изображений второго поколения от xAI, представляющая собой полноценный шаг вперед по сравнению с первым релизом как в контроле параметров, так и в редактировании: соотношение сторон и разрешение действительно применяются, доступен уровень 2K, один вызов возвращает до 10 изображений, а редактирование по референсу по-настоящему сохраняет исходное изображение. APIYI предлагает два варианта: grok-imagine-image (стандартный) и grok-imagine-image-quality (высокое качество). Оба используют одни и те же эндпоинты и параметры — они различаются только детализацией результата и ценой.

На этой странице описан реверс-канал Grok Imagine — цены не изменились: по-прежнему фиксированные $0.02 / $0.045 за изображение независимо от разрешения, с поддержкой редактирования и генерации нескольких изображений.Если вам требуется официальный канал с тарификацией как у xAI, зависящей от разрешения и уровня качества, или более новая grok-imagine-image-2.0, см. Grok Imagine Official. Для генерации видео см. Grok Imagine Video.

🔒 Это семейство недоступно по умолчанию — для доступа требуется выделенная группа Grok_imagine_ReverseGrok Imagine 2 полностью интегрирована и стабильна, но она не входит в группу Default. Ее политика безопасности контента существенно отличается от других моделей на платформе — некоторые категории не фильтруются, поэтому для снижения рисков комплаенса доступ предоставляется выборочно:

Действующие клиенты с суммарными расходами от $1,000: свяжитесь с поддержкой, опишите ваш сценарий использования, и мы включим доступ после проверки
Все остальные: подайте заявку через поддержку в WeCom, описав ваш сценарий использования и механизмы модерации контента; мы активируем доступ для вашего аккаунта после одобрения заявки

Вызов моделей с Token без группы Grok_imagine_Reverse возвращает 503 — это ошибка прав доступа, а не сбой в работе сервиса. Инструкции по подаче заявки и настройке см. ниже в разделе Настройка группы.

Ключевые особенности: фиксированная тарификация за запрос, которая не зависит от разрешения (у xAI уровень качества стоит $0.07 за 2K; мы списываем $0.045 в любом случае, примерно 64% от официальной цены), 5 вариантов соотношения сторон x 2 уровня разрешения, которые действительно применяются, до 10 изображений за вызов, а также высокоточное редактирование по референсу с сохранением художественного стиля, композиции, цветовой палитры и идентичности объекта. Генерация изображения 1K занимает около 9 секунд.

В идентификаторах моделей нет 2. Продукт называется Grok Imagine 2, но имена моделей для вызова — grok-imagine-image и grok-imagine-image-quality. Не указывайте grok-imagine-2-image: такой модели не существует, и запрос вернет 503.

📌 Прочтите перед началом работы: референсные изображения работают только с эндпоинтом редактирования /v1/images/edits — и никогда с генерацией изображений по тексту.Передача image / image_url / images в /v1/images/generations возвращает код 200 с абсолютно нормальным изображением, однако референс незаметно отбрасывается, а тарификация за запрос все равно происходит — без каких-либо ошибок. См. раздел Эндпоинты ниже.

Все API генерации изображений являются синхронными: асинхронный ID задачи отсутствует, поэтому при отключении клиента результат теряется, при этом запрос все равно тарифицируется. Установите достаточный таймаут — см. раздел Рекомендации по Image API.

API генерации изображений по тексту

Генерация изображений по текстовому prompt с интерактивным Playground для тестирования в реальном времени.

API редактирования изображений

Загрузка референсных изображений вместе с инструкцией, объединение от 1 до 4 изображений и Playground.

Доверьте интеграцию ИИ-агенту

Скопируйте этот prompt и вставьте его в Codex / Claude Code / Cursor

Сначала он загрузит текстовую версию этой страницы (добавьте .md к любому URL документации), а затем напишет код под стек вашего проекта: таймаут, немедленное сохранение URL-результатов в свое хранилище, эндпоинт, который незаметно отбрасывает референсные изображения, но всё равно списывает средства, а также тот факт, что size ничего не делает, — всё это уже заложено в требования.

Выполните интеграцию / устранение неполадок Grok Imagine 2 (генерация изображений по тексту и редактирование изображений) в этом проекте.

Прежде чем писать код, изучите документацию: запросите https://docs.apiyi.com/en/api-capabilities/grok-imagine-image/overview.md для получения текстовой версии этой страницы. Для более подробной информации о параметрах добавьте .md …

Названия моделей: стандартный уровень — grok-imagine-image, а уровень высокой детализации — grok-imagine-image-quality. Обратите внимание, что идентификатор модели не содержит ц …

Всего 9 требований. Используйте кнопку ниже, чтобы скопировать полный prompt.

От каких проблем защищает этот prompt

Требование	Предотвращаемая проблема
Референсные изображения — только на эндпоинт редактирования	Отправка их на `/v1/images/generations` возвращает 200, незаметно отбрасывает референс и всё равно списывает средства — самая затратная ловушка, именно потому что ошибка не возникает
Никогда не передавайте `size`	Он незаметно игнорируется: вы думаете, что задали размер, но получаете квадрат 1024 на 1024
ID модели без цифры 2	`grok-imagine-2-image` возвращает 503, что выглядит как сбой сервиса, но на самом деле является неверным именем
Высокая детализация — это модель, а не параметр	У этой модели нет параметра `quality`; его отправка просто игнорируется
Не сверяйте затраты по `usage`	Это заглушка, где `prompt_tokens` жестко зафиксирован как 1000, умноженное на n; используйте записи тарификации в консоли
Таймаут по-прежнему на 360 с	Задержка около 15 секунд провоцирует установить слишком короткий таймаут, который срабатывает при пиковой нагрузке — а средства за отключенный запрос всё равно списываются. См. Основы Image API и лучшие практики

Почему Grok Imagine 2 на APIYI

Формат, совместимый с OpenAI

Стандартные /v1/images/generations и /v1/images/edits эндпоинты. Тела запросов и поля ответов совпадают с OpenAI Images API, поэтому официальный OpenAI SDK работает напрямую — без усилий по миграции.

Без ограничений на параллельные запросы

Без жёстких лимитов RPM/RPD. Измерено уверенно на уровне 100 RPM при достаточной пропускной способности канала, так что пакетные нагрузки масштабируются линейно — не нужны запросы на квоту или искусственное ограничение скорости.

Фиксированная цена, предсказуемая стоимость

Фиксированная цена за изображение, независимо от разрешения: xAI указывает уровень качества по $0.05 за 1K и $0.07 за 2K, тогда как у нас действует фиксированная цена $0.045 — примерно 64% от списка для 2K. Планируйте бюджет точно по числу изображений и используйте бонусы за пополнение, чтобы снизить стоимость ещё больше.

Глобальный доступ без барьеров

Не требуется зарубежный сервер или proxy. Материковые дата-центры, домашний широкополосный доступ и зарубежные узлы — всё подключается напрямую к api.apiyi.com.

Полная экосистема моделей

Также доступны: Nano Banana 2, GPT-Image-2, Seedream, FLUX, а также текстовые модели Grok.

Профессиональная поддержка

Наша команда глубоко работает с нагрузками генерации изображений и может поддержать корпоративных клиентов от PoC до вывода в промышленную эксплуатацию.

Ключевые особенности

Два уровня разрешения

1k — около 1 мегапикселя, 2k — 4,2–4,5 мегапикселя (2816x1584 при соотношении сторон 16:9): цена одинаковая, поэтому 2K выгоднее

5 соотношений сторон

1:1 / 16:9 / 9:16 / 4:3 / 3:4; фактические размеры в пикселях точно соответствуют заявленным

До 10 изображений за запрос

n принимает от 1 до 10 изображений и возвращает их одним запросом — идеально для пакетного отбора

Быстрая генерация

Около 9 с для 1K и 15–17 с для 2K; задержка остаётся стабильной под нагрузкой — 100 запросов в минуту обрабатываются без проблем

Точное редактирование по референсу

Меняется только то, о чём вы просите: художественный стиль, композиция, палитра и идентичность объекта остаются неизменными

Объединение нескольких изображений

Эндпоинт редактирования принимает от 1 до 4 референсов: как показали тесты, каждый добавляет объект, а первый задаёт размеры результата

Два формата ответа

url прямые ссылки или b64_json исходные данные base64 поддерживаются обоими эндпоинтами

Совместимость с OpenAI SDK

client.images.generate() и client.images.edit() работают сразу — настройка HTTP вручную не требуется

Примеры результатов

Преобразование текста в изображение · научно-фантастическая сцена (grok-imagine-image; только промпт: кольцевая обсерватория парит над морем облаков, её металлический корпус отражает золотистый свет заката, вдали видна гигантская газовая планета, широкоформатная композиция): 10,5 с; выразительные отражения на металле, убедительный объём облаков, цельная и хорошо проработанная композиция.

Образец преобразования текста в изображение через обратный канал Grok Imagine: кольцевая обсерватория парит над облаками, а за ней видна гигантская газовая планета

Редактирование изображения · заменить поверхность, сохранив объект (grok-imagine-image; на референсе флакон средства по уходу за кожей на деревянном столе, промпт: замените дерево белой мраморной столешницей, оставив флакон и сухие цветы без изменений): 13,9 с; прожилки мрамора соответствуют направлению света из окна, контур флакона и форма цветов не искажены — среди рассматриваемых семейств здесь лучше всего сохранён объект.

Образец редактирования через обратный канал Grok Imagine: деревянный стол заменён белым мрамором, а флакон и сухие цветы сохранены без изменений

Цены

Модель	Разрешение	Цена APIYI	Прайс-лист xAI	Скидка
`grok-imagine-image`	`1k` / `2k`	$0.02 / image	$0.02	Соответствует прайс-листу
`grok-imagine-image-quality`	`1k`	$0.045 / image	$0.05	90% от прайс-листа
`grok-imagine-image-quality`	`2k`	$0.045 / image	$0.07	~64% от прайс-листа

Примечания к тарификации

Мы игнорируем разрешение; xAI — нет. У xAI уровень качества указан по $0.05 для 1K и $0.07 для 2K, тогда как APIYI взимает фиксированные $0.045 — поэтому чем выше разрешение, тем больше экономия, достигающая примерно 64% от прайс-листа на 2K.
За изображение: n=4 тарифицируется как 4 изображения, независимо от длины prompt.
Редактирование стоит столько же, сколько и text-to-image — для /v1/images/edits не предусмотрена наценка.
Блок usage нельзя использовать для сверки: prompt_tokens всегда 1000 x n, это заполнитель. Вместо этого используйте записи тарификации в консоли.

Эффективная стоимость с бонусами за пополнение

Эти скидки суммируются с многоуровневым бонусом за пополнение (рассчитывается для каждого отдельного пополнения, а не суммарно). Если брать уровень качества 2K:

Уровень пополнения	Множитель кредита	Итог за изображение	по сравнению с $0.07 у xAI
Без акции (цена из прайс-листа)	1.0x	$0.045	64% от прайс-листа
Однократное пополнение на $100 (+10%)	1.1x	≈ $0.041	~58% от прайс-листа
Однократное пополнение на $1,000 (+15%)	1.15x	≈ $0.039	~56% от прайс-листа
Однократное пополнение на $3,000 (+20%)	1.2x	$0.0375	~54% от прайс-листа

В обычном случае (уровень $100), изображение 2K обходится примерно в 58% от прайс-листа xAI, снижаясь примерно до 54% при максимальном бонусе. Стандартный grok-imagine-image работает так же — его цена из прайс-листа $0.02 становится примерно $0.0167 за изображение при бонусе 20%.

Настройка группы

Grok Imagine 2 не входит в группу Default и не открыт по умолчанию. Он находится в отдельной группе Grok_imagine_Reverse (коэффициент тарифа 1.0x, в соответствии с таблицей цен выше), и доступ необходимо запрашивать.

Об имени группы: в консоли эта группа отображается как Grok_imagine_Reverse (ранее Grok_imagine). Для Tokens, у которых уже есть доступ, изменений не требуется — тарификация и вызовы остаются без изменений. Почему отдельная группа: политика безопасности контента этого семейства существенно отличается от других моделей на платформе, и некоторые категории не фильтруются. Чтобы снизить комплаенс-риски, мы не включаем его в группу по умолчанию, доступную всем аккаунтам, а предоставляем доступ выборочно.

Кто может получить доступ

Клиент	Как предоставляется доступ
Действующие клиенты с суммарными расходами $1,000+	Обратитесь в службу поддержки, опишите ваш сценарий использования; доступ активируется после проверки
Все остальные клиенты	Отправьте заявку с описанием вашего сценария использования и механизмов модерации контента; доступ активируется после одобрения

Как подать заявку

Свяжитесь со службой поддержки WeCom

Подайте заявку через поддержку WeCom или по электронной почте [email protected].

Опишите ваш сценарий использования и механизмы модерации

Укажите три момента: для какого продукта предназначены изображения, кто конечные пользователи и какие механизмы модерации и ручной проверки вы применяете на своей стороне. Чем конкретнее запрос, тем быстрее рассмотрение.

Переключите свой Token на эту группу

После одобрения мы активируем Grok_imagine_Reverse для вашего аккаунта. Перейдите на страницу Token в консоли и переключите Token, используемый для этого семейства, на Grok_imagine_Reverse, указав модель тарификации Pay-as-you-go Priority или Pay-per-request.

Как это выглядит до предоставления доступа: Token без группы Grok_imagine_Reverse возвращает 503 (нет доступного канала в текущей группе). Повторные попытки не помогут — сначала необходимо активировать группу.Рекомендуемая модель тарификации Token: Pay-as-you-go Priority. Это семейство тарифицируется за каждый запрос, и маршрутизация работает корректно как для «Pay-as-you-go Priority», так и для «Pay-per-request» — при выборе «Pay-as-you-go Priority» один и тот же Token можно использовать и для моделей с тарификацией по token на остальной части платформы.

Примечание о комплаенсе: после предоставления доступа ответственность за сгенерированный контент несет вызывающая сторона. Соблюдайте применимое к вам законодательство; не генерируйте незаконный контент, материалы, нарушающие права на изображение граждан или интеллектуальную собственность, а также контент, не предназначенный для несовершеннолетних. При распространении среди конечных пользователей рекомендуется внедрить дополнительный уровень модерации на вашей стороне. Дополнительная информация: комплаенс при вызове зарубежных моделей. В случае злоупотреблений доступ к группе будет отозван.

Технические характеристики

Item	Specification
Model IDs	`grok-imagine-image`, `grok-imagine-image-quality`
Aspect ratios	5: `1:1` / `16:9` / `9:16` / `4:3` / `3:4`
Resolution tiers	`1k` (~0.9-1.05 MP), `2k` (~4.2-4.5 MP)
Output format	JPEG at 1K (~220-300 KB), PNG at 2K (~5-6 MB)
Images per call	`n` 1-10
Reference images	1-4 на эндпоинте редактирования (повторно `image[]`; пятое возвращает 400)
Mask inpainting	❌ Не поддерживается
Reproducible `seed`	❌ Не поддерживается
`revised_prompt` echo	❌ Не возвращается
Latency	~9s at 1K, ~15-17s at 2K
Concurrency / rate	Без ограничений; уверенно измерено на 100 RPM
Recommended client timeout	360 seconds or more

Эндпоинты

Возможность	Метод	Путь	Content-Type
Генерация изображений по тексту	`POST`	`/v1/images/generations`	`application/json`
Редактирование изображений	`POST`	`/v1/images/edits`	`multipart/form-data`
Генерация в формате чата	`POST`	`/v1/chat/completions`	`application/json`

✅ Для эндпоинта редактирования требуется загрузка файла через multipart/form-dataОтправка JSON на /v1/images/edits всегда возвращает 400:

request Content-Type isn't multipart/form-data

Это особенно важно, если вы выполняете интеграцию по документации вышестоящего поставщика — в ней описано тело JSON с публичным URL изображения, что не работает через шлюз APIYI. Вместо этого следуйте инструкциям на этой странице: загружайте файл с помощью -F "[email protected]". Подробные примеры см. в API редактирования изображений.Поле файла должно называться image или image[]; images / image_file возвращают 415.

⚠️ Никогда не отправляйте референсные изображения в эндпоинт генерации изображений по текстуКогда /v1/images/generations получает image / image_url / images, он не возвращает ошибку. Он возвращает 200 и генерирует совершенно новое изображение исключительно по prompt, полностью игнорируя ваш референс — и тарифицирует запрос в обычном режиме.Поскольку сигнал об ошибке отсутствует, это обычно обнаруживается только тогда, когда кто-то замечает, что результат не имеет ничего общего с входными данными. В любом сценарии с использованием референсного изображения необходимо использовать /v1/images/edits.

Основной домен — https://api.apiyi.com, резервный — https://b.apiyi.com. Генерация в формате чата (/v1/chat/completions) работает, но не является рекомендуемым способом — см. раздел FAQ ниже.

Миграция с GPT-Image-2

Если вы уже интегрировали GPT-Image-2, эндпоинты и соглашение о вызовах идентичны (/v1/images/generations + /v1/images/edits, совместимо с OpenAI SDK), однако система параметров отличается, поэтому простая замена имени модели не сработает. Ниже описано, что необходимо изменить.

Сопоставление параметров

В таблице GPT-Image-2 используется в качестве основы; gpt-image-2.5-flare / gpt-image-2.5-sunburst используют те же параметры, поэтому сопоставление применимо и к ним.

Аспект	GPT-Image-2	Grok Imagine 2	Действие при миграции
Размер вывода	`size` (явно заданные пиксели, например `1536x1024`)	`aspect_ratio` + `resolution`	Необходимо переписать; `size` не вызывает ошибку
Уровень качества	`quality` (`low`/`medium`/`high`/`auto`)	Такого параметра нет — используйте имя модели	Удалите `quality` и переключитесь на вариант `-quality`
Формат вывода	`output_format` (png/jpeg/webp) + `output_compression`	Такого параметра нет — формат определяется разрешением	Удалите оба параметра; 1K всегда использует JPEG, 2K — PNG
Фон	`background` (`opaque`/`auto`)	Такого параметра нет	Удалите его
Уровень модерации	`moderation` (`auto`/`low`)	Такого параметра нет	Удалите его
Высокая точность	`input_fidelity` нельзя отправлять	Такого параметра нет	Удалите его
Количество изображений за вызов	`n` поддерживает только 1	`n` поддерживает 1–10	✅ Можно удалить цикл распределения запросов на стороне клиента
Эталонные изображения (редактирование)	До 16	До 4	⚠️ Переработайте процессы, отправляющие более 4 изображений
Заполнение маски	✅ Поддерживается	❌ Не поддерживается	⚠️ Процессы, зависящие от маски, перенести нельзя
Тарификация	За token (примерно $0.21 за изображение при высоком качестве)	Фиксированная плата за запрос, $0.02 / $0.045	Модель расчёта бюджета меняется с тарификации на основе использования на тарификацию за изображение

Три самые распространённые ошибки

1. Формат ответа по умолчанию инвертирован — это изменение чаще всего упускаютGPT-Image-2 возвращает только b64_json (url отсутствует), тогда как Grok Imagine 2 по умолчанию возвращает url. Если ваш парсер считывает resp.data[0].b64_json, после миграции он получит None / undefined.Выберите один из двух вариантов исправления:

Сохранить существующий код → явно передавать "response_format": "b64_json"
Переключиться на прямые ссылки → считывать data[0].url и скачивать его

Также обратите внимание: usage GPT-Image-2 содержит реальные значения количества token, тогда как usage Grok Imagine 2 является заполнителем (всегда 1000 x n). Любой скрипт расчёта стоимости, построенный на usage, после миграции будет выдавать неверные значения.

2. size завершается без уведомления об ошибкеGPT-Image-2 выполняет строгую проверку и обычно возвращает ошибку 400 при некорректных входных данных. Grok Imagine 2 более снисходителен: поля в стиле OpenAI, такие как size, quality и style, молча игнорируются, а недопустимые значения aspect_ratio / resolution молча заменяются значениями по умолчанию.Поэтому, если вы измените только model и забудете удалить size: "1536x1024", запрос вернёт ответ 200 с квадратным изображением 1024x1024 — при этом ничто не сообщит вам, что параметр был проигнорирован.После миграции проверьте размеры вывода в пикселях при первом вызове, чтобы убедиться, что aspect_ratio / resolution действительно применились.

3. Эталонные изображения больше нельзя передавать в эндпоинт преобразования текста в изображениеЭта проблема характерна именно для данной модели: отправка эталонного изображения в /v1/images/generations возвращает ответ 200, молча отбрасывает эталонное изображение и всё равно включает запрос в тарификацию. Каждый вызов с эталонным изображением должен использовать /v1/images/edits с multipart/form-data — см. раздел Эндпоинты выше.

До и после

# Before: GPT-Image-2
resp = client.images.generate(
    model="gpt-image-2",
    prompt="Cyberpunk city on a rainy night",
    size="1536x1024",           # <- remove
    quality="high",             # <- remove
    output_format="jpeg"        # <- remove
)
img = base64.b64decode(resp.data[0].b64_json)

# After: Grok Imagine 2
resp = client.images.generate(
    model="grok-imagine-image",           # use grok-imagine-image-quality for higher fidelity
    prompt="Cyberpunk city on a rainy night",
    n=1,
    extra_body={
        "aspect_ratio": "16:9",           # <- replaces size
        "resolution": "1k",               # <- replaces the sizing role of quality
        "response_format": "b64_json"     # <- set explicitly to keep the parser unchanged
    }
)
img = base64.b64decode(resp.data[0].b64_json)

Что следует использовать? Оставайтесь на GPT-Image-2, если вам нужны заполнение маски, пользовательские размеры с точностью до пикселя или объединение до 16 эталонных изображений. Выбирайте Grok Imagine 2 для предсказуемой стоимости (фиксированная плата за изображение, без доплаты за 2K), нескольких изображений за вызов (n до 10) или высокой точности исходного изображения при редактировании. Эти две модели могут использоваться одновременно — один и тот же вызов с Token обращается к обеим.

Ключевые параметры

`aspect_ratio` и `resolution` (размер вывода)

Вместе они определяют фактическое количество пикселей вывода. Измеренные значения точно соответствуют запросу:

`aspect_ratio`	`resolution: 1k`	`resolution: 2k`
`1:1`	1024x1024	2048x2048
`16:9`	1280x720	2816x1584
`9:16`	720x1280	1584x2816
`4:3`	1152x864	2368x1776
`3:4`	864x1152	1776x2368

Оба параметра применяются только к text-to-image. На /v1/images/edits они принимаются без ошибки, но не влияют ни на что — отредактированный результат всегда совпадает с размерами первого reference image (1280x720 на входе, 1280x720 на выходе; при изменении порядка в fusion set выход будет следовать за новым первым изображением). Чтобы изменить размер вывода, обрежьте или измените размер reference image перед загрузкой.

Проверка выполняется мягко — опечатки не вызывают ошибок. Значения вне enum для aspect_ratio (например, 5:7, 21:9) или resolution (например, 1K, 1024x1024) молча откатываются к значению по умолчанию и всё равно возвращают image. Неверный response_format аналогично откатывается к url. Поэтому, если результат не соответствует ожиданиям, сначала проверьте написание параметров.Единственное исключение — resolution: "4k", который возвращает 503 model_service_unavailable. Это означает, что уровень не поддерживается, а не что канал недоступен — переключитесь обратно на 1k / 2k.

`n` (изображений за вызов)

Принимает 1-10; длина возвращаемого массива data равна n, и каждое image тарифицируется. 0 молча интерпретируется как 1; 11 или выше возвращает 400.

Лучшие практики

Сразу решите: генерация или редактирование?

Без опорного изображения → /v1/images/generations. Любое опорное изображение, даже для изменения на один пиксель → /v1/images/edits. Если выбрать неверный эндпоинт, ошибки не будет — только неожиданное изображение.

Установите тайм-аут клиента на 360 секунд

API генерации изображений синхронны. 2K занимает 15-17 секунд и может выполняться дольше в пиковые периоды или при холодном запуске. Тайм-аут 60 секунд приводит к ложным сбоям в запросах, за которые всё равно взимается плата.

Контролируйте композицию с помощью aspect_ratio, а не prompt

Этот параметр действительно работает, поэтому aspect_ratio: "16:9" гораздо надёжнее, чем просить в prompt «пейзажную композицию».

Выбирайте уровень разрешения с учётом пропускной способности

2K — это PNG без потерь размером 5-6 MB на изображение; 1K — JPEG размером 220-300 KB, то есть примерно в 20 раз меньше. Для мобильных устройств или массовой передачи лучше выбирать 1K. Поскольку оба уровня стоят одинаково, выбор — это только качество против пропускной способности.

Говорите «оставьте всё остальное без изменений» при редактировании

Инструкции вроде «смените шарф на красный и оставьте всё остальное точно таким же» работают очень хорошо — модель строго следует этому ограничению и сохраняет остальную часть изображения.

Явно указывайте изображения при объединении

Порядок загрузки image[] — это то, что означает «изображение 1 / изображение 2 / изображение 3». Формулировка «поместите объект из изображения 1 в сцену из изображения 2» гораздо надёжнее, чем позволять модели угадывать.

Не полагайтесь на seed для воспроизводимости

Эта линейка не поддерживает seed; один и тот же prompt даёт разные результаты при разных вызовах. Сохраняйте изображения, которые хотите оставить, вместо того чтобы ожидать их повторной генерации.

Просто используйте параллельную обработку для пакетных задач

Ограничений на параллельные запросы нет — 100 RPM работает комфортно при достаточной ёмкости канала. Не нужно строить последовательную очередь или запрашивать дополнительную квоту.

Коды ошибок и повторные попытки

HTTP	code	Значение	Рекомендуемые действия
`400`	`invalid_image_request`	Эндпоинт редактирования получил JSON вместо multipart	Переключитесь на загрузку `multipart/form-data`; не повторяйте запрос
`400`	`invalid_request`	Недопустимые параметры или prompt заблокирован модерацией	Один и тот же код для обоих случаев — сначала проверьте параметры, затем скорректируйте prompt
`415`	—	Неподдерживаемое имя поля файла в эндпоинте редактирования	Переименуйте поле в `image` или `image[]`
`429`	—	Превышен лимит запросов или недостаточно средств на балансе	Экспоненциальная задержка и проверка баланса аккаунта
`503`	`model_service_unavailable`	Неподдерживаемый уровень параметров (например, `resolution: 4k`)	Это не сбой в работе сервиса — переключитесь обратно на `1k` / `2k`, не повторяйте запрос
`503`	—	У token отсутствует группа `Grok_imagine_Reverse`	Проблема с правами доступа, а не сбой — повторные попытки не помогут; подайте заявку через Настройка групп

Рекомендации для клиента: 400 и 415 детерминированы — повторять запросы бессмысленно, вместо этого отправляйте оповещение. Повторять запросы имеет смысл только для 429 и таймаутов сетевого уровня, используя экспоненциальную задержку и максимум 3 попытки.Обратите внимание, что 400 invalid_request охватывает как «неверный параметр», так и «контент заблокирован», причем по телу ответа их различить невозможно. Практический эвристический метод — оценка задержки: блокировки модерации возвращаются примерно за 5–6 секунд (быстрее успешной генерации, занимающей ~9 с), поскольку блокировка происходит до начала генерации.

Часто задаваемые вопросы

Каждый вызов возвращает 503 — канал недоступен? Как получить доступ?

Сначала определите, какая именно это 503. Передача resolution: "4k" означает, что данный уровень не поддерживается (см. пункт ниже). Если параметры в порядке, а 503 возвращается постоянно, то у token практически наверняка отсутствует группа Grok_imagine_Reverse.Это семейство моделей недоступно по умолчанию: его политика безопасности контента существенно отличается от других моделей на платформе, и некоторые категории не фильтруются. Поэтому для снижения регуляторных рисков мы выделили его в отдельную группу Grok_imagine_Reverse и предоставляем доступ выборочно. Действующие клиенты с суммарными расходами от $1,000+ могут запросить подключение, описав свой сценарий использования службе поддержки; всем остальным необходимо подать заявку через поддержку WeCom с описанием сценария использования и применяемых мер модерации контента.Полная инструкция приведена выше в разделе Настройка группы.

Почему отправка JSON на /v1/images/edits возвращает 400, если в документации провайдера указан JSON?

Потому что эндпоинт редактирования шлюза APIYI принимает только multipart/form-data, в то время как в исходной документации провайдера описано тело JSON с публичным URL изображения. Они различаются — ориентируйтесь на документацию нашего сайта.Корректный формат — загрузка файла:

curl -X POST "https://api.apiyi.com/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=grok-imagine-image" \
  -F "prompt=Change the scarf to red, keep everything else the same" \
  -F "[email protected]"

Плюс в том, что вам не нужен хостинг изображений — загружайте локальный файл напрямую, что гораздо проще, чем подготавливать публичный URL. Полные примеры доступны в разделе API редактирования изображений.

Я отправил референсное изображение в генерацию по тексту и получил 200, но результат никак с ним не связан?

Это ожидаемое поведение и самая распространенная ошибка при работе с этой моделью: /v1/images/generations молча игнорирует image / image_url / images, генерирует изображение исключительно по prompt и тарифицирует запрос в обычном режиме.Из-за отсутствия ошибки легко сделать ложный вывод, что «редактирование не работает». Любой рабочий процесс с референсным изображением должен использовать /v1/images/edits.

Почему resolution / aspect_ratio не влияют на эндпоинт редактирования?

Размеры отредактированного изображения на выходе соответствуют исходному референсному изображению: при входе 1280x720 получается 1280x720, при 1024x1024 — 1024x1024. Передача resolution или aspect_ratio в данном случае не вызывает ошибки, но ни на что не влияет.Чтобы изменить размер выходного изображения, кадрируйте или измените размер референсного изображения перед загрузкой.

Почему в ответе нет поля revised_prompt?

Это семейство моделей не возвращает revised_prompt, а также такие поля, как respect_moderation или model. Каждый элемент data[] содержит либо url, либо b64_json в зависимости от response_format — но никогда оба одновременно.Не рассчитывайте на наличие этих полей при парсинге ответов.

Можно ли сверить тарификацию по количеству token в usage?

Нет. Значение usage.prompt_tokens всегда равно 1000 x n независимо от фактической длины prompt — это плейсхолдер.Это семейство тарифицируется за запрос по фиксированной ставке за каждое изображение. Для проверки фактических списаний используйте записи о тарификации в консоли APIYI.

Почему разрешение 1K возвращается в формате JPEG, а 2K — в PNG? Их размеры сильно отличаются

Таково поведение вышестоящего провайдера: resolution: 1k возвращает JPEG (~220–300 КБ), а resolution: 2k — PNG без потерь (~5–6 МБ), разница примерно в 20 раз.Расширение в URL, HTTP-заголовок Content-Type и фактические байты согласованы между собой, поэтому вы можете безопасно ветвить логику по Content-Type.Для сценариев, чувствительных к пропускной способности сети (мобильные устройства, массовая передача), отдавайте предпочтение 1k — оба уровня стоят одинаково, поэтому выбор зависит исключительно от требований к качеству. И наоборот, если вам нужно качество, 2k не требует доплаты и предоставляется со значительно большей скидкой относительно базовой цены.

Параметр resolution: 4k возвращает 503 — канал недоступен?

Нет. 4k не поддерживается в этом семействе моделей, и шлюз возвращает 503 model_service_unavailable. Код ошибки выглядит как сбой канала, но на самом деле проблема в параметре, поэтому повторные попытки не помогут — вернитесь к 1k или 2k.Поддерживаются только 1k и 2k.

Почему неверные параметры приводят к генерации некорректного изображения вместо ошибки?

Валидация в этом семействе моделей нестрогая: недопустимые значения aspect_ratio (например, 5:7), resolution (например, 1K, 1024x1024) и response_format (например, base64) молча сбрасываются до значений по умолчанию и возвращают изображение вместо ошибки 400.Поэтому, если результат не соответствует ожиданиям, сначала проверьте написание параметров — в частности, значения resolution должны быть в нижнем регистре: 1k / 2k.

Сколько изображений можно получить за один вызов?

n принимает значения от 1 до 10, а длина возвращаемого массива data равна n. Каждое изображение тарифицируется.Значение 0 неявно интерпретируется как 1; передача 11 или больше возвращает 400 invalid_request.

Поддерживается ли воспроизводимость результатов с помощью seed?

Нет. Передача seed не вызывает ошибки, но ни на что не влияет: один и тот же prompt с тем же seed при повторных вызовах будет возвращать разные изображения.Сохраняйте изображение, если оно может понадобиться в дальнейшем, вместо попыток сгенерировать его заново.

Можно ли вызывать это через официальный SDK OpenAI?

Да. Оба эндпоинта совместимы с OpenAI Images API — просто укажите base_url на https://api.apiyi.com/v1:

from openai import OpenAI
client = OpenAI(api_key="sk-your-api-key", base_url="https://api.apiyi.com/v1")

resp = client.images.generate(
    model="grok-imagine-image",
    prompt="a red wooden boat on an alpine lake at dawn",
    extra_body={"aspect_ratio": "16:9", "resolution": "1k"}
)

Обратите внимание, что aspect_ratio и resolution не являются стандартными полями SDK OpenAI, поэтому передавайте их через extra_body.

Есть ли ограничения на параллельные запросы? Будет ли замедляться пакетная генерация?

Ограничений на параллельные запросы нет. По результатам тестов система стабильно работает на 100 RPM без ошибок 429 и отклонений в очереди благодаря достаточной пропускной способности канала. Выполняйте запросы параллельно, не создавая последовательную очередь и не запрашивая дополнительную квоту.Что действительно важно — это timeout: API генерации изображений синхронны, поэтому задайте таймаут клиента на уровне 360 секунд, чтобы не прерывать запросы, которые все еще штатно обрабатываются (и за которые по-прежнему списывается плата).

Как работает модерация контента и как распознать блокировку?

В этом семействе применяется модерация контента. Заблокированные запросы возвращают 400 invalid_request с точно таким же кодом ошибки и сообщением, как при ошибке в параметрах, поэтому по телу ответа различить их невозможно.Практический ориентир — это время задержки: блокировки модерации возвращаются примерно через 5–6 секунд (проверка выполняется до генерации), тогда как успешная генерация изображения занимает около 9 секунд. Результаты модерации также содержат элемент случайности, поэтому пограничный контент может обрабатываться по-разному при повторных попытках — не делайте выводов на основе одного запроса.Если параметры проверены и корректны, а ошибки 400 продолжают возникать, вероятнее всего, prompt был заблокирован модерацией; скорректируйте формулировку.

Можно ли генерировать изображения через /v1/chat/completions?

Да, но это не рекомендуемый способ. Эндпоинт возвращает стандартную структуру чата, где content представляет собой ссылку на изображение в формате markdown:

![image](https://apac.ossforai.com/...)

Это удобно для диалоговых клиентов, таких как Chatbox или LobeChat. Для программной интеграции используйте Images API (/v1/images/generations и /v1/images/edits) — здесь доступен более широкий набор параметров, более стабильная структура ответа и полное соответствие данной документации.

Связанная документация

Grok Imagine 2 Текст-в-изображение API - справочник по эндпоинту с Playground
Grok Imagine 2 Редактирование изображений API - справочник по редактированию и объединению нескольких изображений
Руководство по модели Grok - текстовые модели xAI
Лучшие практики Image API - тайм-ауты, разрывы соединения, сжатие
Руководство по API
Акции на пополнение

​Обзор

API генерации изображений по тексту

API редактирования изображений

​Доверьте интеграцию ИИ-агенту

​Почему Grok Imagine 2 на APIYI

Формат, совместимый с OpenAI

Без ограничений на параллельные запросы

Фиксированная цена, предсказуемая стоимость

Глобальный доступ без барьеров

Полная экосистема моделей

Профессиональная поддержка

​Ключевые особенности

Два уровня разрешения

5 соотношений сторон

До 10 изображений за запрос

Быстрая генерация

Точное редактирование по референсу

Объединение нескольких изображений

Два формата ответа

Совместимость с OpenAI SDK

​Примеры результатов

​Цены

​Эффективная стоимость с бонусами за пополнение

​Настройка группы

​Кто может получить доступ

​Как подать заявку

​Технические характеристики

​Эндпоинты

​Миграция с GPT-Image-2

​Сопоставление параметров

​Три самые распространённые ошибки

​До и после

​Ключевые параметры

​aspect_ratio и resolution (размер вывода)

​n (изображений за вызов)

​Лучшие практики

​Коды ошибок и повторные попытки

​Часто задаваемые вопросы

​Связанная документация

Обзор

Доверьте интеграцию ИИ-агенту

Почему Grok Imagine 2 на APIYI

Ключевые особенности

Примеры результатов

Цены

Эффективная стоимость с бонусами за пополнение

Настройка группы

Кто может получить доступ

Как подать заявку

Технические характеристики

Эндпоинты

Миграция с GPT-Image-2

Сопоставление параметров

Три самые распространённые ошибки

До и после

Ключевые параметры

`aspect_ratio` и `resolution` (размер вывода)

`n` (изображений за вызов)

Лучшие практики

Коды ошибок и повторные попытки

Часто задаваемые вопросы

Связанная документация