Как использовать API wan2.7-image-standard на hiapi: генерация изображений по тексту и редактирование по референсу

wan2.7-image-standard — это стандартная версия модели Wan 2.7 Image от Tongyi Wanxiang. Причина, по которой она заслуживает отдельной страницы, заключается в том, что один и тот же ID модели поддерживает и генерацию изображений по тексту, и редактирование изображений на основе референса, с максимальным разрешением 2K и фиксированной ценой $0.0345 за изображение — дешевле, чем версия Pro с поддержкой 4K. Это руководство содержит готовый к запуску запрос, точную входную схему (проверенную на живом API), путь редактирования по референсу и граничные случаи поведения, которые необходимо обрабатывать в производственной среде.

Всё в разделах схемы и ошибок ниже было подтверждено путём обращения к живому эндпоинту /v1/tasks во время написания — списки перечислений, допустимые наборы полей и формы ответов об ошибках взяты из реальных ответов API, а не по памяти.

Что вы создадите и что вам понадобится

Вы отправите запрос с промптом (необязательно с референсным изображением), будете опрашивать статус до завершения задачи, а затем скачаете изображение. Сначала нужно одно: получить API-ключ из краткого руководства hiapi и экспортировать его в HIAPI_API_KEY. Пути без ключа не существует — каждый запрос аутентифицируется через Authorization: Bearer sk-<your-key>.

wan2.7-image-standard работает на асинхронном API задач hiapi: сначала вы создаёте задачу через POST /v1/tasks, затем опрашиваете эндпоинт деталей, пока он не сообщит о терминальном состоянии.

Генерация по тексту: минимальный запрос

Создайте задачу:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-image-standard",
    "input": {
      "prompt": "Синий час после дождя, тихий безлюдный переулок с маленькой гончарной мастерской, тёплые бумажные фонарики, глазурованные чайники в витрине, огни отражаются на мокрой брусчатке, велосипед прислонён к стене, кинематографичная съёмка 35 мм, высокая детализация",
      "aspect_ratio": "16:9",
      "resolution": "2K"
    }
  }'

ID задачи находится в ответе в поле data.taskId:

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

Затем опрашивайте GET /v1/tasks/<taskId>, пока data.status не станет success, и читайте URL изображения из data.output[0].url:

import os, time, requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

def generate(prompt, aspect_ratio="16:9", resolution="2K", image_urls=None, timeout=600):
    payload = {"model": "wan2.7-image-standard",
               "input": {"prompt": prompt,
                         "aspect_ratio": aspect_ratio,
                         "resolution": resolution}}
    if image_urls:                      # редактирование по референсу (см. следующий раздел)
        payload["input"]["image_urls"] = image_urls

    create = requests.post(API, headers=HEADERS, json=payload).json()
    if create.get("code") != 200:       # синхронная ошибка валидации (например, недопустимое значение перечисления)
        raise RuntimeError(create)
    task_id = create["data"]["taskId"]

    deadline = time.time() + timeout
    while time.time() < deadline:
        data = requests.get(f"{API}/{task_id}", headers=HEADERS).json()["data"]
        if data["status"] == "success":
            return requests.get(data["output"][0]["url"]).content
        if data["status"] == "fail":    # терминальный сбой — не продолжайте опрос
            raise RuntimeError(data.get("error"))
        time.sleep(5)
    raise TimeoutError(task_id)

png = generate("...")   # сохраните байты сразу — см. примечание об истечении срока ниже

aspect_ratio и resolution необязательны (у модели есть значения по умолчанию), но задавайте их явно — resolution принимает только 1K или 2K, и оба варианта стоят одинаково, поэтому нет никаких причин оставлять значение по умолчанию.

Редактирование по референсу: тот же ID модели плюс image_urls

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

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-image-standard",
    "input": {
      "prompt": "Разместите этот продукт на залитой солнцем мраморной кухонной столешнице, рядом свежие травы, мягкий утренний свет, лайфстайл-съёмка продукта",
      "image_urls": ["https://your-storage.example.com/product.jpg"],
      "resolution": "2K"
    }
  }'

В Python это просто параметр image_urls=[...], передаваемый вспомогательной функции выше — всё остальное не меняется. Даже при передаче референсных изображений prompt остаётся обязательным (API отклонит запрос без prompt: missing required field "prompt").

Имя поля имеет значение: именно image_urls. Правдоподобные альтернативные имена — reference_image_urls, image_input, input_urls — будут отклонены схемой с ошибкой additional properties '<name>' not allowed. Если вы переносите код из эндпоинта редактирования другой модели, это первое, что нужно исправить.

Точная входная схема

Схема строгая: любое поле, отсутствующее в приведённом ниже списке, возвращает 400 INVALID_REQUEST с сообщением additional properties '<name>' not allowed. Вот полный набор принимаемых полей:

Поле	Тип	Обязательно	Описание
prompt	string	Да	Обязательно как для генерации по тексту, так и для редактирования. Можно на английском или китайском.
aspect_ratio	string enum	Нет	Одно из значений: 1:1, 16:9, 4:3, 21:9, 3:4, 9:16, 8:1, 1:8. Любое другое значение (например, 3:2) → 400.
resolution	string enum	Нет	Только 1K или 2K. 4K в этой версии не поддерживается.
image_urls	string[]	Нет	Референсные изображения для редактирования (до 9). При передаче переключает в режим референса.
seed	integer	Нет	Для воспроизводимых результатов.

Поля, которые вы могли бы предположить, но которые эта модель не принимает: negative_prompt, n, size и prompt_optimizer — все будут отклонены как неизвестные свойства. Параметра пакетной обработки (n) нет — по одной задаче на каждое изображение.

Производственные заметки и проверенное поведение

Ответ 200 при отправке не означает, что изображение обязательно будет сгенерировано. wan2.7-image-standard синхронно проверяет значения перечислений (неверный resolution или aspect_ratio немедленно приводит к сбою POST с 400 INVALID_REQUEST), но не проверяет референсные URL при отправке. Некорректные или недоступные элементы image_urls принимаются, возвращается 200 и taskId, а затем задача завершается сбоем примерно через секунду. Я проверил это напрямую: задача, созданная с недействительным референсным URL, вернула такое терминальное состояние

{ "status": "fail", "error": { "code": "INVALID_REQUEST", "message": "invalid request parameters for this model" } }

Практический вывод: всегда опрашивайте до терминального состояния и обрабатывайте сбой по ветке data.status == "fail" (читая data.error). Неудачные задачи возвращаются как HTTP 200 с data.status: "fail" — информация об ошибке находится в data.error, а не в виде ошибки HTTP верхнего уровня. Перед отправкой убедитесь, что ваши референсные URL общедоступны.

Скачивайте результат сразу. data.output[0].url — это временная ссылка с меткой времени expireAt, а не постоянный ресурс CDN. Получите байты и перенесите их в собственное хранилище в момент успеха задачи; просроченный URL вернёт 404. Если вы уже столкнулись с этой проблемой, см. почему ваш выходной URL hiapi возвращает 404 и что с этим делать.

Опрос или обратные вызовы. Пример выше опрашивает каждые пять секунд, что подходит для скриптов и малых объёмов. Для производственной пропускной способности добавьте callback в запрос создания, чтобы hiapi уведомлял вас о терминальных событиях, вместо того чтобы вы держали соединение — механизм описан в документации по созданию задачи.

Стандартная версия против Pro: какую выбрать

hiapi размещает две версии Wan 2.7 Image — это разные ID моделей, а не параметры:

• wan2.7-image-standard (это руководство) — генерация по тексту и редактирование по референсу, 1K/2K, фиксированная цена $0.0345 за изображение независимо от разрешения.
• wan2.7-image/text-to-image — версия Pro: только генерация по тексту, до 4K, фиксированная цена $0.08 за изображение. См. страницу Wan 2.7 Image Pro и подробное руководство по созданию с её помощью 4K изображений товаров для электронной коммерции.

Выбирайте стандартную версию, когда вам нужно редактирование по референсу или когда достаточно 2K и вы хотите платить менее половины цены Pro за изображение. Используйте Pro только когда вам действительно нужен нативный вывод 4K — это единственное, чего стандартная версия не умеет. Актуальные цены на обе версии см. на странице тарифов.

Частые вопросы

Поддерживает ли wan2.7-image-standard редактирование изображений или только генерацию по тексту? И то и другое, в рамках одного ID модели. Добавьте массив image_urls, чтобы переключиться на редактирование по референсу; опустите его — и получите чистую генерацию по тексту.

Каково максимальное разрешение? 2K. Поле resolution принимает только 1K и 2K; живой API отклоняет любые другие значения. Если вам нужно 4K, используйте версию Pro (wan2.7-image/text-to-image).

Почему моя задача вернула 200, а затем завершилась сбоем? Референсные URL не проверяются при отправке — только при выполнении. Недоступные или некорректные элементы image_urls создают задачу (HTTP 200), а затем она завершается сбоем в терминальном состоянии INVALID_REQUEST. Опрашивайте data.status и проверяйте, что ваши URL общедоступны.

Можно ли задать негативный промпт? Нет. negative_prompt не является полем, принимаемым этой моделью (как и n, size или prompt_optimizer). Управляйте результатом через позитивный prompt и seed.