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

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

> Изображения 1K и 2K через grok-imagine-image-2.0 по цене $0.055 за изображение с API-ключом LaoZhang API без аккаунта xAI; редактирование с тремя референсами.

Grok Imagine Image 2.0 — актуальная модель изображений xAI. Генерация по тексту и редактирование по референсам идут через OpenAI-совместимые эндпоинты Images, а один запрос может вернуть несколько изображений.

## Что поддерживает grok-imagine-image-2.0

| Параметр | Значение |
| - | - |
| ID модели | `grok-imagine-image-2.0`, вместе с конечным `.0` |
| Цена | **\$0.055 за изображение** при `1k` или `2k` и `low` или `medium`, для генерации и редактирования; тарификация за каждое успешно возвращённое изображение |
| Аккаунт | Аккаунт xAI не нужен, только API-ключ LaoZhang API |
| Группа токена и режим оплаты | `default`; «сначала по использованию» (рекомендуется) или «оплата за вызов» |
| Эндпоинты | Генерация по тексту: JSON `POST /v1/images/generations`; редактирование по референсам: multipart `POST /v1/images/edits` |
| Параллельность и лимиты | Нет лимита параллельности и троттлинга на платформе; `429` возникает из-за ёмкости апстрима, см. [Параллельность и 429](https://docs.laozhang.ai/ru/faq/api-concurrency.md) |
| Неудачные запросы | Ответы не 200 без изображения не тарифицируются; после таймаута проверьте журнал вызовов, см. [Оплата и ошибки](https://docs.laozhang.ai/ru/api-capabilities/image-billing-and-failures.md) |

Публичные цены на 24 сентября 2026 года, проверены 14 октября 2026 года; см. раздел [Модели и цены](https://docs.laozhang.ai/ru/models.md). Модель создана xAI, а цена за изображение фиксированная. xAI тарифицирует по разрешению и качеству: \$0.06 за 1K medium или 2K low и \$0.08 за 2K medium, плюс \$0.01 за каждое входное изображение при редактировании ([страница модели xAI](https://docs.x.ai/docs/models/grok-imagine-image-2.0), проверено 13 октября 2026 года). В LaoZhang API каждый из этих вариантов стоит \$0.055, а за входные изображения при редактировании плата не взимается.

![Кинематографичный маяк на рассвете с отражениями в океане, сгенерировано Grok Imagine Image 2.0](https://mintcdn.com/laozhangai-edd05f2c/YuJHjB7ivlJQODe0/images/samples/grok-generate.jpg?fit=max\&auto=format\&n=YuJHjB7ivlJQODe0\&q=85\&s=79f29d5f27a47afdbe81b006d15ddcf0)

Результат примера генерации ниже: 2K, 16:9, medium. Промпт: A cinematic lighthouse at sunrise, detailed ocean reflections, no text

### Параметры и ограничения

| Параметр | Значения |
| - | - |
| Референсов за правку | 1–3 |
| Разрешение | `1k` или `2k` |
| Качество | `low` или `medium`, задавайте явно |
| Соотношения сторон | 15 фиксированных значений; если не указать, модель выберет сама |
| Изображений за запрос | `n` от 1 до 10, тарификация за каждое возвращённое изображение |
| Формат ответа | `url` или `b64_json` |

> [!WARNING]
>
> Для редактирования нужны загрузки файлов в стиле OpenAI, а не JSON-объекты изображений из документации xAI. Запросы с четырьмя или пятью референсами завершаются ошибкой, поэтому ограничение в три изображения проверяйте в клиенте и не повторяйте запрос, превысивший лимит.

## Выбор модели Grok Imagine

| ID модели | Область применения | Для чего подходит |
| - | - | - |
| `grok-imagine-image-2.0` | 1K/2K, `low`/`medium`, 15 фиксированных соотношений сторон, правки с 1–3 референсами | Новые интеграции, детализированные изображения и композиция по референсам |
| `grok-imagine-image` | Выведена из работы 30 октября 2026 года | Используйте `grok-imagine-image-2.0` |
| `grok-imagine-image-quality` | Более ранняя модель качества с меньшим лимитом референсов | Существующие интеграции и небольшие задачи с финальными ассетами |

Более ранняя модель `grok-imagine-image-quality` стоит \$0.045 за изображение. Как и 2.0, она тарифицируется за каждое успешно возвращённое изображение.

* `grok-imagine-image`: выведена из работы 30 октября 2026 года, вызовы теперь возвращают 503. Замените `model` на `grok-imagine-image-2.0`; `aspect_ratio` и правки с несколькими референсами работают так же. См. [объявление о выводе из работы](https://docs.laozhang.ai/en/announcements/grok-imagine-image-retired-2026-10.md).
* `grok-imagine-image-quality`: xAI объявила о выводе этой модели из работы с 2 ноября 2026 года; запросы к ней обслуживает `grok-imagine-image-2.0` с качеством `low` ([руководство xAI по миграции](https://docs.x.ai/developers/migration/imagine-image-quality-nov-2)). На 3 ноября 2026 года модель ещё доступна в LaoZhang API по цене \$0.045 за изображение. Для новых интеграций используйте 2.0 и задавайте `quality` явно.

## Подготовка к вызову

**1. Создайте и защитите API-ключ**

В разделе [Управление токенами](https://api.laozhang.ai/token) создайте ключ в группе `default` и выберите **Режим оплаты** (计费模式) — **«сначала по использованию»** (按量优先, рекомендуется) или **«оплата за вызов»** (按次计费). Ключ с режимом «сначала по использованию» вызывает и модели с оплатой за вызов, и модели с оплатой по использованию; ключ с оплатой за вызов — только модели с оплатой за вызов.

Храните ключ в переменной окружения на сервере, а не в коде браузера, публичном репозитории или логах.

**2. Проверьте доступ к модели и цену**

В разделе [Модели и цены](https://api.laozhang.ai/account/pricing) убедитесь, что ключу доступна `grok-imagine-image-2.0`, и посмотрите актуальную цену.

**3. Подготовьте окружение**

Задайте ключ и установите OpenAI Python SDK, который используется в примерах на Python:

```bash theme={null}
export LAOZHANG_API_KEY="YOUR_LAOZHANG_API_KEY"
python3 -m pip install openai
```

**4. Начните с одного изображения**

Сначала используйте `n=1`. Сохраните результат, проверьте содержимое и размеры, а также запись в журнале вызовов, прежде чем увеличивать разрешение, число изображений или параллельность.

## Генерация изображения

Этот запрос создаёт одно изображение 2K с соотношением 16:9 и качеством `medium` и записывает ответ в `grok-generation.json`:

```bash theme={null}
curl --fail-with-body "https://api.laozhang.ai/v1/images/generations" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0",
    "prompt": "A cinematic lighthouse at sunrise, detailed ocean reflections, no text",
    "n": 1,
    "aspect_ratio": "16:9",
    "resolution": "2k",
    "quality": "medium",
    "response_format": "url"
  }' \
  -o grok-generation.json
```

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

Успешный ответ приходит с HTTP 200 и содержит один элемент в `data`:

```json theme={null}
{
  "data": [
    {
      "url": "https://..."
    }
  ]
}
```

### Сохранение результата

Ссылка временная, поэтому скачайте изображение сразу. Сохраните скрипт как `save_images.py`. Он записывает на диск все изображения из ответа, будь то `url` или `b64_json`, и выбирает расширение файла по данным изображения:

```python save_images.py theme={null}
import base64
import json
import sys
import urllib.request
from pathlib import Path

response_file, stem = sys.argv[1], sys.argv[2]
response = json.loads(Path(response_file).read_text())
if not response.get("data"):
    sys.exit(f"В {response_file} нет изображения: {response}")

for number, item in enumerate(response["data"], start=1):
    if item.get("b64_json"):
        # Убираем необязательный префикс data:image/...;base64, и восстанавливаем padding.
        value = item["b64_json"].split(",", 1)[-1]
        image = base64.b64decode(value + "=" * (-len(value) % 4))
    else:
        with urllib.request.urlopen(item["url"], timeout=120) as download:
            image = download.read()
    if image.startswith(b"\x89PNG"):
        extension = "png"
    elif image[:4] == b"RIFF" and image[8:12] == b"WEBP":
        extension = "webp"
    else:
        extension = "jpg"
    path = Path(f"{stem}-{number}.{extension}")
    path.write_bytes(image)
    print(f"Сохранено: {path}")
```

```bash theme={null}
python3 save_images.py grok-generation.json grok-lighthouse
```

Скрипт выведет строку вида `Сохранено: grok-lighthouse-1.jpg`. Откройте файл и проверьте объект, текст и композицию. Чтобы получить в ответе байты изображения вместо ссылки, задайте `response_format` равным `b64_json`; тот же скрипт обрабатывает оба варианта.

### Генерация через Python SDK

OpenAI Python SDK не выводит все параметры изображений Grok как именованные, поэтому передавайте `aspect_ratio`, `resolution` и `quality` через `extra_body`. Этот пример запрашивает вывод в Base64 и сохраняет декодированное изображение:

```python theme={null}
import base64
import os
from pathlib import Path

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LAOZHANG_API_KEY"],
    base_url="https://api.laozhang.ai/v1",
    timeout=180,
)

response = client.images.generate(
    model="grok-imagine-image-2.0",
    prompt="Премиальные механические часы на тёмном сланце, макросъёмка для каталога",
    n=1,
    response_format="b64_json",
    extra_body={
        "aspect_ratio": "1:1",
        "resolution": "2k",
        "quality": "medium",
    },
)

value = response.data[0].b64_json.split(",", 1)[-1]
image = base64.b64decode(value + "=" * (-len(value) % 4))
extension = "png" if image.startswith(b"\x89PNG") else "jpg"
output = Path(f"grok-watch.{extension}")
output.write_bytes(image)
print(f"Сохранено: {output}")
```

## Соотношение сторон, разрешение и качество

`grok-imagine-image-2.0` принимает 15 фиксированных соотношений сторон:

| Ориентация | Значения |
| - | - |
| Квадрат | `1:1` |
| Альбомная | `16:9`, `4:3`, `3:2`, `2:1`, `19.5:9`, `20:9`, `21:9`, `5:2` |
| Портретная | `9:16`, `3:4`, `2:3`, `1:2`, `9:19.5`, `9:20` |

Не указывайте `aspect_ratio`, чтобы модель выбрала сама, или передайте значение, если раскладка должна быть предсказуемой.

* `resolution="1k"` работает быстрее и подходит для черновиков, миниатюр и пакетов вариантов.
* `resolution="2k"` даёт файлы крупнее и дольше отвечает; подходит для финальных ассетов и обрезки.
* `quality="low"` отдаёт предпочтение скорости, `quality="medium"` — детализации.
* Не отправляйте `quality="high"` и `resolution="4k"`.

Ответы не сообщают, какой уровень качества использован. Задавайте `quality` равным `low` или `medium` явно, а не полагайтесь на `auto`, чтобы время ответа и качество вывода оставались предсказуемыми.

## Редактирование по одному референсу

Для редактирования нужна загрузка файла. Положите в текущую папку локальный файл `product-photo.png` и выполните:

```bash theme={null}
curl --fail-with-body "https://api.laozhang.ai/v1/images/edits" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -F "model=grok-imagine-image-2.0" \
  -F "prompt=Сделай кружку матовой чёрной. Сохрани композицию, освещение и фон." \
  -F "image=@product-photo.png" \
  -F "response_format=url" \
  -o grok-edit.json

python3 save_images.py grok-edit.json grok-edit
```

Редактирование по референсу заново создаёт сцену, а не выполняет попиксельный inpainting по маске. Проверьте объект, цвет, текст и композицию на сохранённом изображении.

## Редактирование по двум или трём референсам

Повторите поле `image[]` для каждого референса. Этот запрос передаёт объект, сцену и стиль тремя отдельными файлами:

```bash theme={null}
curl --fail-with-body "https://api.laozhang.ai/v1/images/edits" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -F "model=grok-imagine-image-2.0" \
  -F "prompt=Помести изделие с изображения 1 в сцену с изображения 2 и примени визуальный стиль с изображения 3. Сохрани цвета изделия." \
  -F "image[]=@product.png" \
  -F "image[]=@scene.jpg" \
  -F "image[]=@style.jpg" \
  -F "aspect_ratio=3:2" \
  -F "response_format=url" \
  -o grok-multi-edit.json

python3 save_images.py grok-multi-edit.json grok-multi-edit
```

Порядок загрузки соответствует изображениям 1, 2 и 3 в промпте. Успешный запрос возвращает одно изображение; при `aspect_ratio=3:2` ожидайте альбомный результат, например 1248×832. Пересчитайте файлы до отправки запроса: четвёртый референс приводит к ошибке всего запроса.

### Редактирование через Python SDK

OpenAI SDK подходит для правок по одному изображению. Этот пример получает ссылку и сразу скачивает изображение:

```python theme={null}
import os
import urllib.request
from pathlib import Path

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LAOZHANG_API_KEY"],
    base_url="https://api.laozhang.ai/v1",
    timeout=180,
)

with open("product.png", "rb") as source:
    response = client.images.edit(
        model="grok-imagine-image-2.0",
        image=source,
        prompt="Оставь изделие и замени фон на дождливую неоновую улицу.",
        response_format="url",
    )

with urllib.request.urlopen(response.data[0].url, timeout=120) as download:
    image = download.read()
extension = "png" if image.startswith(b"\x89PNG") else "jpg"
output = Path(f"grok-sdk-edit.{extension}")
output.write_bytes(image)
print(f"Сохранено: {output}")
```

Для нескольких референсов сначала используйте вариант с cURL выше, чтобы убедиться, как ваш HTTP-клиент сериализует повторяющиеся поля multipart.

## Параметры

| Параметр | Тип | Обязателен | Поведение |
| - | - | - | - |
| `model` | string | Да | `grok-imagine-image-2.0` |
| `prompt` | string | Да | Содержание, композиция, стиль и детали, которые должны остаться прежними |
| `n` | integer | Нет | 1–10 результатов генерации по тексту; каждое возвращённое изображение тарифицируется |
| `aspect_ratio` | string | Нет | Одно из 15 значений выше; если не указать, модель выберет сама |
| `resolution` | string | Нет | `1k` или `2k` строчными для генерации по тексту |
| `quality` | string | Нет | `low` или `medium`; не отправляйте `high` |
| `response_format` | string | Нет | `url` или `b64_json` |
| `image` | file | Для правки по одному изображению | Одно локальное изображение |
| `image[]` | file | Для правки по нескольким изображениям | Повторите поле для файлов, всего до трёх |

## Цены и оплата

Тарификация считает изображения, которые запрос фактически вернул:

| Запрос | Тарифицируется как |
| - | - |
| `n=1`, возвращено одно изображение | 1 изображение |
| `n=4`, возвращено четыре изображения | 4 изображения |
| `n=10`, возвращено десять изображений | 10 изображений (\$0.55 по текущей цене) |
| Правка по трём референсам, возвращено одно изображение | 1 изображение |

LaoZhang API берёт одну цену за `1k` и `2k` и за `low` и `medium`. xAI тарифицирует по разрешению и качеству; сравнение приведено в примечании о цене в начале страницы.

Перед большим пакетом проверьте [консоль](https://api.laozhang.ai/account/pricing), а окончательным источником данных об оплате считайте записи в журнале вызовов.

## Обработка ошибок

| Ситуация | Возможный результат | Что делать |
| - | - | - |
| Неверный API-ключ | 401 | Замените ключ; не повторяйте запрос с теми же учётными данными |
| Нет `prompt` | 400 | Исправьте запрос |
| `n` больше 10 | Может прийти 429 | Проверяйте `n` локально: от 1 до 10 |
| Неподдерживаемое соотношение сторон | Может прийти 429 | Используйте значения из списка выше |
| `resolution="4k"` | Может прийти 503 | Используйте `1k` или `2k`; это не временный сбой |
| `quality="high"` | Изображение всё равно может прийти | Отклоняйте локально, чтобы избежать тихой подмены и списания |
| Четыре или пять референсов | 500 | Сократите до трёх; не повторяйте тот же запрос |

Допустимые запросы, получившие 429, сетевые ошибки или явно временные ошибки 5xx, повторяйте с экспоненциальной задержкой и джиттером. После таймаута на клиенте проверьте запись в журнале вызовов, прежде чем отправлять запрос снова, чтобы не сгенерировать и не оплатить одно изображение дважды.

## Перед запуском в продакшен

1. Сгенерируйте одно изображение `1k` с `low` рабочим ключом.
2. Сохраните результат и проверьте его реальный формат и размеры.
3. Проверьте именно те значения разрешения, качества, соотношения сторон и `n`, которые планируете использовать.
4. Для правок берите разные нечувствительные референсы и убедитесь, что каждый влияет на результат.
5. Проверяйте в клиенте ограничение в три референса.
6. Задайте таймаут не меньше 60 секунд для запросов `1k` `low` и 120–180 секунд для `medium` или `2k`.
7. Прежде чем повышать параллельность, сверьте долю успешных запросов, время ответа, число изображений и записи в журнале вызовов.

## Частые вопросы

### Можно ли вызывать Grok Imagine без аккаунта xAI?

Да. Нужен только API-ключ LaoZhang API, аккаунт xAI не требуется. Генерация и редактирование идут через OpenAI-совместимые эндпоинты Images, тарификация — за каждое успешно возвращённое изображение.

### Какой точный ID модели?

Используйте `grok-imagine-image-2.0`, вместе с конечным `.0`. Более ранняя `grok-imagine-image` выведена из работы 30 октября 2026 года; `grok-imagine-image-quality` — отдельная более ранняя модель; xAI объявила о её выводе из работы со 2 ноября, поэтому для новых интеграций используйте 2.0.

### Влияют ли разрешение и качество на цену?

Нет: тарификация идёт за каждое успешно возвращённое изображение. `1k`, `2k`, `low` и `medium` сейчас стоят одинаково; примеры — в разделе «Цены и оплата». Время ответа зависит от уровня, поэтому планируйте таймауты: 14 октября 2026 года промпт из быстрого старта занял 16 с на 1K low и 71 с на 2K medium, а каждый вызов записан в журнале по \$0.055.

![Маяк на скалистом берегу на рассвете с отражением солнца в море, сгенерировано Grok Imagine Image 2.0 в 1K low](https://mintcdn.com/laozhangai-edd05f2c/20UJZ-8MviaLAz5r/images/samples/grok-1k-low.jpg?fit=max\&auto=format\&n=20UJZ-8MviaLAz5r\&q=85\&s=f83ade14ebc124ee23ec1b56e1ab2ac3)

1K, low, 16:9: 16 с, \$0.055

![Маяк на скалистом берегу на рассвете с детализированными облаками и волнами, сгенерировано Grok Imagine Image 2.0 в 2K medium](https://mintcdn.com/laozhangai-edd05f2c/20UJZ-8MviaLAz5r/images/samples/grok-2k-medium.jpg?fit=max\&auto=format\&n=20UJZ-8MviaLAz5r\&q=85\&s=0911bebb8edf5ac6b2e8ac61deba42b3)

2K, medium, 16:9: 71 с, \$0.055

Запрос, вернувший ошибку не 200 и не вернувший изображение, не тарифицируется. Но таймаут на клиенте не равен сбою: сервер мог завершить генерацию и списать оплату, поэтому проверьте запись в журнале, прежде чем отправлять запрос снова. Записи в журнале вызовов — окончательный источник данных об оплате.

### Можно ли править в JSON xAI или передать 4–5 референсов?

Нельзя ни то ни другое. Редактирование принимает только файлы в multipart, до трёх референсов, как показывает таблица в начале страницы. JSON-объекты изображений xAI возвращают HTTP 400.

В документации xAI сказано, что `images.edit()` из OpenAI SDK не подходит для редактирования в Grok; это относится к собственному API xAI, который принимает только JSON.

В LaoZhang API `images.edit()` работает для правок по одному изображению, как показано в разделе «Редактирование через Python SDK». Для нескольких референсов начните с формы `image[]` в cURL.

### Какое соотношение сторон вернёт правка?

По данным xAI, правка без `aspect_ratio` следует соотношению сторон первого референса. Чтобы зафиксировать кадр, добавьте `aspect_ratio` в запрос на правку; пример с тремя референсами использует `aspect_ratio=3:2` и возвращает изображение 1248×832.

### Можно ли продолжить правку предыдущего результата?

Да. Скачайте предыдущий результат, загрузите его как `image` и опишите в промпте только изменение этого раунда, например: «Оставь всё как есть и добавь золотую рамку». Каждый раунд — новый запрос на правку, который тарифицируется по возвращённым изображениям.

### Как хранить сгенерированные изображения?

Скачивайте результаты-ссылки в собственное хранилище сразу: xAI тоже называет возвращаемые URL временными. Используйте `b64_json`, если изображение должно прийти внутри ответа API.

## Источники и связанные материалы

* [Объявление о запуске Grok Imagine Image 2.0](https://docs.laozhang.ai/en/announcements/grok-imagine-image-2-0-2026-09.md): доступность и ограничение в три референса при редактировании
* [Модель xAI Grok Imagine Image 2.0](https://docs.x.ai/developers/models/grok-imagine-image-2.0): официальный ID модели и цены апстрима по разрешению и качеству
* [Генерация изображений в xAI](https://docs.x.ai/developers/model-capabilities/images/generation): официальные соотношения сторон, разрешение, качество, пакетная генерация и форматы ответа
* [Редактирование изображений в xAI](https://docs.x.ai/developers/model-capabilities/images/editing): JSON-формат редактирования апстрима, который отличается от multipart-интерфейса LaoZhang API
* [Редактирование по нескольким изображениям в xAI](https://docs.x.ai/developers/model-capabilities/images/multi-image-editing): как писать промпты для правок по нескольким изображениям; LaoZhang API принимает до трёх референсов за правку
* [Справочник Images API](https://docs.laozhang.ai/ru/api-reference/images.md): общая структура запросов и ответов
* [Сравнение API изображений](https://docs.laozhang.ai/ru/api-capabilities/image-generation-guide.md): Grok Imagine и другие модели изображений
* [Модели и цены в консоли](https://api.laozhang.ai/account/pricing): модели, группы, цены и журнал вызовов вашего аккаунта


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