Как пользоваться API преобразования изображений Grok Image 2.0? Одно референсное изображение и одна инструкция для редактирования

Как пользоваться API преобразования изображений Grok Image 2.0? Передайте одно публично доступное референсное изображение и инструкцию по редактированию, отправьте запрос через POST /v1/tasks, а при опросе получите data.output[0].url — это и будет отредактированное изображение. Фиксированная цена $0,065 за изображение, 1K и 2K стоят одинаково, маски и слои не нужны.

Grok Image 2.0 уже доступен в HiAPI: откройте страницу модели преобразования изображений, загрузите изображение и редактируйте. Новым пользователям при регистрации начисляется 200 кредитов — этого хватит на 1 преобразование изображения (130 кредитов).

TL;DR

• Что это: grok-imagine-image-2.0/image-to-image от xAI — редактирование одного референсного изображения с помощью инструкции на естественном языке: можно менять фон, добавлять мелкие объекты, изменять материал и цвет.
• Сколько стоит: $0,065 за изображение; 1K / 2K и low / medium стоят одинаково; оплата за успешно созданные изображения, при ошибке автоматический возврат. На $10 получится около 153 изображений.
• Как вызвать быстрее всего: обязательны только prompt и image; image — это одна строка URL, а не массив.

Какие параметры есть у преобразования изображений Grok Image 2.0?

Поле	Обязательно	Значения	Описание
prompt	Да	Строка	Инструкция по редактированию
image	Да	Строка	Один публично доступный URL JPG / JPEG / PNG / WebP, не массив
resolution	Нет	1k, 2k	По умолчанию 1k
quality	Нет	low, medium	По умолчанию medium; medium даёт лучшую детализацию, low быстрее
aspect_ratio	Нет	Те же 14 значений, что и для генерации изображений по тексту	Можно передать, но не действует: формат вывода следует за референсным изображением

За раз можно редактировать только одно референсное изображение, одна задача — одно изображение; для нескольких изображений отправляйте несколько задач параллельно. Запросы с именами полей и значениями, которых нет в таблице выше, вернут 400.

Два пути: онлайн-проба и API

Онлайн-проба (1 минута)

1. Откройте страницу модели преобразования изображений, войдите и загрузите референсное изображение.
2. Введите инструкцию по редактированию, выберите разрешение.
3. Нажмите «Запустить» и после успешного выполнения сравните референсное и итоговое изображения.

Подключение по API (5 минут)

1. Создайте API Key в консоли.
2. Разместите референсное изображение по публично доступному адресу (свой CDN или объектное хранилище).
3. Отправьте задачу через POST /v1/tasks, опрашивайте статус или настройте callback.
4. После успеха сразу скачайте data.output[0].url.

Keep the elderly luthier exactly as he is: his face, expression, hands, seated pose, and the checked flannel shirt he's wearing, completely unchanged. Replace only the background environment: move him from the wood-shaving workshop into a sunlit outdoor market stall with hanging string instruments and warm afternoon light, matching the new environment's light direction so it falls naturally across his face and hands.

Попробуйте сразу с этим промптом для редактирования: перенести старого мастера по изготовлению струнных инструментов из мастерской с древесной стружкой на солнечный рынок, человек остаётся неизменным. Сгенерировать с этим промптом → (ссылка только предзаполняет промпт, референсное изображение загрузите на странице модели, разрешение выберите 2K)

Референсное изображение	Результат

curl и Python: первое успешное редактирование

Сначала задайте API Key:

export HIAPI_API_KEY="sk-..."

Все запросы содержат Authorization: Bearer sk-<key>. Редактирование изображений асинхронное и использует тот же интерфейс задач, что и другие модели HiAPI. Референсное изображение загружается сервером, локальный путь к файлу не подойдёт — нужен публично доступный URL.

Шаг 1, создание задачи:

curl --fail-with-body -sS -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0/image-to-image",
    "input": {
      "prompt": "Change the mug on the table to matte black ceramic, keep everything else in the scene identical",
      "image": "https://your-cdn.example.com/source-photo.jpg",
      "resolution": "2k"
    }
  }'

Сразу возвращается taskId:

{
  "code": 200,
  "message": "success",
  "data": { "taskId": "tk-hiapi-01M01JW1C9N3VHRZAEBFEESC5Q" }
}

Шаг 2, опрос до конечного состояния:

curl --fail-with-body -sS https://api.hiapi.ai/v1/tasks/tk-hiapi-01M01JW1C9N3VHRZAEBFEESC5Q \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Проверяйте data.status: success означает успех, fail — ошибку; при других статусах продолжайте ждать. Пример успешного ответа:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M01JW1C9N3VHRZAEBFEESC5Q",
    "status": "success",
    "storage": "temp",
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M01JW1C9N3VHRZAEBFEESC5Q-0.jpg",
        "artifactId": "76711",
        "expireAt": 1787364206
      }
    ]
  },
  "message": "success"
}

Обратите внимание на storage: "temp" и expireAt: адрес итогового изображения временный, скачайте его сразу после завершения задачи или перенесите в своё объектное хранилище. Формат вывода следует за референсным изображением, в примере опущен недействующий aspect_ratio.

Версия на Python:

Сначала установите requests (python3 -m pip install requests) и задайте HIAPI_API_KEY как выше. Скрипт опрашивает не более 10 минут; после тайм-аута сохраните taskId и продолжайте查询.

import os
import time
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def task_data(response):
    response.raise_for_status()
    body = response.json()
    if body.get("code") != 200:
        raise RuntimeError(f"HiAPI request failed: {body}")
    return body["data"]


def edit_image(prompt: str, image_url: str, resolution: str = "1k") -> str:
    create = requests.post(
        f"{BASE}/tasks",
        headers=HEADERS,
        json={
            "model": "grok-imagine-image-2.0/image-to-image",
            "input": {
                "prompt": prompt,
                "image": image_url,
                "resolution": resolution,
            },
        },
        timeout=30,
    )
    task_id = task_data(create)["taskId"]
    print(f"taskId: {task_id}", flush=True)
    deadline = time.monotonic() + 600

    while time.monotonic() < deadline:
        poll = requests.get(f"{BASE}/tasks/{task_id}", headers=HEADERS, timeout=30)
        data = task_data(poll)
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "fail":
            raise RuntimeError(f"task {task_id} failed: {data}")
        time.sleep(2)
    raise TimeoutError(f"task {task_id} is still pending; query this ID instead of submitting again")


if __name__ == "__main__":
    url = edit_image(
        "Change the mug on the table to matte black ceramic, keep everything else identical",
        "https://your-cdn.example.com/source-photo.jpg",
        resolution="2k",
    )
    print(url)

На что обратить внимание перед запуском?

• Сначала разместите референсное изображение в публичном доступе. Если изображение пользователя находится в приватном бакете или на localhost, платформа не сможет его загрузить, и задача асинхронно завершится ошибкой; перед отправкой убедитесь, что ссылка публично доступна, и используйте долгоживущий адрес (не используйте подписанные ссылки с истечением срока).

• Формулируйте инструкцию как "что сохранить, что изменить". Сначала напишите то, что должно остаться неизменным, затем то, что нужно изменить; чем уже область изменений, тем стабильнее результат. Больше вариантов — в шаблонах промптов для преобразования изображений.

• Для пакетной обработки используйте callback, а не плотный цикл опроса.

  {
    "model": "grok-imagine-image-2.0/image-to-image",
    "input": { "prompt": "...", "image": "https://your-cdn.example.com/source-photo.jpg" },
    "callback": { "url": "https://your-service.example.com/hooks/hiapi", "when": "final" }
  }
  

  when: "final" уведомляет, когда задача достигает конечного состояния успеха или ошибки; принимающая сторона дедуплицирует по taskId.

• Сразу переносите итоговое изображение. data.output[0].url — временный адрес, он истекает согласно expireAt.

• Отправляйте одну задачу только один раз. После получения ответа сохраните соответствие taskId и бизнес-задачи; повторная отправка может создать несколько задач, и каждая будет оплачена отдельно. Если запрос на создание завершился по тайм-ауту и ID не получен, сначала проверьте записи задач, а затем решайте, отправлять ли повторно.

• Явно указывайте resolution. По умолчанию 1k; 1K и 2K стоят одинаково ($0,065), для финальных работ сразу передавайте "2k".

• Обработка ошибок. Сначала проверяйте HTTP-статус и code, message в ответе, затем читайте data. При ошибке параметров или аутентификации исправьте и отправьте снова; если задача вернула fail, зафиксируйте ошибку и прекратите опрос.

Связанные материалы

• Страница модели генерации изображений по тексту Grok Image 2.0: та же серия, создание новых изображений только по тексту.
• Сколько стоит Grok Image 2.0 API?
• Подключение API генерации изображений по тексту Grok Image 2.0
• Шаблоны промптов для преобразования изображений Grok Image 2.0
• Аутентификация и быстрый старт

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

image — это URL или массив? Одна строка URL. Массив вызовет ошибку типа. Если нужно объединить несколько изображений, используйте модель, поддерживающую несколько референсных изображений.

Что делать при ошибке "additional properties not allowed"? input принимает только prompt, image, aspect_ratio, resolution, quality. Часто встречающиеся в других моделях редактирования image_urls, strength, mask, seed, negative_prompt здесь недоступны — просто удалите их.

Браузер открывает референсное изображение, но задача всё равно может завершиться ошибкой — почему? Платформа загружает изображение на сервере, поэтому референсное изображение должно быть доступно без авторизации из публичной сети; подписанная ссылка должна оставаться действительной до завершения загрузки. Проверьте права доступа, формат и срок действия ссылки перед отправкой.

Можно ли за один раз отредактировать несколько изображений? Нет: одно изображение на входе — одно на выходе. Для пакетной обработки отправляйте несколько задач параллельно.

Почему преобразование изображений дороже генерации по тексту? Преобразование изображений стоит $0,065, генерация по тексту — $0,052, разница 25%, что соответствует возможности "редактировать с одним референсным изображением".

Сколько действует адрес вывода? Временное хранилище; expireAt в ответе — это Unix-временная метка. Скачайте или перенесите сразу после успешного завершения задачи.

Нужно ли синхронно ждать результат? Нет. Интерфейс создания возвращает ответ сразу после постановки задачи в очередь; короткий скрипт опрашивает GET /v1/tasks/<taskId>, в продакшене настройте callback.

Отредактируйте первое изображение прямо сейчас

Сначала задайте HIAPI_API_KEY, затем замените адрес image в примерах curl и Python на URL вашего публичного изображения. Чтобы сначала посмотреть результат, откройте страницу модели преобразования изображений, загрузите изображение и вставьте промпт выше.