HiAPI
Ru
Блог

Руководство

Как использовать seedream-5.0-lite в режиме «изображение в изображение» через hiapi API

Jul 7, 2026
Как использовать seedream-5.0-lite в режиме «изображение в изображение» через hiapi API

Это руководство покажет вам, как вызывать режим «изображение в изображение» seedream-5.0-lite через унифицированный API задач hiapi: точная структура запроса, готовые к запуску команды curl, Python-скрипт, который можно вставить в бэкенд, а также ловушки валидации, которые этот модель принудительно проверяет, а другие модели — нет.

После прочтения этой статьи у вас будет скрипт, который принимает один или несколько URL опорных изображений и одну подсказку для редактирования, а возвращает URL сгенерированного изображения, готового к немедленной загрузке.

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

  • Учётная запись hiapi и ключ API. Их можно получить в консоли hiapi.
  • Одно или несколько опорных изображений, размещённых на публичных HTTPS URL. Эта модель принимает до 14 опорных изображений за один запрос — именно это делает её полезной для рабочих процессов с несколькими опорными изображениями: объединение объекта с одного изображения со стилем или сценой другого.
  • Текстовая подсказка, описывающая редактирование или преобразование (минимум 3 символа — да, API это проверяет).

Все запросы отправляются на унифицированную конечную точку задач, ключ передаётся в заголовке Authorization:

POST https://api.hiapi.ai/v1/tasks
Authorization: Bearer sk-<your-key>
Content-Type: application/json

Структура запроса (и требования этой модели)

Идентификатор модели — seedream-5.0-lite/image-to-image — передавайте его как есть, точно так, как он указан в /v1/models. Его схема input строгая: все четыре поля обязательны:

Поле Тип Описание
prompt string Инструкция для редактирования. Минимальная длина — 3.
image_urls string[] URL от 1 до 14 опорных изображений.
aspect_ratio string Одно из значений: 1:1, 4:3, 3:4, 16:9, 9:16, 2:3, 3:2, 21:9.
resolution string Только 2K или 4K. У этой модели нет уровня 1K.

Те, кто мигрирует с других моделей на платформе, часто наступают на две грабли:

  1. resolution принимает только 2K или 4K. Если ваш общий код отправки задач по умолчанию подставляет "1K" (что работает во многих других моделях изображений), эта модель отклонит запрос с ошибкой 400.
  2. Лишние поля отклоняются, а не игнорируются. Отправка size, n или чего-либо ещё вне схемы возвращает 400 INVALID_REQUEST с сообщением additional properties '<field>' not allowed. API задач валидирует input по каждой модели — не копируйте payload другой модели вслепую.

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

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

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-lite/image-to-image",
    "input": {
      "prompt": "Replace the background with a sunlit Tokyo street at golden hour, keep the subject unchanged",
      "image_urls": ["https://your-cdn.example.com/subject.png"],
      "aspect_ratio": "3:2",
      "resolution": "2K"
    }
  }'

После успешной отправки в data возвращается id задачи:

{"code": 200, "data": {"taskId": "task_abc123..."}}

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

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

Во время выполнения data.status равен pending/processing. После завершения он становится "success", а изображения появляются в data.output:

{
  "code": 200,
  "data": {
    "status": "success",
    "output": [{"url": "https://.../result.png", "expireAt": "..."}]
  }
}

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

Несколько опорных изображений: передача нескольких картинок

Чтобы объединить несколько опорных изображений — например, изображение продукта и изображение-референс стиля — просто добавьте больше URL в image_urls и укажите в подсказке, какой вклад вносит каждое изображение:

{
  "model": "seedream-5.0-lite/image-to-image",
  "input": {
    "prompt": "Place the product from the first image into the scene from the second image, matching its lighting and color grade",
    "image_urls": [
      "https://your-cdn.example.com/product.png",
      "https://your-cdn.example.com/scene-reference.jpg"
    ],
    "aspect_ratio": "1:1",
    "resolution": "2K"
  }
}

Жёсткий лимит — 14 URL; 15-й вернёт 400 INVALID_REQUEST: image_urls: maxItems: got 15, want 14. На практике 2–4 тщательно подобранных опорных изображения вместе с подсказкой, явно задающей роль каждому изображению («сохрани объект с изображения 1, используй цветовую палитру изображения 2»), дают гораздо более управляемый результат редактирования, чем куча слабо связанных картинок.

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

Готовый к продакшену Python: отправка, опрос, загрузка

import time
import requests

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


def edit_image(prompt: str, image_urls: list[str],
               aspect_ratio: str = "1:1", resolution: str = "2K") -> bytes:
    # 1. Создаём задачу
    resp = requests.post(API_BASE, headers=HEADERS, json={
        "model": "seedream-5.0-lite/image-to-image",
        "input": {
            "prompt": prompt,
            "image_urls": image_urls,
            "aspect_ratio": aspect_ratio,
            "resolution": resolution,  # эта модель: только "2K" или "4K"
        },
    }, timeout=60)
    body = resp.json()
    if resp.status_code != 200 or not (body.get("data") or {}).get("taskId"):
        raise RuntimeError(f"create failed [{resp.status_code}]: {body}")
    task_id = body["data"]["taskId"]

    # 2. Опрашиваем до конечного состояния
    deadline = time.time() + 600
    while time.time() < deadline:
        task = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS,
                            timeout=30).json().get("data") or {}
        if task.get("status") == "success":
            outputs = task.get("output") or []
            if not outputs or not outputs[0].get("url"):
                raise RuntimeError(f"task {task_id} succeeded but returned no output URL")
            # 3. Скачиваем сразу — URL истекает
            img = requests.get(outputs[0]["url"], timeout=120)
            img.raise_for_status()
            return img.content
        if task.get("status") == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(5)
    raise TimeoutError(f"task {task_id} still running after 600s")


if __name__ == "__main__":
    png = edit_image(
        "Replace the background with a minimalist studio backdrop, keep the subject unchanged",
        ["https://your-cdn.example.com/subject.png"],
        aspect_ratio="3:2",
    )
    with open("edited.png", "wb") as f:
        f.write(png)
    print(f"saved edited.png ({len(png)} bytes)")

Использование callback вместо опроса

Опрос подходит для скриптов и очередей воркеров. Для веб-бэкенда зарегистрируйте callback при создании задачи, чтобы hiapi передавал вам конечное состояние — объект callback находится на верхнем уровне запроса, рядом с model:

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

С "when": "final" вы получите ровно один POST, когда задача перейдёт в success или fail. У обработчика два правила:

  • Сделайте его идемпотентным. Используйте id задачи как ключ обработки, чтобы повторная доставка webhook не приводила к повторной обработке. Сохраняйте id задачи при отправке и рассматривайте callback как уведомление «сходи и заверши», а не как единственный источник истины.
  • Сохраните путь сверки. Если ваш эндпоинт недоступен в момент срабатывания callback, периодическая проверка незавершённых id и GET /v1/tasks/<id> поймают пропущенные.

Если ваш callback, кажется, так и не приходит, перебирайте типичные режимы отказа по степени вероятности из статьи почему ваш callback задачи hiapi не срабатывает.

Обработка ошибок: три действительно важных сбоя

401 permission_denied при создании — ваш ключ не может использовать эту модель. Тело ответа выглядит так:

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

Проверьте права ключа на модели в консоли или используйте ключ с включёнными моделями изображений.

400 INVALID_REQUEST при создании — ваш input не соответствует схеме этой модели. Сообщение перечисляет все нарушающие поля сразу (например, resolution: value must be one of '2K', '4K'; <root>: additional properties 'size' not allowed), поэтому читайте его полностью и исправляйте все поля за один раз. Это постоянные ошибки — повтор с тем же payload всегда будет неудачным.

status: "fail" у задачи — создание прошло успешно, но генерация не удалась (опорный URL, недоступный бэкенду, политика контента, ёмкость вышестоящего сервиса). error.code и error.message задачи объяснят причину. В отличие от 400, некоторые из них временные и заслуживают одной повторной попытки с задержкой.

Также стоит знать: GET для несуществующего или истёкшего id задачи возвращает 404 task not found — при сканировании сверки это следует считать конечным состоянием, а не «всё ещё в ожидании».

Куда двигаться дальше

FAQ

Сколько опорных изображений можно передать в seedream-5.0-lite «изображение в изображение»? Массив image_urls принимает до 14 изображений. Минимум одно — это поле обязательно, поэтому для вызовов чисто текстовой генерации следует использовать seedream-5.0-lite/text-to-image.

Почему другие модели работают с 1K, а я получаю «value must be one of '2K', '4K'»? Схема входных данных API задач определяется для каждой модели. Режим «изображение в изображение» seedream-5.0-lite предлагает только выход 2K и 4K; другие модели предлагают уровень 1K. Не копируйте payload другой модели, не проверив его.

Могу ли я отправлять опорные изображения в base64 вместо URL? Схема этой модели принимает image_urls — массив URL. Разместите изображения на доступном HTTPS URL (подойдёт любой CDN, бакет объектного хранилища или предподписанный URL) и передайте этот URL.

Сколько занимает одна генерация и как долго действует URL вывода? Обычно значительно меньше бюджета опроса в 600 секунд из примера на Python выше. URL вывода имеет метку времени expireAt — сразу после успешного завершения задачи скачайте байты и сохраните в своё хранилище.

Тот же код подойдёт для seedream-5.0-lite «текст в изображение»? Конечная точка и процесс те же, но у «текст в изображение» своя схема input (без image_urls). Замените id модели на seedream-5.0-lite/text-to-image и уберите опорные изображения — затем проверьте одним тестовым вызовом, поскольку обязательные поля в разных режимах различаются.

Сколько стоит каждое изображение? Цена рассчитывается за использование каждой генерации и зависит от разрешения. Актуальные ставки смотрите на странице тарифов.

ТегирецептГенерация изображенийseedreamУчебное пособие

Похожие статьи

Все статьи →

Начните работать с постоянными артефактами ИИ

Получите API-ключ и вызывайте модели изображений, видео и аудио через один API на основе tasks.

Читать документацию API