Как использовать Recraft Creative Upscale API: curl, Python и один реальный запуск

TL;DR

• recraft/creative-upscale увеличивает изображение и перерисовывает его текстуры и детали. В теле запроса только одно поле — image_url. Ни промпта, ни настроек масштабирования.
• Он работает через единый процесс /v1/tasks: POST возвращает taskId, затем опрос GET /v1/tasks/<taskId>, а скачивание — из data.output[0].url.
• В нашем запуске PNG 1254×1254 вернулся примерно через 60 секунд как WebP 4096×4096, около 19,8 МБ. Заложите бюджет на время ожидания и размер файла.

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

API-ключ hiapi из консоли и публично доступный URL изображения. На странице модели перечислены ограничения на вход: рекомендуемый PNG, максимум 20 МБ, 256–4096 px по каждой стороне, максимум 16 МП.

Если вам нужно, чтобы текст, логотипы или детали продукта оставались неизменными, используйте вместо этого Recraft Crisp Upscale. Creative Upscale перерисовывает изображение, поэтому небольшие элементы могут измениться.

Минимальный запрос curl

export HIAPI_KEY=sk-your-key

curl -s https://www.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "recraft/creative-upscale",
    "input": { "image_url": "https://example.com/old-illustration.png" }
  }'

Ответ — это дескриптор задачи:

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

Опрашивайте её, пока data.status не станет success:

curl -s https://www.hiapi.ai/v1/tasks/tk-hiapi-01M5K8J899THH6XJK99TAZ4VSD \
  -H "Authorization: Bearer $HIAPI_KEY"

Python: отправка, опрос, сохранение

import os, time, requests

BASE = "https://www.hiapi.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def upscale(image_url: str, out_path: str) -> str:
    r = requests.post(f"{BASE}/v1/tasks", headers=HEADERS, timeout=30, json={
        "model": "recraft/creative-upscale",
        "input": {"image_url": image_url},
    })
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    deadline = time.time() + 300
    while time.time() < deadline:
        time.sleep(5)
        try:
            d = requests.get(f"{BASE}/v1/tasks/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        except requests.RequestException:
            continue  # transient network error: keep polling the SAME taskId
        if d["status"] == "success":
            url = d["output"][0]["url"]
            with open(out_path, "wb") as f:
                f.write(requests.get(url, timeout=120).content)
            return task_id
        if d["status"] in ("fail", "failed"):
            raise RuntimeError(f"task {task_id} failed: {d}")
    raise TimeoutError(f"task {task_id} still running; re-poll it, do not resubmit")

upscale("https://example.com/old-illustration.png", "upscaled.webp")

В продакшене важны две детали. Во-первых, никогда не отправляйте запрос повторно после таймаута: каждая отправка создаёт новую платную задачу, поэтому сохраняйте taskId и опрашивайте его снова. Во-вторых, сохраняйте файл сразу: URL вывода содержит expireAt, а хост временный.

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

• Используйте callback для пакетных задач. Вместо опроса можно передать в теле задачи callback: {"url": "...", "when": "final"}, и hiapi вызовет вас по завершении задачи. Используйте taskId как ключ дедупликации.
• Интервала опроса в 5 секунд достаточно. Одна задача занимает около минуты, поэтому более частый опрос лишь добавляет запросы.
• Проверяйте URL перед отправкой. Платформа заранее отклоняет некорректные URL (см. ниже), но недоступный https:// URL — это другой тип отказа, который лучше отловить на своей стороне быстрым запросом HEAD.

Что мы увидели в одном реальном запуске

Мы выполнили один реальный запрос с примером входного изображения со страницы модели (PNG 1254×1254 с домиком в горах).

Пункт	Наблюдение
Ответ на отправку	{"code":200,"data":{"taskId":"tk-hiapi-01M5K8J899THH6XJK99TAZ4VSD"}}
Последовательность статусов	handling → archiving → success
Время от created до completed	61 секунда (1792721625 → 1792721686)
Вывод	Одно изображение, WebP, https://temp.hiapi.ai/.../...-0.webp, с expireAt примерно через 7 дней
Размер входа	PNG 1254×1254, 2,7 МБ
Размер вывода	WebP 4096×4096, около 19,8 МБ

Что стоит знать из того запуска:

1. На этапе archiving ещё нет output. Задача в течение нескольких опросов сообщает completed и status: "archiving", пока результат не будет перемещён в хранилище. Только status == "success" содержит output[0].url, поэтому не читайте URL, как только впервые увидели отметку времени completed.
2. Результат — не чистое удвоение. Вход 1254 px превратился в 4096 px, примерно в 3,3 раза по каждой стороне. На странице модели показана та же пара, и поле масштабирования там не предусмотрено, поэтому ожидайте, что размер вывода определяет модель, а не вы. Если вам нужно ровно 2×, Crisp Upscale — это эндпоинт, соответствующий такому условию.
3. Файл вывода большой. Одно изображение весит 19,8 МБ, что превышает лимит входа в 20 МБ, позволяющий сразу подать его обратно, поэтому не запускайте второй проход по выводу без изменения размера.
4. Детали перерисовываются, а не просто повышается резкость. Собственное описание этой пары изображений на странице модели таково: композиция, освещение и цвета в основном сохраняются, а брёвна, каменная кладка и перила перерисовываются; некоторые мелкие элементы (например, дерево рядом с крыльцом) меняются. Проверяйте вывод перед заменой фирменных материалов.
5. Неверный URL приводит к быстрому отказу. Отправка "image_url": "not-a-url" сразу возвращает HTTP 400: {"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: image_url: 'not-a-url' does not match pattern '^https?://'"}. Эта проверка по шаблону — единственное, что мы проверили; мы не тестировали минимум в 256 px или верхний предел в 16 МП.

Мы запустили только одну задачу, поэтому цифра в 61 секунду — единичный пример, а не бенчмарк.

Creative Upscale или Crisp Upscale?

Оба принимают только один image_url и не требуют промпта. Разница — в том, как они обращаются с пикселями, и в цене.

	Creative Upscale	Crisp Upscale
ID модели	recraft/creative-upscale	recraft/crisp-upscale
Поведение	Увеличивает и перерисовывает текстуры и детали	Удваивает ширину и высоту, сохраняя содержимое и текст
Лучше всего подходит для	Старых иллюстраций, небольших или низкодетализированных артов	Фотографий продуктов, постеров с текстом, дизайнерских материалов
Цена	Гораздо выше за изображение; см. цены	См. статью о ценах Crisp

Цена Creative Upscale за изображение намного выше, чем у Crisp (сравнивайте актуальные цифры на странице цен), поэтому используйте его только тогда, когда вы действительно хотите, чтобы детали были созданы заново. Для универсального рабочего процесса повышения разрешения с разными моделями см. повышение разрешения изображений с помощью hiapi.

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

• Страница модели Recraft Creative Upscale
• Руководство по Recraft Crisp Upscale API
• Руководство по Recraft Remove Background API: сначала увеличьте, затем вырежьте объект
• Повышение разрешения изображений с помощью hiapi API
• Цены hiapi

FAQ

Нужен ли мне промпт? Нет. На странице модели описано, что на вход подаётся одно изображение, без промпта и других настроек; в нашем запросе использовался только image_url.

Могу ли я выбрать размер вывода? Через API — нет. Поля масштабирования нет; наш вход 1254 px вернулся как 4096 px.

Сохранятся ли текст и логотипы? Не гарантируется. Детали создаются заново, небольшие элементы могут измениться, поэтому для материалов с текстом используйте Crisp Upscale.

Какой формат вывода я получу? В нашем запуске — WebP, доставляемый по временному URL, который истекает, поэтому скачивайте сразу.

Сколько времени это занимает? Наш единственный запуск занял около минуты; рассчитывайте время ожидания клиента примерно на такой порядок.