Как использовать grok-imagine-quality/image-to-image через hiapi API: curl, Python и доступные запросы

В этом руководстве показано, как преобразовать существующее изображение через унифицированный API задач hiapi с помощью grok-imagine-quality/image-to-image (уровень повышенной точности в серии Grok Imagine). Вы отправите исходное изображение и текстовый промпт, опросите результат и скачаете сгенерированное изображение. Каждая структура запроса и ответа ниже проверена на работающем API.

Что вам понадобится

• Ключ API hiapi — создайте его в панели управления.
• От одного до трёх общедоступных URL изображений в качестве источника. Платформа получает и нормализует ваши входные медиа на стороне сервера, поэтому локальные пути к файлам и base64-полезные нагрузки не поддерживаются — сначала разместите изображения там, где они доступны API.

Это всё. SDK не нужен; API задач — это обычный HTTPS + JSON.

Режим запроса

grok-imagine-quality/image-to-image работает на эндпоинте асинхронных задач: вы создаёте задачу через POST /v1/tasks, затем опрашиваете GET /v1/tasks/<taskId> (или регистрируете callback), пока она не завершится.

Схема входных данных строгая — неизвестные поля отклоняются с кодом 400:

Поле	Тип	Обязательно	Описание
prompt	string	✅	Что сделать с исходным изображением
image_urls	string[]	✅	Публичные URL 1–3 исходных/референсных изображений
aspect_ratio	string	–	Одно из: 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	string	–	1k или 2k — в нижнем регистре (1K вернёт 400)
output_format	string	–	jpeg, png или webp

Обратите внимание, чего нет: нет size, нет n, нет seed, нет регуляторов strength или consistency. Насколько выходной результат следует за исходным изображением, определяется вашим промптом и переданными референсными изображениями — см. раздел FAQ ниже.

Минимальный рабочий пример (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-quality/image-to-image",
    "input": {
      "prompt": "Преврати это фото продукта в чистый студийный снимок на светло-сером фоне с мягкими тенями",
      "image_urls": ["https://your-cdn.example.com/source.jpg"],
      "aspect_ratio": "1:1",
      "resolution": "2k",
      "output_format": "png"
    }
  }'

Успешное создание возвращает ID задачи:

{
  "code": 200,
  "data": {
    "taskId": "task_xxxxxxxxxxxx"
  }
}

Опрашивайте, пока задача не достигнет финального состояния:

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

Во время выполнения data.status имеет промежуточное значение; после завершения становится success, а изображения находятся в data.output:

{
  "code": 200,
  "data": {
    "taskId": "task_xxxxxxxxxxxx",
    "status": "success",
    "output": [
      {
        "url": "https://.../result.png?...&expireAt=...",
        "expireAt": 1760000000
      }
    ]
  }
}

⚠️ URL вывода временные (обратите внимание на expireAt). Сразу после успеха задачи скачайте байты и сохраните их в своё хранилище — не используйте прямые ссылки на URL результата.

Если задача не удалась, data.status равен fail, а data.error содержит code и message.

Python: создание, опрос, скачивание

Полный скрипт, использующий только requests:

import time
import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
API_KEY = "sk-<your-key>"

HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

def create_task(prompt: str, image_urls: list[str]) -> str:
    payload = {
        "model": "grok-imagine-quality/image-to-image",
        "input": {
            "prompt": prompt,
            "image_urls": image_urls,   # 1-3 public URLs
            "aspect_ratio": "1:1",
            "resolution": "2k",         # lowercase: "1k" or "2k"
            "output_format": "png",
        },
    }
    r = requests.post(API_BASE, headers=HEADERS, json=payload, timeout=60)
    data = r.json()
    task_id = (data.get("data") or {}).get("taskId")
    if not task_id:
        raise RuntimeError(f"create failed: {data}")
    return task_id

def wait_task(task_id: str, timeout_s: int = 600, poll_interval: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        task = r.json().get("data") or {}
        status = task.get("status")
        if status == "success":
            return task
        if status == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} still running after {timeout_s}s")

if __name__ == "__main__":
    task_id = create_task(
        prompt="Преврати это фото продукта в чистый студийный снимок на светло-сером фоне",
        image_urls=["https://your-cdn.example.com/source.jpg"],
    )
    print("task:", task_id)

    task = wait_task(task_id)
    url = task["output"][0]["url"]

    # The output URL expires -- download immediately and persist yourself
    img = requests.get(url, timeout=120).content
    with open("result.png", "wb") as f:
        f.write(img)
    print(f"saved result.png ({len(img)} bytes)")

Рекомендации для продакшена

Используйте callback вместо опроса

Для любого сценария, кроме одноразовых скриптов, зарегистрируйте callback и пропустите цикл опроса. Добавьте объект верхнего уровня callback (на том же уровне, что model и input):

{
  "model": "grok-imagine-quality/image-to-image",
  "input": { "...": "..." },
  "callback": {
    "url": "https://your-app.example.com/hooks/hiapi",
    "when": "final"
  }
}

when поддерживает только "final" — вы получите ровно один POST, когда задача достигнет финального состояния (success или fail). Практическое правило:

• Опрос подходит для CLI, ноутбуков и пакетных заданий, где процесс и так остаётся живым. Опрашивайте каждые 3–5 секунд; не бомбардируйте с субсекундными интервалами.
• Callback лучше подходит для веб-бэкендов: нет висящих соединений, нет рабочих потоков, занятых во время генерации. Проверяйте полезную нагрузку на сервере, повторно запрашивая GET /v1/tasks/<taskId>, а не доверяя телу webhook слепо.

Идемпотентность

Создание задачи само по себе не идемпотентно — если ваш процесс упадёт после POST /v1/tasks, но до сохранения taskId, повторная попытка создаст (и оплатит) вторую задачу. До начала ожидания сохраните taskId в своём хранилище под ключом вашего внутреннего ID задания, а при перезапуске восстанавливайтесь, опрашивая сохранённый taskId, а не создавая задачу заново.

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

Ошибки, с которыми вы реально столкнётесь:

• 401 permission_denied — недействительный ключ API или нет доступа к этой модели. Тело ответа содержит request_id, который можно отправить в поддержку:

  {
    "error": {
      "code": "permission_denied",
      "message": "This API key cannot use the selected model. ...",
      "request_id": "2026...",
      "type": "hiapi_error"
    }
  }
  

• 400 INVALID_REQUEST — нарушение схемы с точным сообщением. Реальные примеры для этой модели:

  • prompt: missing required field "prompt" — вы забыли обязательное поле.
  • image_urls: maxItems: got 12, want 3 — слишком много референсных изображений (максимум 3).
  • resolution: value must be one of '1k', '2k' — вы отправили 1K/4K.
  • additional properties 'seed' not allowed — вы передали поле, которое эта модель не принимает.

• Финальное состояние fail — задача принята, но генерация не удалась (например, исходный URL недоступен). Проверьте data.error.message, исправьте входные данные и создайте новую задачу.

Используйте повторные попытки с экспоненциальной задержкой для 5xx и сетевых ошибок; не повторяйте 400 — до исправления полезной нагрузки они будут снова завершаться так же.

Выбор уровня качества (и что насчёт «консистентности»?)

Серия Grok Imagine на hiapi разделена на отдельные ID моделей по уровню и модальности. Для изображения в изображение вы можете выбрать:

• grok-imagine-quality/image-to-image — уровень повышенной точности, описанный в этой статье; медленнее, лучше сохраняет детали.
• grok-imagine/image-to-image — стандартный уровень; та же схема запроса, быстрее и дешевле за изображение.

Уровень и есть ID модели — внутри input нет параметра quality (его отправка вернёт 400 additional properties 'quality' not allowed). Цены за изображение для обоих уровней указаны на странице цен.

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

• Страница модели grok-imagine-quality/image-to-image — песочница и цены
• Как использовать grok-imagine/text-to-image — сначала сгенерируйте исходное изображение с нуля
• Как использовать grok-imagine/image-to-video — оживите свой результат
• Документация hiapi — аутентификация, API задач и остальная часть платформы

FAQ

Есть ли параметр консистентности или силы? Нет. Схема входных данных принимает только prompt, image_urls, aspect_ratio, resolution и output_format; всё остальное отклоняется с 400. Чтобы управлять тем, насколько выходной результат следует за исходным изображением, явно укажите в промпте, что должно быть сохранено («сохрани продукт и этикетку в точности, измени только фон»), и передайте до 3 референсных изображений через image_urls.

Могу ли я загрузить локальный файл или отправить base64? Напрямую — нет, image_urls принимает URL, и платформа получает их на стороне сервера. Загрузите файл в любое общедоступное хранилище (S3, R2, CDN) и передайте этот URL.

Сколько исходных изображений можно передать? От 1 до 3. Пустой массив завершится ошибкой minItems: got 0, want 1; больше 3 — ошибкой maxItems.

Какие разрешения и соотношения сторон поддерживаются? resolution — 1k или 2k (только в нижнем регистре). aspect_ratio поддерживает 14 значений от 2:1 до 1:2, включая auto, 16:9, 1:1, 9:16 и подходящие для телефонов 9:19.5/9:20.

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

Как сгенерировать несколько вариантов? Параметра n нет — для каждого варианта создавайте задачу. Задачи выполняются независимо, поэтому можно отправлять несколько параллельно.

Что означает 401 permission_denied, если мой ключ верный? Ключ существует, но не может использовать эту модель (план или область разрешений). Проверьте права ключа на модели в панели управления или обратитесь в поддержку с request_id из тела ответа с ошибкой.