Ошибка ввода изображения в HiAPI: передавайте общедоступный URL, а не Base64

Модели image-to-image и модели с референсными изображениями в HiAPI получают ваше исходное изображение по общедоступному HTTP(S) URL — они не принимают base64-строки байтов и не могут обратиться к приватным адресам. Самая коварная ловушка: ошибочный ввод изображения выглядит как успешный — POST /v1/tasks возвращает 200 с taskId, а настоящая ошибка всплывает только когда вы начинаете опрашивать задачу. Вот две ошибки, которые вы реально увидите:

{ "code": 200, "message": "success",
  "data": { "status": "fail", "model": "gpt-image-2/image-to-image", "storage": "temp", "taskId": "tk-...",
    "error": { "code": "INVALID_REQUEST",
      "message": "The image URL could not be downloaded. Please provide a reachable public HTTP(S) URL and try again." } } }

{ "code": 200, "message": "success",
  "data": { "status": "fail", "model": "gpt-image-2/image-to-image", "storage": "temp", "taskId": "tk-...",
    "error": { "code": "TASK_FAILED", "message": "task failed" } } }

Первый — ответ на недоступный URL; второй — общий результат, который вы получаете, передав base64 data URI в качестве изображения — никаких подсказок, только task failed, и именно здесь люди застревают чаще всего. Обратите внимание: внешнее "message": "success" означает лишь то, что сам запрос опроса прошёл успешно, а настоящий результат находится в data.status.

Частые причины (по убыванию вероятности)

• Вы вставили base64 в поле изображения — строку вида data:image/...;base64,.... Этому полю нужен URL, который сервер может загрузить, а не встроенные байты. В gpt-image-2/image-to-image data URI принимается на этапе отправки, после чего задача завершается со status: fail и кодом ошибки TASK_FAILED / task failed.

• URL не общедоступен. http://localhost, 127.0.0.1, внутренние IP, файлы, доступные только после входа, просроченные предподписанные ссылки — всё это падает с INVALID_REQUEST — "The image URL could not be downloaded…".

• Неверное имя поля (у разных моделей по-разному, см. таблицу ниже). Поле ввода изображения не унифицировано между семействами моделей. Неверное имя отклоняется HTTP 400 ещё на этапе отправки, например при использовании image_url в gpt-image-2/image-to-image:

  { "code": 400, "data": null, "error_code": "INVALID_REQUEST",
    "message": "invalid input: input_urls: missing required field \"input_urls\"; <root>: additional properties 'image_url' not allowed" }
  

• Вы использовали голый model id для редактирования. Голый id (например, gpt-image-2) — это чисто text-to-image, поле изображения в нём не определено, поэтому поле изображения будет отклонено: 400 invalid input: <root>: additional properties 'input_urls' not allowed. Для редактирования используйте route id image-to-image: gpt-image-2/image-to-image.

Как читать коды ошибок: определить, это «проблема ввода» или «проблема вышестоящего сервиса»

Разделите ответ на два этапа: отправка (непосредственный ответ POST /v1/tasks) и финальное состояние (data.status, полученный опросом GET /v1/tasks/<taskId>):

• HTTP 400 на этапе отправки, плоский конверт {"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: ..."} → проблема в структуре запроса / полях (проблема ввода). Задача ещё не создана, списания нет. Исправьте имя поля или model id.
• HTTP 401 на этапе отправки, вложенный конверт {"error":{"code":"permission_denied","type":"hiapi_error","request_id":"..."}} → это проблема аутентификации (неверный ключ или нет прав), а не проблема ввода.
• HTTP 200 на этапе отправки + taskId, но при опросе data.status: "fail": смотрите data.error.code —
  • INVALID_REQUEST с message "could not be downloaded" → URL изображения недоступен (это по-прежнему ваша проблема ввода: замените изображение на общедоступный URL).
  • TASK_FAILED с message "task failed" → общая ошибка без подсказок. Сначала исключите base64 / некорректный ввод; если после этого всё равно падает, тогда рассматривайте как проблему «вышестоящей генерации».

Одной фразой: 4xx на этапе отправки — это проблема уровня запроса / аутентификации, и только финальный fail может быть связан с загрузкой или вышестоящей генерацией; и в любом случае не дайте внешнему "message":"success" себя обмануть — ориентируйтесь на data.status.

Имя поля ввода изображения зависит от модели

Таблица ниже проверена по текущей input schema каждой модели (обязательно сверяйтесь со страницей модели, поля различаются между семействами):

model id (маршрут image-to-image)	Поле ввода изображения	Тип
gpt-image-2/image-to-image	input_urls	массив строк
seedream-5.0-pro/image-to-image	image_urls	массив строк
nano-banana-pro	image_input	массив строк

Поле должно находиться внутри объекта input; большинство моделей с референсными изображениями требуют передачи массива (даже если изображение одно).

Шаги исправления

1. Разместите изображение на общедоступном HTTP(S) URL. Загрузите его в любое объектное хранилище / CDN (Cloudflare R2, S3, GCS и т. п.) и сделайте объект публичным на чтение, либо используйте действующую предподписанную ссылку.
2. Убедитесь, что доступ возможен без аутентификации. В чистой сессии (или на машине, отличной от вашей) выполните curl -sI "<ваш URL>" — должен вернуться 200 и content-type image/*. Если нужны cookie, заголовок или VPN, сервер не сможет загрузить изображение.
3. Используйте model id image-to-image, а не голый id. Для редактирования вызывайте gpt-image-2/image-to-image (или соответствующий i2i-маршрут вашей модели), а не gpt-image-2.
4. Используйте имя поля из документации модели (input_urls / image_urls / image_input), помещая его в input.
5. Никогда не передавайте base64. Если у вас есть только байты, сначала загрузите их, а затем передайте полученный URL.
6. Сначала отправьте, затем опрашивайте. Выполняйте GET /v1/tasks/<taskId>, пока data.status не станет success или fail. При ошибке читайте data.error.message — "could not be downloaded" означает проблему с URL, а не с вашим prompt.

Минимальный пример проверки

Сначала выполните бесплатную проверку связности: список моделей не создаёт никаких задач и ничего не стоит.

curl -s https://api.hiapi.ai/v1/models \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Возврат 200 с массивом data означает, что ваш ключ работает. Плохой ключ вернёт 401 + {"error":{"code":"permission_denied", ... ,"type":"hiapi_error"}} — это проблема аутентификации, а не ввода. Затем отправьте правильный запрос image-to-image: в поле модели укажите общедоступный URL.

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2/image-to-image",
    "input": {
      "prompt": "把背景换成干净的影棚白",
      "input_urls": ["https://your-public-host.example.com/source.png"]
    }
  }'

Замените input_urls на URL вашего доступного изображения. Успешная отправка вернёт data.taskId; затем опрашивайте GET https://api.hiapi.ai/v1/tasks/<taskId>, пока data.status не станет success, и берите результат из data.output[0].url (этот URL имеет срок действия — скачайте или пересохраните его как можно скорее, не используйте горячую ссылку).

Связанные ссылки

• HiAPI 400 Bad Request: как исправить ошибку параметров — подробно о неверном имени поля или model id и об отклонении на этапе отправки с 400 ещё до запуска задачи.
• Списываются ли деньги за неудачные запросы в HiAPI? — правила оплаты, когда задача падает после приёма.
• Сверка полей: страница модели gpt-image-2 и страница модели Nano Banana Pro.
• Цены API, а также получите API Key в консоли.
• Документация API: создание задачи, получение деталей задачи, аутентификация.

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

Можно ли передавать base64 в модели image-to-image HiAPI? Нет. Полю изображения нужен общедоступный HTTP(S) URL, который сервер сможет скачать. Строка data:image/...;base64,... для некоторых моделей принимается на этапе отправки, но затем задача завершается финальным status: fail с кодом ошибки TASK_FAILED / task failed. Загрузите байты в публичное место и передайте URL.

Мой POST /v1/tasks вернул 200, но задача упала — почему? 200 на этапе отправки означает лишь то, что запрос принят. Загрузка изображения и генерация происходят позже. Опрашивайте GET /v1/tasks/<taskId>; ошибочный ввод изображения проявится там как data.status: fail с error.code INVALID_REQUEST ("The image URL could not be downloaded…") или TASK_FAILED.

В какое именно поле помещать URL изображения? Зависит от модели. gpt-image-2/image-to-image использует input_urls, seedream-5.0-pro/image-to-image использует image_urls, nano-banana-pro использует image_input (все — массивы). Перед отправкой запроса сверьтесь с текущей schema на странице модели.

Подойдёт ли localhost или приватный URL? Нет. HiAPI загружает изображение со своих серверов, поэтому localhost, 127.0.0.1, внутренние адреса, ссылки, доступные только после входа, и просроченные предподписанные URL — всё это падает с "The image URL could not be downloaded." Используйте URL, публично разрешаемый и доступный без аутентификации.

Что означает additional properties 'input_urls' not allowed? Вы передали поле изображения модели, в которой оно не определено — обычно использован голый id text-to-image (gpt-image-2) вместо маршрута image-to-image (gpt-image-2/image-to-image) или имя поля другой модели. Это 400 на этапе отправки; см. руководство по 400 Bad Request выше.

Списываются ли деньги за неудачные задачи с изображениями? Запросы, отклонённые кодом 400 на этапе отправки, не тарифицируются; но задачи, которые были приняты (200 + taskId) и упали позже, могут тарифицироваться — подробнее в разделе «Списываются ли деньги за неудачные запросы?» выше. Поэтому перед повторным запуском сначала исправьте URL.