> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

## Обзор

**Grok Imagine 2** — это новейшая, второго поколения, модель для генерации изображений xAI — полноценный шаг вперёд по сравнению с первым релизом как в управлении параметрами, так и в редактировании: соотношение сторон и разрешение действительно применяются, доступен уровень 2K, один вызов возвращает до 10 изображений, а редактирование по референсу действительно сохраняет исходное изображение.

APIYI предлагает два варианта: `grok-imagine-image` (стандартная) и `grok-imagine-image-quality` (высокого качества). Оба используют одни и те же эндпоинты и параметры — различаются только точностью вывода и ценой.

<Note>
  **Преимущества**: фиксированная цена за запрос (**1K и 2K стоят одинаково**), 5 соотношений сторон x 2 уровня разрешения, которые **действительно применяются**, до 10 изображений за вызов и высокоточное редактирование по референсу, сохраняющее художественный стиль, композицию, палитру и идентичность объекта. На создание изображения 1K уходит примерно 9 секунд.
</Note>

<Info>
  **Идентификаторы модели не содержат `2`.** Продукт называется Grok Imagine 2, но вызываемые вами имена моделей — **`grok-imagine-image`** и **`grok-imagine-image-quality`** — не указывайте `grok-imagine-2-image`, так как это вернёт 503, потому что такой модели не существует.
</Info>

<Warning>
  **📌 Прочитайте это сначала**: **референсные изображения работают только с эндпоинтом редактирования `/v1/images/edits` — никогда не с text-to-image.**

  Передача `image` / `image_url` / `images` в `/v1/images/generations` возвращает **200 с совершенно обычным изображением**, но референс **молча отбрасывается**, и с вас всё равно взимается тарификация — без какой-либо ошибки. См. [Эндпоинты](#endpoints) ниже.
</Warning>

<Info>
  Все API для изображений **синхронные**: идентификатора асинхронной задачи нет, поэтому если клиент отключится, результат будет потерян, хотя запрос всё равно тарифицируется. Установите достаточно большой timeout — см. [Лучшие практики API для изображений](/ru/api-capabilities/image-api-best-practices).
</Info>

<CardGroup cols={2}>
  <Card title="API генерации изображений по тексту" icon="wand-sparkles" href="/ru/api-capabilities/grok-imagine-image/text-to-image">
    Генерируйте изображения по text prompt, с интерактивным Playground для тестирования в реальном времени.
  </Card>

  <Card title="API редактирования изображений" icon="image" href="/ru/api-capabilities/grok-imagine-image/image-edit">
    Загрузите референсные изображения и инструкцию, с объединением 1–3 изображений и Playground.
  </Card>
</CardGroup>

## Why Grok Imagine 2 on APIYI

<CardGroup cols={2}>
  <Card title="Формат, совместимый с OpenAI" icon="shield-check">
    Стандартные `/v1/images/generations` и `/v1/images/edits` эндпоинты. Формат запроса и поля ответа совпадают с OpenAI Images API, так что официальный OpenAI SDK работает напрямую — без миграции.
  </Card>

  <Card title="Без ограничений на параллельные запросы" icon="infinity">
    Жёстких лимитов RPM/RPD нет. **Комфортно измерено на уровне 100 RPM** при достаточной пропускной способности канала, поэтому пакетные нагрузки масштабируются линейно — не нужны запросы на квоту или искусственное ограничение скорости.
  </Card>

  <Card title="Фиксированная тарификация, предсказуемая стоимость" icon="percent">
    Фиксированная цена за изображение, **не зависит от разрешения** — изображение 2K стоит столько же, сколько 1K. Планируйте бюджет по точному числу изображений и используйте [бонусы за пополнение](/ru/faq/recharge-promotions), чтобы снизить его ещё сильнее.
  </Card>

  <Card title="Глобальный доступ, без барьеров" icon="globe">
    **Не требуется зарубежный сервер или proxy.** Материковые дата-центры, домашний широкополосный интернет и зарубежные узлы напрямую подключаются к `api.apiyi.com`.
  </Card>

  <Card title="Полная экосистема моделей" icon="layers">
    Также доступны: [Nano Banana 2](/ru/api-capabilities/nano-banana-2-image/overview), [GPT-Image-2](/ru/api-capabilities/gpt-image-2/overview), [Seedream](/ru/api-capabilities/seedream-image/overview), [FLUX](/ru/api-capabilities/flux/overview), а также [текстовые модели Grok](/ru/api-capabilities/grok/overview).
  </Card>

  <Card title="Профессиональная поддержка" icon="handshake">
    Наша команда глубоко работает с нагрузками генерации изображений и может поддержать корпоративных клиентов от PoC до вывода в production.
  </Card>
</CardGroup>

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

<CardGroup cols={2}>
  <Card title="Два уровня разрешения" icon="expand">
    `1k` примерно 1 мегапиксель, `2k` 4.2-4.5 мегапикселя (2816x1584 при 16:9) — **одинаковая цена**
  </Card>

  <Card title="5 соотношений сторон" icon="maximize">
    `1:1` / `16:9` / `9:16` / `4:3` / `3:4`, с точным совпадением размеров в пикселях
  </Card>

  <Card title="До 10 за один вызов" icon="images">
    `n` принимает 1-10, возвращая несколько изображений в одном запросе — идеально для пакетного выбора
  </Card>

  <Card title="Быстрая генерация" icon="zap">
    Около 9 с при 1K и 15-17 с при 2K, со стабильной задержкой под нагрузкой — 100 RPM работает без проблем
  </Card>
</CardGroup>

<CardGroup cols={2}>
  <Card title="Полноценное редактирование по референсу" icon="wand">
    Меняет только то, что вы укажете — художественный стиль, композиция, палитра и идентичность объекта остаются неизменными
  </Card>

  <Card title="Слияние нескольких изображений" icon="layers-2">
    Эндпоинт редактирования принимает 1-3 референсных изображения, например помещая объект из изображения A в сцену и стиль изображения B
  </Card>

  <Card title="Два формата ответа" icon="file-json">
    `url` прямые ссылки или `b64_json` raw base64, поддерживаемые на обоих эндпоинтах
  </Card>

  <Card title="Готово для OpenAI SDK" icon="plug">
    `client.images.generate()` и `client.images.edit()` работают из коробки — без ручной настройки HTTP
  </Card>
</CardGroup>

## Тарифы

| Model                            | Тарификация                  | Цена APIYI                | Примечания                                         |
| -------------------------------- | ---------------------------- | ------------------------- | -------------------------------------------------- |
| **`grok-imagine-image`**         | Фиксированная цена за запрос | **\$0.02 / изображение**  | Стандартный уровень, выбор по умолчанию            |
| **`grok-imagine-image-quality`** | Фиксированная цена за запрос | **\$0.045 / изображение** | Уровень высокого качества для требовательных задач |

<Info>
  **Примечания по тарификации**

  * **Независимо от разрешения**: `1k` и `2k` стоят одинаково — за 2K не взимается доплата.
  * **За каждое изображение**: `n=4` тарифицируется как 4 изображения, независимо от длины prompt.
  * **Редактирование стоит столько же**, сколько text-to-image — за `/v1/images/edits` не взимается надбавка.
  * **Блок `usage` нельзя использовать для сверки**: `prompt_tokens` всегда `1000 x n`, это заглушка. Вместо этого используйте записи тарификации в консоли.
</Info>

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

Grok Imagine 2 работает в **`Default` группе (коэффициент тарифа 1.0x)**, что соответствует таблице тарификации выше. **Переключение группы не требуется.**

**Рекомендуемая модель тарификации Token**: `Pay-as-you-go Priority`. Эта серия тарифицируется за каждый запрос, и оба маршрута — Pay-as-you-go Priority и Pay-per-request — работают корректно; если выбрать Pay-as-you-go Priority, один Token также сможет покрывать модели с тарификацией token в других местах платформы.

<Tip>
  Если ваш Token уже покрывает другие модели генерации изображений, просто оставьте `Default` основной группой. Для этой серии не требуется отдельная группа или дополнительная настройка.
</Tip>

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

| Пункт                                | Спецификация                                              |
| ------------------------------------ | --------------------------------------------------------- |
| Идентификаторы моделей               | `grok-imagine-image`, `grok-imagine-image-quality`        |
| Соотношения сторон                   | 5: `1:1` / `16:9` / `9:16` / `4:3` / `3:4`                |
| Уровни разрешения                    | `1k` (\~0.9-1.05 MP), `2k` (\~4.2-4.5 MP)                 |
| Формат вывода                        | **JPEG на 1K (\~220-300 KB), PNG на 2K (\~5-6 MB)**       |
| Изображений за вызов                 | `n` 1-10                                                  |
| Референсные изображения              | 1-3 на эндпоинте редактирования (повторяющийся `image[]`) |
| Инпейнтинг маски                     | ❌ Не поддерживается                                       |
| Воспроизводимый `seed`               | ❌ Не поддерживается                                       |
| Эхо `revised_prompt`                 | ❌ Не возвращается                                         |
| Задержка                             | \~9s на 1K, \~15-17s на 2K                                |
| Параллельные запросы / rate          | Без ограничений; **замерено с запасом на уровне 100 RPM** |
| Рекомендуемое время ожидания клиента | 360 секунд или более                                      |

## Endpoints

| Возможность           | Метод  | Путь                     | Content-Type              |
| --------------------- | ------ | ------------------------ | ------------------------- |
| Text-to-image         | `POST` | `/v1/images/generations` | `application/json`        |
| Image editing         | `POST` | `/v1/images/edits`       | **`multipart/form-data`** |
| Chat-style generation | `POST` | `/v1/chat/completions`   | `application/json`        |

<Warning>
  **✅ Эндпоинт редактирования требует загрузки файла `multipart/form-data`**

  Отправка JSON на `/v1/images/edits` **всегда возвращает 400**:

  ```text theme={null}
  request Content-Type isn't multipart/form-data
  ```

  **Это особенно важно, если вы интегрируете решение по документации исходного вендора** — в той документации описано JSON-основное тело с публичным URL изображения, которое через шлюз APIYI **не работает**. **Следуйте этой странице вместо этого**: загрузите файл с помощью `-F "image=@photo.jpg"`. Полные примеры в [API редактирования изображений](/ru/api-capabilities/grok-imagine-image/image-edit).

  Поле файла должно называться `image` или `image[]`; `images` / `image_file` возвращают 415.
</Warning>

<Warning>
  **⚠️ Никогда не отправляйте референсные изображения в эндпоинт генерации изображений по тексту**

  Когда `/v1/images/generations` получает `image` / `image_url` / `images`, он не возвращает ошибку. Он возвращает 200 и генерирует совершенно новое изображение только по prompt, полностью игнорируя ваш референс — **и тарифицирует вас как обычно**.

  Поскольку сигнала об ошибке нет, это обычно обнаруживается только тогда, когда кто-то замечает, что результат никак не связан со входными данными. **Любой рабочий процесс с использованием референсного изображения должен использовать `/v1/images/edits`.**
</Warning>

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

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

Если вы уже интегрировали [GPT-Image-2](/ru/api-capabilities/gpt-image-2/overview), **эндпоинты и соглашение вызова идентичны** (`/v1/images/generations` + `/v1/images/edits`, совместимо с OpenAI SDK) — но **система параметров отличается**, поэтому простая замена названия модели не сработает. Вот что нужно изменить.

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

| Аспект                                   | 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**                               | ✅ Вы можете убрать цикл fan-out на стороне клиента                                 |
| Референсные изображения (редактирование) | До 16                                                  | **До 3**                                                | ⚠️ Переработайте потоки, которые отправляют больше 3                               |
| Инпейтинг по маске                       | ✅ Поддерживается                                       | ❌ **Не поддерживается**                                 | ⚠️ Потоки, зависящие от маски, не могут быть перенесены                            |
| Тарификация                              | За token (\~\$0.21/изображение на высоком)             | **Фиксированная цена за запрос**, \$0.02 / \$0.045      | Модель расчёта бюджета меняется с оплаты по использованию на оплату за изображение |

### Три самые частые ошибки

<Warning>
  **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`, после миграции будет выдавать неверные числа.
</Warning>

<Warning>
  **2. `size` молча игнорируется вместо выдачи ошибки**

  GPT-Image-2 строго проверяет параметры и обычно возвращает 400 при неверном вводе. **Grok Imagine 2 более снисходителен**: поля в стиле OpenAI, такие как `size`, `quality` и `style`, **молча игнорируются**, а некорректные значения `aspect_ratio` / `resolution` **молча сбрасываются к значениям по умолчанию**.

  Поэтому, если вы измените только `model` и забудете удалить `size: "1536x1024"`, запрос **вернёт 200 с квадратным изображением 1024x1024** — и ничто не сообщит вам, что параметр был проигнорирован.

  После миграции **обязательно проверьте размеры изображения в пикселях при первом вызове**, чтобы убедиться, что `aspect_ratio` / `resolution` действительно вступили в силу.
</Warning>

<Warning>
  **3. Референсные изображения больше нельзя отправлять в эндпоинт text-to-image**

  Эта ловушка характерна именно для этой модели: отправка референсного изображения в `/v1/images/generations` возвращает **200, молча отбрасывает референс и всё равно тарифицирует вас**. Каждый вызов с референсным изображением должен использовать `/v1/images/edits` с `multipart/form-data` — см. [Эндпоинты](#endpoints) выше.
</Warning>

### До и после

```python theme={null}
# 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)
```

<Tip>
  **Что выбрать?** Оставайтесь на [GPT-Image-2](/ru/api-capabilities/gpt-image-2/overview), если вам нужен инпейтинг по маске, пользовательские размеры с точностью до пикселя или смешивание до 16 референсов. Выбирайте Grok Imagine 2 ради **предсказуемой стоимости** (фиксированная цена за изображение, без доплаты за 2K), **нескольких изображений за один вызов** (`n` до 10) или **высокой точности исходника при редактировании**. Эти два варианта сосуществуют — одни и те же вызовы Token работают для обоих.
</Tip>

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

### `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        |

<Warning>
  **Оба параметра применяются только к text-to-image.** На `/v1/images/edits` они принимаются без ошибки, но **не имеют эффекта** — результат редактирования всегда совпадает **с размерами входного референсного изображения** (1280x720 на входе, 1280x720 на выходе). Чтобы изменить размер вывода, обрежьте или измените размер референсного изображения перед загрузкой.
</Warning>

<Info>
  **Проверка выполняется мягко — опечатки не вызывают ошибок.** Значения вне enum для `aspect_ratio` (например, `5:7`, `21:9`) или `resolution` (например, `1K`, `1024x1024`) **тихо откатываются к значению по умолчанию** и всё равно возвращают изображение. Неверный `response_format` также откатывается к `url`. Поэтому, если вывод не соответствует ожиданиям, **сначала проверьте написание параметров**.

  Единственное исключение — `resolution: "4k"`, который возвращает `503 model_service_unavailable`. Это означает, что **уровень не поддерживается**, а не то, что канал недоступен — переключитесь обратно на `1k` / `2k`.
</Info>

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

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

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

<Steps>
  <Step title="Сразу определитесь: генерация или редактирование?">
    Нет опорного изображения → `/v1/images/generations`. Любое опорное изображение, даже для изменения на один пиксель → `/v1/images/edits`. При выборе неверного эндпоинта ошибки не будет — просто получится неожиданное изображение.
  </Step>

  <Step title="Установите тайм-аут клиента на 360 секунд">
    API для изображений синхронны. 2K занимает 15-17 секунд и может выполняться дольше в периоды пиковой нагрузки или при cold starts. Тайм-аут в 60 секунд приводит к ложным сбоям в запросах, по которым все еще идет тарификация.
  </Step>

  <Step title="Контролируйте композицию через aspect_ratio, а не через prompt">
    Параметр действительно работает, поэтому `aspect_ratio: "16:9"` гораздо надежнее, чем просить в prompt «альбомную композицию».
  </Step>

  <Step title="Выбирайте уровень разрешения с учетом пропускной способности">
    2K — это PNG без потерь размером 5-6 МБ на изображение; 1K — это JPEG размером 220-300 КБ — примерно в 20 раз меньше. Для мобильных устройств или массовой передачи лучше выбирать 1K. Поскольку оба уровня стоят одинаково, выбор — это только компромисс между качеством и пропускной способностью.
  </Step>

  <Step title="Говорите «оставьте все остальное без изменений» при редактировании">
    Инструкции вроде «поменяйте шарф на красный, а все остальное оставьте точно таким же» работают очень хорошо — модель строго следует этому ограничению и сохраняет остальную часть изображения.
  </Step>

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

  <Step title="Не полагайтесь на seed для воспроизводимости">
    Эта линейка не поддерживает `seed`; один и тот же prompt дает разные результаты при каждом вызове. Сохраняйте изображения, которые хотите оставить, вместо того чтобы рассчитывать на их повторную генерацию.
  </Step>

  <Step title="Просто используйте параллельные запросы для пакетной обработки">
    Ограничений на параллельные запросы нет — **100 RPM работает без проблем** при достаточной пропускной способности канала. Не нужно выстраивать последовательную очередь или запрашивать дополнительную квоту.
  </Step>
</Steps>

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

| 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, см. раздел «Настройка группы» выше                 |

<Info>
  **Рекомендации для клиента**: `400` и `415` — детерминированные, поэтому повторять бессмысленно, вместо этого отправляйте уведомление. Повторять стоит только `429` и тайм-ауты на уровне сети, с экспоненциальной задержкой между повторами и не более 3 попыток.

  Обратите внимание, что `400 invalid_request` охватывает и «неверный параметр», и «контент заблокирован», и **тело ответа не позволяет различить их**. Практический эвристический признак — задержка: блоки модерации возвращаются примерно за 5–6 секунд — быстрее, чем успешная генерация (\~9s), — потому что блокировка происходит до начала генерации.
</Info>

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

<AccordionGroup>
  <Accordion title="Почему отправка JSON в /v1/images/edits возвращает 400, если в документации вендора указан JSON?">
    Потому что **эндпоинт редактирования шлюза APIYI принимает только `multipart/form-data`**, тогда как upstream-документация вендора описывает JSON-тело с публичным URL изображения. Это разные варианты — следуйте документации этого сайта.

    Правильный формат — загрузка файла:

    ```bash theme={null}
    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 "image=@photo.jpg"
    ```

    Преимущество в том, что вам **не нужен хостинг изображений** — загрузите локальный файл напрямую, что проще, чем подготавливать публичный URL. Полные примеры в [API редактирования изображений](/ru/api-capabilities/grok-imagine-image/image-edit).
  </Accordion>

  <Accordion title="Я отправил референсное изображение в text-to-image и получил 200, но результат не связан с запросом?">
    Это ожидаемое поведение и **самая распространенная ловушка** в этой модели: `/v1/images/generations` **молча игнорирует** `image` / `image_url` / `images`, генерирует только по prompt и **тарифицирует как обычно**.

    Без сигнала об ошибке легко сделать вывод, что «редактирование сломано». **Любой workflow с референсным изображением должен использовать `/v1/images/edits`.**
  </Accordion>

  <Accordion title="Почему resolution / aspect_ratio не влияют на эндпоинт редактирования?">
    Размеры результата редактирования **следуют за входным референсным изображением**: 1280x720 на входе дает 1280x720 на выходе, 1024x1024 на входе дает 1024x1024 на выходе. Передача `resolution` или `aspect_ratio` здесь не вызывает ошибки, но ничего не делает.

    Чтобы изменить размер выхода, обрежьте или измените размер референсного изображения перед загрузкой.
  </Accordion>

  <Accordion title="Почему в ответе нет revised_prompt?">
    Эта серия **не** возвращает `revised_prompt`, а также поля вроде `respect_moderation` или `model`. Каждая запись `data[]` содержит **либо** `url` **либо** `b64_json` в зависимости от `response_format` — никогда оба сразу.

    Не предполагайте, что эти поля существуют при разборе ответов.
  </Accordion>

  <Accordion title="Могу ли я сверить тарификацию по количеству token в usage?">
    **Нет.** `usage.prompt_tokens` всегда равно `1000 x n` независимо от фактической длины prompt — это заполнитель.

    Эта серия тарифицируется **за запрос** по фиксированной цене за изображение. Для фактических списаний используйте записи тарификации в консоли APIYI.
  </Accordion>

  <Accordion title="Почему 1K — это JPEG, а 2K — PNG? Размеры сильно отличаются">
    Это поведение upstream: `resolution: 1k` возвращает JPEG (\~220-300 KB), а `resolution: 2k` возвращает без потерь PNG (\~5-6 MB), то есть примерно в 20 раз больше.

    Расширение URL, HTTP `Content-Type` и фактические байты согласованы друг с другом, поэтому вы можете безопасно ветвиться по `Content-Type`.

    Для сценариев, чувствительных к трафику (мобильные устройства, массовая передача), предпочитайте `1k` — оба уровня стоят одинаково, так что выбор зависит только от качества.
  </Accordion>

  <Accordion title="resolution: 4k возвращает 503 — канал недоступен?">
    **Нет.** `4k` не является поддерживаемым уровнем для этой серии, и шлюз возвращает `503 model_service_unavailable`. Код выглядит как сбой, но на самом деле это проблема параметра, так что **повторные попытки не помогут** — переключитесь обратно на `1k` или `2k`.

    Поддерживаются только `1k` и `2k`.
  </Accordion>

  <Accordion title="Почему неверные параметры приводят к неправильному изображению вместо ошибки?">
    Проверка в этой серии мягкая: неверные `aspect_ratio` (например, `5:7`), `resolution` (например, `1K`, `1024x1024`) и `response_format` (например, `base64`) все **молча откатываются к значениям по умолчанию** и по-прежнему возвращают изображение, а не 400.

    Поэтому, когда результат не соответствует ожиданиям, **сначала проверьте написание параметров** — в частности, значения `resolution` пишутся в нижнем регистре: `1k` / `2k`.
  </Accordion>

  <Accordion title="Сколько изображений может создать один вызов?">
    `n` принимает **1-10**, а длина возвращаемого массива `data` равна `n`. Каждое изображение **тарифицируется**.

    `0` без предупреждения трактуется как `1`; `11` и выше возвращает `400 invalid_request`.
  </Accordion>

  <Accordion title="Поддерживается ли воспроизводимость на основе seed?">
    **Нет.** Передача `seed` не вызывает ошибки, но не имеет эффекта — один и тот же prompt с одним и тем же `seed` возвращает разные изображения при каждом вызове.

    Сохраняйте любое изображение, которое нужно будет повторно использовать, вместо того чтобы пытаться сгенерировать его заново.
  </Accordion>

  <Accordion title="Могу ли я вызывать это через официальный OpenAI SDK?">
    Да. Оба эндпоинта совместимы с OpenAI Images API — просто укажите `base_url` на `https://api.apiyi.com/v1`:

    ```python theme={null}
    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`.
  </Accordion>

  <Accordion title="Есть ли ограничения на concurrency? Будет ли batch generation ограничиваться?">
    **Ограничений на concurrency нет.** **Комфортно измерено на уровне 100 RPM** без 429 и без отклонений в очереди, при этом доступна достаточная пропускная способность канала. Вызывайте параллельно, не выстраивая последовательную очередь и не запрашивая дополнительную квоту.

    На самом деле важно **`timeout`**: image APIs синхронны, поэтому установите timeout клиента на **360 seconds**, чтобы не обрывать запросы, которые еще нормально обрабатываются — и все еще тарифицируются.
  </Accordion>

  <Accordion title="Как работает модерация контента и как определить блокировку?">
    Эта серия применяет модерацию контента. Заблокированные запросы возвращают `400 invalid_request` с **точно таким же кодом ошибки и сообщением, как при ошибке параметра**, поэтому по телу ответа их нельзя различить.

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

    Если параметры проверены и 400 продолжает повторяться, значит, prompt, скорее всего, вызвал модерацию; измените формулировку.
  </Accordion>

  <Accordion title="Могу ли я генерировать изображения через /v1/chat/completions?">
    Да, но это **не рекомендуемый путь**. Эндпоинт возвращает стандартную структуру чата, где `content` — markdown-ссылка на изображение:

    ```text theme={null}
    ![image](https://apac.ossforai.com/...)
    ```

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

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

* [API Grok Imagine 2 для генерации изображений по тексту](/ru/api-capabilities/grok-imagine-image/text-to-image) - справочник по эндпоинту с Playground
* [API Grok Imagine 2 для редактирования изображений](/ru/api-capabilities/grok-imagine-image/image-edit) - справочник по редактированию и объединению нескольких изображений
* [Руководство по Grok](/ru/api-capabilities/grok/overview) - текстовые модели xAI
* [Лучшие практики для Image API](/ru/api-capabilities/image-api-best-practices) - тайм-ауты, разрывы соединения, сжатие
* [Руководство по API](/ru/api-manual)
* [Акции на пополнение](/ru/faq/recharge-promotions)