Как повысить разрешение изображений с помощью API hiapi: рабочий процесс апскейлинга до 4K

Если у вас есть изображение продукта в низком разрешении, маленькая миниатюра, сгенерированная ИИ, или старый скан, и вам нужна чёткая версия в 2K/4K, вам не нужен отдельный сервис суперразрешения. Единый эндпоинт /v1/tasks в hiapi позволяет отправлять одинаковые запросы к нескольким моделям изображений — эти модели принимают существующее изображение и перерисовывают его в более высоком разрешении. Этот материал показывает полный рабочий процесс: отправку задачи, опрос (или получение обратного вызова) для получения результата, а затем скачивание увеличенного файла.

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

Что вы создадите и что нужно подготовить заранее

Вы создадите небольшой скрипт, который:

1. Загружает ссылку на ваше существующее изображение (подойдёт любой публичный URL — ваш собственный CDN, R2, S3 и т. п.)
2. Отправляет задачу «изображение в изображение» с запросом на перерисовку в 4K
3. Опрашивает статус до завершения задачи и скачивает результат в более высоком разрешении

Перед началом:

• Аккаунт hiapi и ключ API, созданный на странице API Keys в панели управления. Каждому запросу ниже требуется Authorization: Bearer sk-<your-key> — без ключа вызвать эти эндпоинты невозможно.
• Публично доступный URL, указывающий на изображение, которое вы хотите увеличить. Рабочие процессы задач hiapi загружают изображение на сервере, поэтому пути localhost или приватные бакеты не подойдут — сначала загрузите файл на любой публичный хост.
• Python 3.8+ с установленным requests (pip install requests) или, если хотите тестировать в shell, достаточно curl.

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

Самый чистый вариант — seedream-5.0-lite/image-to-image. Его входная схема требует ровно четыре поля — prompt, image_urls, aspect_ratio и resolution — а resolution принимает только 2K или 4K (на этом маршруте нет уровня 1K, что как раз означает, что вы не сможете случайно заставить его уменьшить ваше изображение).

import time
import requests

API_KEY = "sk-your-hiapi-key"  # from https://www.hiapi.ai/en/dashboard/api-keys
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

def create_upscale_task(source_image_url: str) -> str:
    payload = {
        "model": "seedream-5.0-lite/image-to-image",
        "input": {
            "prompt": "Same image, preserved composition and colors, sharp fine detail, no artifacts",
            "image_urls": [source_image_url],
            "aspect_ratio": "1:1",   # match your source image's ratio
            "resolution": "4K",
        },
    }
    resp = requests.post(BASE, headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    body = resp.json()
    task_id = body["data"]["taskId"]
    return task_id

def wait_for_result(task_id: str, timeout_s: int = 300, poll_every: int = 5) -> str:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()["data"]
        if task["status"] == "success":
            return task["output"][0]["url"]
        if task["status"] == "fail":
            err = task.get("error", {})
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(poll_every)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

if __name__ == "__main__":
    task_id = create_upscale_task("https://your-cdn.example.com/product-photo-small.jpg")
    result_url = wait_for_result(task_id)
    print("4K result:", result_url)

Если вы просто хотите посмотреть, как выглядит запрос, вот эквивалентный вызов создания задачи через curl:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-your-hiapi-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-lite/image-to-image",
    "input": {
      "prompt": "Same image, preserved composition and colors, sharp fine detail, no artifacts",
      "image_urls": ["https://your-cdn.example.com/product-photo-small.jpg"],
      "aspect_ratio": "1:1",
      "resolution": "4K"
    }
  }'

По поводу этого запроса стоит отметить несколько моментов:

• image_urls — это массив, даже если эта модель читает только первый элемент. Передача голой строки вместо списка — частая причина ошибки 400.
• URL результата истекает. Как только wait_for_result() вернёт значение, сразу скачайте байты и сохраните их самостоятельно — не используйте ссылку, размещённую hiapi, как постоянный URL вашего ресурса.
• Если ваше исходное изображение не квадратное, установите aspect_ratio в соответствии с ним (4:3, 16:9, 9:16, 3:2, 2:3 или 21:9), чтобы модель не обрезала и не дополняла ваш объект.

Как делать это в продакшене

При масштабировании используйте обратные вызовы вместо опроса. Если изображений для увеличения больше нескольких, не бомбардируйте GET /v1/tasks/<id> в цикле для каждой задачи — передайте объект callback, чтобы hiapi сам отправил вам результат:

payload = {
    "model": "seedream-5.0-lite/image-to-image",
    "input": {...},
    "callback": {
        "url": "https://your-service.example.com/hooks/hiapi-task",
        "when": "final",
    },
}

Ваш webhook получит тот же объект задачи, что и при опросе (status, output, error) — проверяйте его структуру защитно, поскольку сетевые повторы могут доставить его более одного раза.

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

Обрабатывайте две принципиально разные формы ошибок. Неверно сформированное тело запроса возвращает HTTP 400 с плоским {"code": 400, "error_code": "INVALID_REQUEST", "message": "..."}. Отсутствующий или неверный ключ API возвращает HTTP 401 с вложенным {"error": {"code": "permission_denied", "message": "..."}}. Сначала проверьте код состояния, затем ветвитесь:

if resp.status_code == 401:
    raise RuntimeError(f"auth error: {resp.json()['error']['message']}")
if resp.status_code == 400:
    raise RuntimeError(f"bad request: {resp.json()['message']}")
resp.raise_for_status()

Выбирайте модель в зависимости от того, какие входные данные у вас есть. Все три маршрута ниже находятся на одном эндпоинте /v1/tasks — различаются только строка model и поля input:

Что у вас есть	Модель	Обязательные поля input
Существующее изображение, нужна чистая перерисовка в 2K/4K	seedream-5.0-lite/image-to-image	prompt, image_urls, aspect_ratio, resolution (2K|4K)
Существующее изображение, нужен выбор между качеством и стоимостью	gpt-image-2/image-to-image@ext	prompt, image_urls, quality (low|medium|high), resolution (1K|2K|4K)
Нет исходного изображения — сгенерировать новый высокоразрешённый ресурс по текстовому описанию	wan2.7-image/text-to-image	prompt (плюс необязательные resolution и aspect_ratio)

Обратите внимание на суффикс @ext во второй строке — это вариант маршрута базовой модели gpt-image-2 (hiapi открывает некоторые модели более чем под одним маршрутом с несколько иными тарифами/уровнями качества), а не отдельное семейство моделей. Точная стоимость каждого запроса для каждой из них зависит от выбранного разрешения и уровня качества, поэтому смотрите актуальные цифры на странице тарифов, а не зашивайте значения в логику бюджетирования.

Проверяйте до отправки. Все три модели отклоняют неизвестные поля input напрямую (additional properties 'x' not allowed), а не игнорируют их молча, а такие перечислимые поля, как resolution и aspect_ratio, чувствительны к регистру и значению. Если вы создаёте обёртку, проверяйте на клиенте по точным перечислимым значениям выше, чтобы опечатки быстро давали сбой, а не тратили запрос впустую.

Похожие материалы

• Wan 2.7 Image — API текст-в-изображение, генерация совершенно новых изображений высокого разрешения только по подсказке.
• API GPT Image 2, альтернатива с уровнями качества/разрешения, использованная в таблице выше.
• Тарифы API hiapi, чтобы узнать текущую стоимость каждого запроса для каждой модели и уровня.
• Документация hiapi, полный справочник по жизненному циклу задач, включая все параметры обратных вызовов.

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

Есть ли у hiapi специальная модель увеличения изображений или суперразрешения? Специальной модели, сохраняющей пиксели, нет. Рабочий процесс выше использует универсальные модели «изображение в изображение», которые заново генерируют ваше изображение в более высоком разрешении — это хорошо работает для фотографий и иллюстраций, но не является увеличением без потерь.

Могу ли я повысить разрешение, не меняя содержимое изображения? Вы можете добиться очень близкого результата, подсказывая модели точно сохранять композицию, цвета и объект («то же изображение, не менять композицию, не добавлять и не удалять элементы, только добавить детали и резкость»), но поскольку это генеративная перерисовка, а не интерполяция, на мелких текстурах всё же будут небольшие отличия по сравнению с настоящим увеличением без потерь.

Какое максимальное разрешение я могу получить? Верхний предел для всех трёх моделей выше — уровень разрешения 4K. Если вам нужен размер больше этого, придётся разбить исходное изображение на блоки, увеличить каждый блок отдельно или добавить на клиенте шаг масштабирования после вызова API.

Нужен ли ключ API, чтобы попробовать это? Да — каждый вызов /v1/tasks требует Authorization: Bearer sk-<your-key>. Для создания задач нет песочницы без ключа; сначала получите ключ в панели управления.

Могу ли я пакетно увеличить целую папку изображений? Да — пройдитесь по URL ваших изображений, отправьте по одной задаче на каждое изображение, а затем либо опрашивайте каждый taskId, либо (что лучше при большом объёме) зарегистрируйте URL обратного вызова и сопоставляйте результаты со своими задачами по taskId, сохранённому при создании каждой задачи.

Почему мой запрос завершается ошибкой «additional properties not allowed»? Вы отправили поле, которое не знает схема модели — например, использовали size вместо resolution + aspect_ratio или скопировали лишний параметр из примеров других моделей. Смотрите таблицу обязательных полей выше, чтобы узнать точные имена полей, принимаемые каждой моделью.