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

> Полное руководство по официальному каналу Grok Imagine на APIYI: grok-imagine-image / grok-imagine-image-quality / grok-imagine-image-2.0, цены как у xAI и тарификация по разрешению (1k / 1.5k / 2k) и уровню качества (low / medium), $0.02–0.08 за изображение. Требуется группа GrokOfficial по заявке.

## Обзор

**Grok Imagine Official** — это **официальный канал** для моделей генерации изображений xAI: запросы пересылаются через APIYI в официальный API xAI, **цены соответствуют официальному прайс-листу xAI**, тарификация зависит от разрешения и уровня качества, а валидация параметров полностью идентична апстриму.

Доступны три модели: стандартная `grok-imagine-image`, высококачественная `grok-imagine-image-quality` и более новая **`grok-imagine-image-2.0`** (с уровнями качества `low` / `medium`).

> [!WARNING]
>
> **🔒 Для этого канала требуется группа `GrokOfficial`, доступная по заявке**
>
> Grok Imagine Official не входит в группу `Default`. Политика безопасности контента этого семейства существенно отличается от других моделей на платформе, поэтому для снижения комплаенс-рисков доступ предоставляется **выборочно**:
>
> * **Действующие клиенты с совокупными расходами от \$1,000**: обратитесь в службу поддержки и опишите ваш сценарий использования — мы включим доступ после проверки
> * **Остальные пользователи**: подайте заявку через [поддержку WeCom](https://work.weixin.qq.com/kfid/kfc9adfd5810ece25ec), указав ваш **сценарий использования** и **инструменты модерации контента**; доступ будет открыт после одобрения
>
> Token без группы `GrokOfficial` возвращает ошибку **`503`** — это проблема с правами доступа, а не сбой в работе сервиса. См. раздел [Настройка групп](#group-setup) ниже.

> [!TIP]
>
> **Официальный релей или reverse?** На этой странице описан официальный канал: цены соответствуют xAI, тарификация по уровням качества, поддержка `grok-imagine-image-2.0`, и **на данный момент поддерживается только text-to-image, по одному изображению за запрос**. Если вам требуется **редактирование изображений или генерация нескольких изображений за запрос**, либо более низкая фиксированная цена (\$0.02 / \$0.045 за изображение независимо от разрешения), используйте [Grok Imagine Reverse](/ru/api-capabilities/grok-imagine-image/overview). См. [Сравнение официального релея и reverse](#official-vs-reverse) для подробного сопоставления.

> [!NOTE]
>
> Все API генерации изображений являются **синхронными**: асинхронный ID задачи отсутствует, поэтому при отключении клиента результат будет потерян, но запрос все равно тарифицируется. `grok-imagine-image-2.0` с качеством `medium` и разрешением 2K в наших тестах занимает около 60–80 секунд, поэтому задавайте для этой модели достаточно большой таймаут. См. [Примечания и рекомендации по API генерации изображений](/ru/api-capabilities/image-api-best-practices).

> **[API Text-to-Image](/ru/api-capabilities/grok-imagine-image-official/text-to-image)**
>
> Генерация изображений по текстовому prompt с интерактивной площадкой Playground.

> **[Grok Imagine Video](/ru/api-capabilities/grok-imagine-video/overview)**
>
> Та же группа `GrokOfficial` — text-to-video и image-to-video с посекундной тарификацией.

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

Интегрируйте / устраните неполадки генерации изображений по тексту Grok Imagine Official в этом проекте.

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

Требования:

1. Выберите одну модель: `grok-imagine-image` (стандартная), `grok-imagine-image-quality` (высокое качество) или `grok-imagine-image-2.0` (более новая, с двумя уровнями `quality`). Группа Token должна включать `GrokOfficial`, иначе каждый вызов будет возвращать 503.

2. Таймаут: установите клиентский таймаут на 360 секунд с запасом надежности. `grok-imagine-image` занимает около 8 секунд, а `-quality` — около 7–12 секунд, но `grok-imagine-image-2.0` при `medium` и 2K занимает 60–80 секунд. API генерации изображений является синхронным: если клиент отключается, результат теряется, а за запрос все равно списывается плата. Увеличьте лимиты также на обратных прокси, шлюзах и в бессерверных средах выполнения.

3. Эндпоинт: используйте только `/v1/images/generations` (JSON) для генерации изображений по тексту. **Не отправляйте референсные изображения в этот эндпоинт** (`image` / `image_url` и т. д.) — они будут просто проигнорированы. Этот канал пока не поддерживает редактирование изображений; для редактирования используйте обратный канал по адресу `/en/api-capabilities/grok-imagine-image/overview`.

4. Размер: управляйте выводом с помощью `resolution` (`1k` / `1.5k` / `2k`, строчными буквами) плюс `aspect_ratio` (например, `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`). **Не передавайте `size`** — он не сопоставляется с уровнем разрешения, поэтому изображение создается с разрешением 1k по умолчанию. Значения вне допустимого набора возвращают 422 вместо автоматического перехода на резервный вариант.

5. Качество: только `grok-imagine-image-2.0` имеет `quality`; передавайте только `low` (по умолчанию) или `medium`, но ни в коем случае не `auto` или `high` (`high` возвращает 400). Двум другим моделям `quality` не требуется — выберите саму модель, чтобы задать детализацию.

6. Количество: всегда передавайте `n` = 1. Для получения нескольких изображений отправляйте несколько запросов параллельно вместо использования `n`.

7. Обработка ответа: по умолчанию используется `url`; вы также можете передать `response_format: "b64_json"`. Если вы используете URL, сразу скачивайте и сохраняйте изображение на своем сервере, не сохраняя только ссылку. Поле `usage` является плейсхолдером (`prompt_tokens` всегда равно количеству изображений, умноженному на 1000) и **не может использоваться для сверки** — проверяйте записи тарификации в консоли.

8. Считывайте ключ из переменной окружения `APIYI_API_KEY` и используйте [https://api.apiyi.com/v1](https://api.apiyi.com/v1) в качестве base\_url; никогда не прописывайте его жестко в коде и не фиксируйте в git. По завершении выполните один реальный вызов генерации изображений по тексту и покажите мне результат и стоимость этого вызова.

## Модели и цены

Цены соответствуют прайс-листу xAI и взимаются **за изображение**; уровень определяется параметром `resolution` (а также `quality` для версии 2.0):

| Модель | Уровень качества | `1k` | `1.5k` | `2k` |
| - | - | - | - | - |
| **`grok-imagine-image`** | — | \$0.02 | \$0.02 | \$0.02 |
| **`grok-imagine-image-quality`** | — | \$0.05 | \$0.06 | \$0.07 |
| **`grok-imagine-image-2.0`** | `low` (по умолчанию) | \$0.04 | \$0.05 | \$0.06 |
| **`grok-imagine-image-2.0`** | `medium` | \$0.06 | \$0.07 | \$0.08 |

> [!NOTE]
>
> Цены на модели синхронизированы с официальными сайтами и могут меняться при их изменении; таблица выше приведена только для справки, а определяющей является вкладка **Цены на модели** в верхней панели навигации: [Цены на модели](/en/models/index).

> [!NOTE]
>
> **Примечания по тарификации**
>
> * **Значения по умолчанию**: для `resolution` по умолчанию используется `1k`; для `grok-imagine-image-2.0` — `quality: low`, то есть \$0.04 за изображение.
> * **За изображение, одно за запрос**: оставьте `n=1` на этом канале и используйте параллельные запросы, если требуется больше изображений.
> * **Неудачные запросы не тарифицируются**: ошибки параметров (422 / 400), отсутствие доступа к группе (503) и прочие ответы с ошибками бесплатны.
> * **Не сверяйте с `usage`**: `prompt_tokens` всегда имеет значение `1000 × image count` — это заглушка; определяющими являются записи тарификации в консоли.
> * Дополнительно действуют [многоуровневые бонусы за пополнение](/ru/faq/recharge-promotions); корпоративные клиенты с большими объемами могут обратиться в отдел продаж по вопросу индивидуальных тарифов.

## Официальный канал и реверс

APIYI предлагает как официальный, так и реверс-канал для Grok Imagine. **Они различаются группой, тарификацией и возможностями**:

| Параметр | **Официальный** (эта страница) | [**Реверс**](/ru/api-capabilities/grok-imagine-image/overview) |
| - | - | - |
| Группа | `GrokOfficial` (по заявке) | `Grok_imagine_Reverse` (по заявке) |
| Тарификация | **По официальным ценам xAI**, рассчитывается как «разрешение × уровень качества» | Фиксированная за изображение, независимо от разрешения |
| Модели | `grok-imagine-image` / `-quality` / **`-2.0`** | `grok-imagine-image` / `-quality` |
| Уровни разрешения | `1k` / `1.5k` / `2k` | `1k` / `2k` |
| Генерация по тексту | ✅ | ✅ |
| Редактирование изображений / слияние нескольких изображений | Пока не поддерживается | ✅ 1–4 референсных изображения |
| Несколько изображений за один вызов | Пока не поддерживается (`n=1`) | ✅ `n` до 10 |
| Валидация параметров | **Строгая**: значения вне допустимого диапазона возвращают 422 | Мягкая: недопустимые значения без ошибок сбрасываются до значений по умолчанию |

> [!TIP]
>
> **Как выбрать**: если вам требуется `grok-imagine-image-2.0`, нужна тарификация на условиях самого xAI или важно, чтобы опечатки приводили к явной ошибке → выбирайте официальный канал. Если вам нужны редактирование, несколько изображений за один вызов или минимальная цена за результат в разрешении 2K → выбирайте реверс-канал. Вы можете использовать обе группы и обращаться к каждой со своим Token.

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

> [!WARNING]
>
> **Grok Imagine Official не входит в группу `Default`.** Он находится в **группе `GrokOfficial` (такая же цена, как у xAI, см. таблицу выше)**, и для доступа необходимо подать заявку.

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

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

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

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

Подайте заявку через [поддержку в WeCom](https://work.weixin.qq.com/kfid/kfc9adfd5810ece25ec) или напишите на [hi@apiyi.com](mailto:hi@apiyi.com). Укажите, что подаете заявку на **`GrokOfficial` (Grok Imagine Official)**.

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

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

**3. Переключите группу Token после одобрения**

После одобрения мы включим `GrokOfficial` для вашего аккаунта. Перейдите на [страницу Token в консоли](https://api.apiyi.com/token), переключите используемый для этого канала Token на `GrokOfficial` и установите режим тарификации на `Pay-as-you-go Priority` или `Pay-as-you-go`.

> [!NOTE]
>
> **Как это выглядит до предоставления доступа**: Token без группы `GrokOfficial` возвращает **`503` (в текущей группе нет доступных каналов)**. Повторные попытки не помогут — сначала необходимо подключить группу.
>
> **Не используйте режим тарификации `Pay-per-request`**: этот канал тарифицируется по факту использования, поэтому Token с оплатой за запрос невозможно маршрутизировать, и он также вернет 503.

> [!NOTE]
>
> **Напоминание о соблюдении правил**: после предоставления доступа ответственность за сгенерированный контент лежит на вызывающей стороне. Соблюдайте местное законодательство и нормативные требования; не создавайте незаконный контент, материалы, нарушающие права на изображение граждан или интеллектуальную собственность, а также контент, не предназначенный для несовершеннолетних. Для сценариев с прямым доступом конечных пользователей добавьте собственный уровень модерации. Подробнее: [Примечания по соблюдению нормативных требований при вызове зарубежных моделей](/ru/faq/overseas-model-compliance). В случае выявления злоупотреблений доступ к группе аннулируется.

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

| Параметр | Значение |
| - | - |
| ID моделей | `grok-imagine-image`, `grok-imagine-image-quality`, `grok-imagine-image-2.0` |
| Эндпоинт | `POST /v1/images/generations` (`application/json`) |
| Уровни разрешения | `1k` (по умолчанию) / `1.5k` / `2k` |
| Соотношения сторон | Основные: `1:1` (по умолчанию) / `16:9` / `9:16` / `4:3` / `3:4` / `3:2` / `2:3` |
| Уровни качества | Только для `grok-imagine-image-2.0`: `low` (по умолчанию) / `medium` |
| Изображений за вызов | `n=1` |
| Формат ответа | `url` (по умолчанию) или `b64_json` |
| Валидация параметров | Строгая — значение `resolution` / `aspect_ratio` вне допустимого диапазона возвращает 422 |
| Задержка | `grok-imagine-image` около 8 с; `-quality` около 7 с при 1k и 12 с при 2k; `-2.0` `low` около 15–17 с, `medium` 2K около 60–80 с |
| Рекомендуемый таймаут клиента | ≥ 360 секунд |

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

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

Вместе они определяют итоговое разрешение в пикселях. Некоторые результаты измерений:

| Модель | Запрос | Фактический результат |
| - | - | - |
| `grok-imagine-image` | `1k` + `3:2` | 1248×832 (JPEG) |
| `grok-imagine-image-quality` | `2k` + `9:16` | 1584×2816 (PNG, около 6,7 МБ) |
| `grok-imagine-image-2.0` | `1.5k` + `16:9` + `medium` | 1792×1008 |

> [!WARNING]
>
> **Используйте `resolution`, а не `size`**
>
> Этот канал не сопоставляет `size` в стиле OpenAI (например, `"2048x2048"`) с уровнем разрешения: передача `size` не вызывает ошибки, но изображение генерируется и тарифицируется по умолчанию как `1k`. Для 2K явно передавайте `resolution: "2k"`.

> [!NOTE]
>
> **Ошибки приводят к явным сбоям**: в отличие от обратного канала, валидация параметров здесь соответствует xAI. Значения вне допустимого диапазона, такие как `resolution: "4k"` или `aspect_ratio: "5:7"`, возвращают ошибку **422** и не тарифицируются. Если вы столкнулись с ошибкой 422, сначала проверьте написание этих двух параметров (все строчными буквами: `1k` / `1.5k` / `2k`).

### `quality` (только `grok-imagine-image-2.0`)

| Значение | Примечания |
| - | - |
| `low` | По умолчанию, быстрее |
| `medium` | Выше детализация, на \$0.02 дороже за изображение, около 60–80 с при 2K |

Передача `high` возвращает 400 (`This model only supports the following quality value(s): low, medium, auto`). **Отправляйте только `low` или `medium`** — не отправляйте `auto`. `grok-imagine-image` и `grok-imagine-image-quality` не принимают `quality`; модель сама задает детализацию.

### `n` (количество изображений)

**Всегда передавайте `n=1`** в этом канале. Чтобы получить сразу несколько изображений, отправляйте несколько запросов одновременно — задержка стабильна, поэтому параллельные запросы масштабируются линейно.

## Рекомендации

**1. Экспериментируйте в 1k, финализируйте в 2k**

Запустите prompt несколько раз с `1k`, чтобы выбрать направление, а затем сгенерируйте итоговый вариант с `2k`. `grok-imagine-image-2.0` с `medium` и 2K занимает больше минуты, поэтому мало подходит для метода проб и ошибок.

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

API генерации изображений является синхронным. Таймаут в 60 секунд приведет к множеству ложных ошибок по таймауту на 2.0 `medium`, а запросы, прерванные клиентом, все равно тарифицируются.

**3. Используйте aspect\_ratio для кадрирования, а не prompt**

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

**4. Сохраняйте результаты по URL сразу же**

Сразу же скачивайте возвращенные ссылки на изображения в собственное хранилище на сервере; не используйте прямые ссылки на них постоянно и не передавайте их конечным пользователям.

**5. Переключитесь на reverse-канал для редактирования**

Этот канал пока не поддерживает редактирование изображений. Для правок по референсу и объединения нескольких изображений используйте `/v1/images/edits` в [Grok Imagine Reverse](/ru/api-capabilities/grok-imagine-image/overview).

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

| HTTP | Значение | Что делать |
| - | - | - |
| `400` | Недопустимое значение `quality` (например, `high`); в сообщении перечислены допустимые значения | Измените на `low` / `medium`; не повторяйте запрос |
| `422` | `resolution` / `aspect_ratio` вне допустимого набора | Проверьте написание и регистр; не повторяйте запрос |
| `429` | Превышен лимит запросов или недостаточно средств на балансе | Повторите попытку с экспоненциальной задержкой и проверьте баланс |
| `503` | У Token отсутствует группа `GrokOfficial` или Token использует тарификацию с оплатой за запрос | **Проблема с правами доступа, а не сбой** — повторные попытки не помогут; см. [Настройка группы](#group-setup) |

> [!NOTE]
>
> **Рекомендация для клиента**: `400` / `422` — детерминированные ошибки, повторять запрос бессмысленно, вместо этого настройте оповещения. Повторять попытки имеет смысл только при `429` и таймаутах на уровне сети, с экспоненциальной задержкой и не более 3 попыток. Ответы с ошибками не тарифицируются.

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

> **Каждый вызов возвращает 503 — канал не работает?**
>
> Почти наверняка дело в правах доступа. Возможны два варианта:
>
> 1. **В группе Token отсутствует `GrokOfficial`**: доступ к этому каналу предоставляется по заявке; см. [Настройка групп](#group-setup).
> 2. **Режим тарификации Token — с оплатой за запрос**: этот канал тарифицируется по факту использования и не может маршрутизироваться от Token с оплатой за запрос. Переключите режим тарификации на `Pay-as-you-go Priority` или `Pay-as-you-go`.

> **Я передал size: 2048x2048 — почему на выходе по-прежнему 1K?**
>
> Этот канал не сопоставляет `size` с уровнем разрешения, поэтому изображение генерируется и тарифицируется по умолчанию как `1k`. Вместо этого используйте `resolution: "2k"` и управляйте кадрированием с помощью `aspect_ratio`.

> **Можно ли редактировать изображения или передавать референсное изображение?**
>
> Этот канал **пока не поддерживает редактирование изображений**. Отправка референсного изображения в `/v1/images/generations` не вызывает ошибки, однако референс игнорируется, и генерируется новое изображение только на основе prompt.
>
> Для редактирования или объединения нескольких изображений запросите доступ к [Grok Imagine Reverse](/ru/api-capabilities/grok-imagine-image/overview), чей `/v1/images/edits` принимает от 1 до 4 референсных изображений.

> **Почему n=1? Как получить несколько изображений за один раз?**
>
> В настоящее время этот канал выдает только одно изображение за раз. Чтобы получить больше изображений, отправляйте несколько параллельных запросов с `n=1` в каждом. Если ваш рабочий процесс действительно требует нескольких изображений за вызов, используйте [Grok Imagine Reverse](/ru/api-capabilities/grok-imagine-image/overview) (`n` до 10).

> **Чем grok-imagine-image-2.0 отличается от двух других?**
>
> `grok-imagine-image-2.0` — это более новая модель изображений от xAI, в которую добавлен уровень `quality` (`low` / `medium`); `medium` обеспечивает более высокую детализацию, но работает медленнее (около 60–80 секунд при 2K). `grok-imagine-image` — самый дешевый вариант и стоит одинаково при любом разрешении; `grok-imagine-image-quality` обеспечивает более высокую точность с дифференцированной тарификацией в зависимости от разрешения.
>
> Сначала настройте пайплайн на `grok-imagine-image` или 2.0 `low`, а затем переходите на более высокий уровень по мере необходимости в качестве.

> **Можно ли сверить расходы по счету с количеством token в usage?**
>
> **Нет.** `usage.prompt_tokens` всегда имеет значение `1000 × image count` — это заполнитель, не связанный с реальными списаниями. Этот канал тарифицируется за каждое изображение в зависимости от разрешения и уровня качества; официальными считаются записи о тарификации в консоли.

> **Можно ли использовать официальный OpenAI SDK?**
>
> Да. Эндпоинт совместим с OpenAI Images API; направьте `base_url` на `https://api.apiyi.com/v1` и укажите нестандартные поля в `extra_body`:
>
> ```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-2.0",
>     prompt="a red wooden boat on an alpine lake at dawn",
>     n=1,
>     extra_body={"resolution": "2k", "aspect_ratio": "16:9", "quality": "medium"},
>     timeout=360,
> )
> print(resp.data[0].url)
> ```

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

* [Официальный API Grok Imagine Text-to-Image](/ru/api-capabilities/grok-imagine-image-official/text-to-image) — справочник по API с Playground
* [Grok Imagine Video](/ru/api-capabilities/grok-imagine-video/overview) — та же группа, генерация text-to-video и image-to-video
* [Grok Imagine Reverse](/ru/api-capabilities/grok-imagine-image/overview) — фиксированная цена за изображение, поддержка редактирования и нескольких изображений за один вызов
* [Примечания и рекомендации по работе с Image API](/ru/api-capabilities/image-api-best-practices) — общие советы по тайм-аутам, разрывам соединения и сжатию
* [Бонусы за пополнение](/ru/faq/recharge-promotions)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.