Генерация и редактирование изображений Grok Imagine 2

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

Обзор

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

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

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

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

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

ID моделей не содержат 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 изображений являются синхронными: async ID задачи отсутствует, поэтому при отключении клиента результат теряется, хотя запрос всё равно тарифицируется. Установите достаточно большой timeout — смотрите Рекомендации по работе с Image API.

API преобразования текста в изображение

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

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

Загружайте референсные изображения вместе с инструкцией, используйте объединение 1–4 изображений и песочницу.

Поручите интеграцию AI-агенту

Если вы работаете с Codex / Claude Code / Cursor, скопируйте текст ниже и передайте его агенту. Сначала он получит текстовую версию этой страницы (добавьте .md к любому docs URL), затем напишет код в стеке вашего проекта — таймаут, немедленное повторное размещение результатов по URL, эндпоинт, который молча отбрасывает reference images, но всё равно тарифицирует вас, и тот факт, что size ничего не делает, уже заложены в требования.

Поручите кодирующему агенту интеграцию или устранение неполадок Grok Imagine 2 для генерации изображений по тексту и редактирования изображений. Скопируйте и вставьте это в Codex, Claude Code, Cursor и аналогичные инструменты.

От чего вас защищает этот промпт

Требование	Какую ошибку это предотвращает
Reference images только на edit endpoint	Отправка их на `/v1/images/generations` возвращает 200, молча отбрасывает reference и всё равно тарифицирует вас — самая дорогая ловушка здесь, именно потому, что ошибок нет
Никогда не отправляйте `size`	Он молча игнорируется, поэтому вы думаете, что задали размер, а получаете квадрат 1024 на 1024
Идентификатор модели без цифры 2	`grok-imagine-2-image` возвращает 503, что выглядит как сбой, но на самом деле это просто неверное имя
Higher fidelity — это модель, а не параметр	У этой модели нет параметра `quality`; если отправить его, он будет молча проигнорирован
Не сверяйте стоимость по `usage`	Это заглушка с фиксированным `prompt_tokens`, равным 1000, умноженным на n; используйте записи тарификации в консоли
Таймаут по-прежнему установлен на 360s	Задержка около 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 RPM работает без проблем

Настоящее редактирование по референсу

Изменяет только то, что вы просите — арт-стиль, композиция, палитра и идентичность объекта остаются неизменными

Слияние нескольких изображений

Эндпоинт редактирования принимает 1-4 референса — каждый из них при тестировании добавляет объект, а первый задает размеры вывода

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

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

OpenAI SDK готов к работе

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

Цены

Модель	Разрешение	Цена 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 (коэффициент тарифа 1,0x, как указано в приведённой выше таблице цен), и доступ к нему необходимо запросить.

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

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

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

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

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

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

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

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

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

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

Что происходит до предоставления доступа: Token без группы Grok_imagine возвращает 503 (в текущей группе нет доступного канала). Повторные попытки не помогут — сначала необходимо включить группу.Рекомендуемая модель тарификации Token: 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

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

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

Основной домен https://api.apiyi.com, резервный https://vip.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`	Недопустимые параметры или промпт заблокирован модерацией	Один и тот же код для обоих случаев — сначала проверьте параметры, затем измените промпт
`415`	—	Неподдерживаемое имя поля файла на эндпоинте редактирования	Переименуйте поле в `image` или `image[]`
`429`	—	Превышен лимит запросов или недостаточный баланс	Экспоненциальная задержка между попытками и проверка баланса аккаунта
`503`	`model_service_unavailable`	Неподдерживаемый уровень параметра (например, `resolution: 4k`)	Это не сбой — вернитесь к `1k` / `2k` и не повторяйте запрос
`503`	—	В token отсутствует группа `Grok_imagine`	Это проблема разрешений, а не сбой — повторные попытки не помогут; примените настройку через Настройка группы

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

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

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

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

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

Потому что эндпоинт редактирования шлюза APIYI принимает только multipart/form-data, тогда как в документации поставщика upstream описано тело 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 редактирования изображений.

Я отправил эталонное изображение в text-to-image и получил 200, но результат не имеет к нему отношения?

Это ожидаемое поведение и самая распространённая ошибка при работе с этой моделью: /v1/images/generations молча игнорирует image / image_url / images, генерирует изображение только по промпту и обычным образом списывает оплату.При отсутствии сигнала об ошибке легко решить, что «редактирование не работает». Любой рабочий процесс с эталонным изображением должен использовать /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 — никогда оба поля одновременно.Не предполагайте наличие этих полей при разборе ответов.

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

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

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

Это поведение upstream: 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 не вызывает ошибку, но не влияет на результат — один и тот же промпт с одинаковым seed возвращает разные изображения при разных вызовах.Сохраняйте изображения, которые нужно использовать повторно, вместо попыток сгенерировать их заново.

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

Да. Оба эндпоинта совместимы с 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 не являются стандартными полями OpenAI SDK, поэтому передавайте их через extra_body.

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

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

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

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

Можно ли генерировать изображения через /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 редактирования изображений

​Поручите интеграцию AI-агенту

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

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

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

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

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

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

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

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

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

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

До 10 за один вызов

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

Настоящее редактирование по референсу

Слияние нескольких изображений

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

OpenAI SDK готов к работе

​Цены

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

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

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

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

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

​Эндпоинты

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

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

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

​До и после

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

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

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

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

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

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

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

Обзор

Поручите интеграцию AI-агенту

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

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

Цены

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

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

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

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

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

Эндпоинты

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

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

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

До и после

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

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

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

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

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

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

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