Руководство

Как использовать grok-imagine image-to-image через hiapi API: curl, Python и рабочий запрос

Jul 11, 2026

grok-imagine/image-to-image принимает одно или несколько референсных изображений и текстовый промпт и возвращает отредактированное изображение — можно сменить стиль фотографии продукта, заменить фон или объединить до трёх референсных изображений в один результат. На hiapi он работает через единый task API: создать задачу, опрашивать (или получать callback), скачать результат. Это руководство проведёт вас по точной структуре запроса и даст готовые к копированию curl- и Python-примеры, работающие сразу «из коробки».

Что вы построите + предварительные условия

Цель: отправить одно референсное изображение и промпт, получить URL отредактированного изображения и скачать его — сначала интерактивно через опрос, затем в производственной версии с callback.

Вам нужна всего одна вещь: API-ключ hiapi. Получите его в панели управления — он выглядит как sk-... и передаётся в заголовке Authorization: Bearer при каждом вызове.

Ваши референсные изображения должны быть общедоступными URL (модель загружает их на стороне сервера), поэтому сначала разместите их на вашем CDN или в объектном хранилище.

Минимальный рабочий пример (curl)

Создание задачи:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/image-to-image",
    "input": {
      "prompt": "Turn this product photo into a clean studio shot on a seamless white background with soft shadows",
      "image_urls": ["https://your-cdn.com/product.jpg"]
    }
  }'

Здесь два обязательных поля — prompt и image_urls — и это уже полный запрос. В ответе будет ID задачи в поле data.taskId:

{
  "data": {
    "taskId": "<task-id>"
  }
}

Опрос результата:

curl https://api.hiapi.ai/v1/tasks/<task-id> \
  -H "Authorization: Bearer sk-<your-key>"

Пока задача выполняется, data.status сообщает о прогрессе. Когда он становится success, URL изображения находится в data.output[0].url. Если fail, в data.error будут код ошибки и сообщение.

Важная деталь: выходные URL подписаны и истекают (в полезной нагрузке есть expireAt). Скачивайте файл сразу после успешного завершения задачи — никогда не сохраняйте и не хотлинкайте исходный выходной URL.

curl -o result.png "<data.output[0].url>"

Тот же пример на Python

import time
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-<your-key>"}

payload = {
    "model": "grok-imagine/image-to-image",
    "input": {
        "prompt": (
            "Turn this product photo into a clean studio shot "
            "on a seamless white background with soft shadows"
        ),
        "image_urls": ["https://your-cdn.com/product.jpg"],
        "aspect_ratio": "auto",
        "resolution": "1k",
        "output_format": "png",
    },
}

# 1. Создаём задачу
resp = requests.post(API, json=payload, headers=HEADERS, timeout=60)
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print("task:", task_id)

# 2. Опрашиваем до достижения конечного состояния
while True:
    task = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    if task["status"] == "success":
        image_url = task["output"][0]["url"]
        break
    if task["status"] == "fail":
        raise RuntimeError(f"task failed: {task.get('error')}")
    time.sleep(5)

# 3. Скачиваем сразу — выходные URL истекают
with open("result.png", "wb") as f:
    f.write(requests.get(image_url, timeout=120).content)
print("saved result.png")

Полная схема входных данных

Поле	Обязательно	Тип	Описание
`prompt`	✅	string	Что изменить / желаемый вид
`image_urls`	✅	массив URL	1–3 референсных изображения, должны быть общедоступными
`aspect_ratio`	необязательно	enum	`auto`, `2:1`, `20:9`, `19.5:9`, `16:9`, `4:3`, `3:2`, `1:1`, `2:3`, `3:4`, `9:16`, `9:19.5`, `9:20`, `1:2`
`resolution`	необязательно	enum	`1k` или `2k` — в нижнем регистре
`output_format`	необязательно	enum	`jpeg`, `png` или `webp`

Эта схема строгая: любое неизвестное ей поле отклоняется с 400. Здесь нет size, нет seed, нет n — если вы переносите код модели, использующий пиксельные размеры (например, size: "1024x1024"), используйте здесь aspect_ratio + resolution. Каждая задача возвращает одно изображение; для получения вариантов отправляйте несколько задач.

Несколько референсов: до 3 входных изображений

image_urls принимает до трёх референсных изображений, и модель объединяет их — например, изображение продукта плюс фон плюс референс стиля. Если отправить больше трёх, API просто отклонит запрос:

invalid input: image_urls: maxItems: got 4, want 3

Поместите самое важное изображение (обычно субъект) первым и укажите в промпте, что вносит каждый референс.

Автоматическое соотношение сторон

aspect_ratio: "auto" позволяет модели вывести пропорции результата из вашего референсного изображения, а не форсировать фиксированный кадр — это подходящее значение по умолчанию для фотографий продуктов и правок, где нужно сохранить композицию. Задавайте явное соотношение только когда этого требует целевой сценарий (например, 9:16 для сторис, 16:9 для ключевого баннера).

Замечания для продакшена

Callback вместо опроса

Для пакетной обработки или серверных нагрузок пропустите цикл опроса — зарегистрируйте callback при создании задачи, и hiapi отправит финальный результат POST-запросом на ваш эндпоинт:

{
  "model": "grok-imagine/image-to-image",
  "input": {
    "prompt": "...",
    "image_urls": ["https://your-cdn.com/product.jpg"]
  },
  "callback": {
    "url": "https://your-server.com/hooks/hiapi",
    "when": "final"
  }
}

when поддерживает только "final" — вы получите один вызов, когда задача достигнет success или fail, а не промежуточные события прогресса.

Практическое правило: для интерактивных инструментов — опрос (есть пользователь, который смотрит; цикл с sleep 5 секунд подходит), для пайплайнов — callback (работают десятки задач; вам не нужен отдельный опросчик на каждую задачу). Ваш обработчик callback всё равно должен скачивать результат немедленно — полученный им URL истекает так же, как любой другой.

Идемпотентность и повторные попытки

Task API разделяет «отправку» и «результат», что делает безопасные повторы простыми:

Сохраняйте taskId в момент возврата create. Если ваш процесс затем упадёт, восстановитесь, опросив сохранённый ID — не создавайте задачу заново.
Повторяйте только при неудачном вызове create, который не вернул taskId (сетевая ошибка, 5xx). Повторная отправка запроса, который уже вернул ID, создаст вторую отдельно оплачиваемую задачу.
Считайте status: "fail" конечным состоянием. Исправьте входные данные (или переключитесь на резервный вариант) и отправьте новую задачу; неудачная задача не перезапускается.

Частые ошибки

Что вы видите	Что это значит	Как исправить
`401` — `permission_denied`	Неверный ключ или у ключа нет доступа к этой модели	Проверьте ключ в панели управления
`400 INVALID_REQUEST` — `missing required field "prompt"` / `"image_urls"`	Отсутствует обязательное входное поле	Оба поля обязательны
`400 INVALID_REQUEST` — `additional properties '...' not allowed`	Неизвестное поле (например, `size`, `seed`, `n`)	Строгая схема — используйте только поля из таблицы выше
`400 INVALID_REQUEST` — `image_urls: maxItems`	Больше 3 референсных изображений	Сократите до 3
`404` — `task not found`	Неверный `taskId` при GET или он принадлежит другому аккаунту	Проверьте сохранённый ID
`status: "fail"` при опросе	Задача принята, но генерация не удалась	Прочитайте `data.error`, скорректируйте входные данные, отправьте заново

Обратите внимание: сбой аутентификации — это 401 с "code": "permission_denied" в теле ошибки — стоит явно обрабатывать его, поскольку он также охватывает случай, когда ключ существует, но не имеет доступа к этой модели.

Дальнейшие шаги

Детали модели и онлайн-демо: grok-imagine/image-to-image
Нужна более высокая точность? Уровень качества использует ту же структуру запроса: grok-imagine-quality/image-to-image
Начать только с промпта (без референсного изображения): grok-imagine text-to-image
Стоимость одного изображения для обоих уровней: цены
Полный справочник по task API: документация

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

Сколько референсных изображений можно передать? До 3 в image_urls. API жёстко отклоняет больше (maxItems: got N, want 3).

Можно ли задать выходной размер в пикселях? Нет. Поля size нет — форму вы контролируете через aspect_ratio (14 значений enum), а чёткость — через resolution (1k или 2k, в нижнем регистре). Всё остальное вернёт 400.

Что делает aspect_ratio: "auto"? Он позволяет модели следовать пропорциям референсного изображения, а не форсировать фиксированный кадр — это обычный выбор для правок, где нужно сохранить композицию.

Сколько живут URL результатов? Это подписанные URL с ограниченным сроком действия (expireAt в полезной нагрузке вывода). Скачивайте байты как можно скорее после успешного завершения задачи; не хотлинкайте их.

Мне опрашивать или использовать callback? Для интерактивного использования опрос примерно каждые 5 секунд подходит. Для пакетных пайплайнов передайте callback: {"url": ..., "when": "final"} и обрабатывайте один POST на задачу — "final" — единственный поддерживаемый триггер.

Можно ли получить несколько вариантов за один вызов? Нет — параметра n нет. Отправляйте отдельную задачу на каждый вариант; они всё равно выполняются параллельно.

Чем отличается от grok-imagine-quality/image-to-image? Та же структура запроса, но уровень рендеринга с более высокой точностью (и более высокой стоимостью). Прототипируйте на стандартном уровне, а затем перезапускайте отобранные варианты на уровне качества; сравнивайте стоимость одного изображения на странице цен.

ТегиAPI изображений Учебное пособие