hiapi /v1/tasks: задача зависла или истекла по времени — диагностика и стратегия повторов

Вы отправили задачу через POST https://api.hiapi.ai/v1/tasks, получили taskId, но когда запрашиваете GET /v1/tasks/{taskId}, data.status уже несколько минут остаётся queued или handling — выглядит так, будто задача «зависла»; либо ваш цикл опроса дошёл до заданного вами предела, так и не дождавшись терминального состояния, и вы получили таймаут. Не спешите сразу переотправлять: задачи hiapi асинхронные, и «ещё не закончилась» и «уже провалилась» — разные вещи. Сначала разберитесь в диагнозе, иначе можно сделать только хуже.

Если вы видите, что data.status уже равен fail, error.code — TASK_TIMEOUT, или браузер/прокси выдаёт буквальный HTTP 504, — это другая проблема (задача действительно провалилась, или таймаут произошёл на сетевом уровне между вами и hiapi). Смотрите Диагностика таймаутов задач и ошибок 504 в HiAPI. В этой статье речь только о сценариях «застревания», когда задача долго не достигает терминального состояния.

Симптомы

«Зависшая» задача при запросе выглядит примерно так (HTTP 200, но задача всё ещё в нетерминальном состоянии):

{
  "data": {
    "taskId": "…",
    "status": "queued",
    "output": null,
    "error": null
  }
}

Ключевые признаки: data.status — одно из queued (в очереди) / handling (в обработке) / archiving (в архивации), data.error равно null, а data.output пока пуст. Это означает, что задача здорова, просто ещё не завершилась.

У задачи hiapi есть только два терминальных состояния: data.status равен success или fail. Пока он не равен ни одному из них, задача не завершена — «зависания» почти всегда происходят именно в этом нетерминальном диапазоне.

Два легко путаемых «ложных зависания»:

• Запрос сразу возвращает 404:

  {"code": 404, "data": null, "message": "task not found"}
  

  Это не зависание, а опечатка в taskId, задача вообще не была создана, или запись о задаче уже истекла — сверьтесь с data.taskId, полученным при отправке.

• Отказ при отправке (вы вообще не получили taskId), например из-за опечатки в model:

  {"code": 400, "data": null, "error_code": "MODEL_UNAVAILABLE", "message": "model not available via /v1/tasks"}
  

  Это проблема самого запроса, а не зависание задачи — исправьте и отправьте заново.

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

1. Накопление очереди (самая частая)

Когда какую-то модель (графическую, видеомодель или любую ресурсоёмкую) вызывают массово, ваша задача ждёт в очереди этой модели, пока её не подхватит worker.

• Признак: data.status равен queued, data.error равно null, с момента отправки прошло немного времени.
• Решение: замедлите опрос — достаточно проверять раз в 5–10 секунд, не крутитесь на 100ms. Большинство задач подхватываются в течение одной-двух минут.

2. Тяжёлая модель сама по себе долгая

Задача уже подхвачена (handling/archiving), но эта модель в принципе работает медленно — длинное видео, высокое разрешение, множество референсных изображений заметно увеличивают время выполнения.

• Признак: data.status равен handling или archiving в течение нескольких минут без ошибок.
• Решение: задайте более щедрый лимит опроса для тяжёлых задач (с запасом под возможности модели). Долго ≠ провал, не обрывайте её, когда она вот-вот выдаст результат.

3. Неправильный подход к опросу (чаще всего принимают за «зависание»)

Многие «зависания» на самом деле — проблема клиента: слишком частый опрос сбивает вас с толку, отсутствует лимит, или лимит слишком мал и вы сдаётесь слишком рано.

• Признак: на сервере data.status нормально продвигается, но ваш цикл преждевременно выбрасывает таймаут, или вы вовсе не читаете data.status.
• Решение: фиксированный интервал (рекомендуется 5 секунд) + разумный лимит (около 10 минут для обычных задач, дольше для тяжёлых). Таймаут должен определять ваш цикл, а не серверный статус timeout — в hiapi такого статуса нет.

4. Недоступность callback-эндпоинта

Если при отправке задачи вы указали callback, сама задача может уже быть success, просто результат не доходит до вас, и кажется, что «ничего не происходит».

• Признак: при активном запросе data.status уже success, data.output заполнен, но ваш callback-эндпоинт ничего не получил.
• Решение: адрес callback должен быть доступен из интернета, принимать POST и возвращать 2xx примерно в течение 10 секунд; иначе переходите на опрос. Подробности см. в Почему не срабатывает callback задачи hiapi.

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

1. Сначала проверьте статус, не переотправляйте наугад: GET /v1/tasks/{taskId}, читайте data.status и data.error.
2. Разделяйте по статусу:
   • queued / handling / archiving → ещё выполняется, подождите 5–10 секунд и проверьте снова (причины 1 / 2).
   • success → задача успешна, забирайте результат из data.output; если вы ждали callback и не получили его → причина 4.
   • fail → читайте data.error.code и data.error.message; если это TASK_TIMEOUT → смотрите руководство по таймаутам и 504.
   • 404 task not found → неверный taskId или задача не создана, сверьтесь с data.taskId в ответе на отправку.
3. output имеет срок годности: URL для скачивания в data.output содержит expireAt (около 7 дней), сразу сохраните на диск / переложите в хранилище, не храните горячую ссылку надолго.
4. Убедитесь, что это не проблема аутентификации / запроса: сначала выполните минимальный проверочный пример ниже, чтобы исключить проблемы с key и model id.
5. Если действительно нужен повтор — используйте backoff: см. следующую секцию стратегии повторов, не переотправляйте одно и то же body в тесном цикле.

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

Минимальным запросом проверьте, что key и сам интерфейс задач работают. model указывайте как голый id (например, gpt-image-2):

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",
    "input": { "prompt": "a single red apple on a white background, studio lighting" }
  }'

При успешной отправке вы получите ответ вида {"data":{"taskId":"…","status":"queued"}}. Используйте taskId для опроса:

curl -s "https://api.hiapi.ai/v1/tasks/<taskId>" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

• Если возвращается 401, а body — {"error":{"code":"permission_denied","type":"hiapi_error","request_id":"…"}} — проблема в key, а не в задаче. Смотрите Диагностика ошибки недействительного API Key.
• Если отправка отклонена с 400 + "error_code":"MODEL_UNAVAILABLE" — проблема в model id. Передайте голый id и сверьтесь с ошибка hiapi «модель недоступна».

Стратегия повторов, которая не сделает хуже

1. Экспоненциальный backoff: рекомендуется 5s → 15s → 45s.
2. Максимум 3 попытки: если третья тоже не удалась, эскалируйте (смените модель, понизьте конфигурацию или откройте тикет), не зацикливайтесь бесконечно.
3. Каждый повтор — новая задача: один POST /v1/tasks — это новый taskId и возможная новая тарификация. У hiapi нет публично обещанной «идемпотентной переотправки» — не рассчитывайте, что повтор того же body переиспользует старую задачу.
4. При 429 замедляйте скорость отправки, а не опроса: см. Как исправить ошибку лимита запросов (429) hiapi.

Надёжный пример опроса + backoff на Python:

import time, os, requests

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

def submit_and_wait(body, poll_interval=5, max_wait=600):
    r = requests.post(BASE, json=body, headers=HEADERS, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    deadline = time.time() + max_wait
    while time.time() < deadline:
        time.sleep(poll_interval)
        data = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()
        status = (data.get("data") or {}).get("status")
        if status == "success":
            return data["data"]["output"]
        if status == "fail":
            raise RuntimeError(data["data"].get("error"))
        # queued / handling / archiving → 继续等
    raise TimeoutError(f"task {task_id} 在 {max_wait}s 内未到终态")

Обратите внимание: терминальными считаются только success и fail; остальные статусы (queued / handling / archiving) — продолжайте ждать, а таймаут определяется вашим max_wait.

Когда пора эскалировать

• Повторили с backoff 3 раза, и каждый раз один и тот же data.error.code → это не временный сбой, меняйте входные данные или модель.
• Задача долго стоит в queued без продвижения → зайдите в консоль hiapi, check объявления платформы, и откройте тикет с request_id.
• data.status уже success, но callback так и не приходит → не полагайтесь на callback для этого эндпоинта, переходите на опрос.

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

• Диагностика таймаутов задач и ошибок 504 в HiAPI — когда задача действительно fail с TASK_TIMEOUT или вы видите буквальный 504.
• Почему не срабатывает callback задачи hiapi — отдельная статья о «ложном зависании» из-за отсутствия callback.
• Диагностика ошибки недействительного API Key｜Ошибка «модель недоступна»｜Ошибка лимита запросов 429

FAQ

Вопрос: сколько времени считается «таймаутом»? Есть ли единая длительность таймаута? Ответ: единого числа нет, всё зависит от модели; тяжёлые задачи (длинное видео, высокое разрешение) дольше. К тому же у hiapi нет серверного статуса timeout — так называемый таймаут обычно означает, что ваш цикл опроса достиг заданного вами предела. Задачи, которые действительно провалились по таймауту на сервере, будут иметь data.status:"fail" + error.code:"TASK_TIMEOUT" — такой случай смотрите в руководстве по таймаутам и 504.

Вопрос: задача в queued уже 30 секунд, отменять и повторять? Ответ: нет. 30 секунд — нормальный диапазон для любой нетривиальной модели, подождите хотя бы две минуты, прежде чем думать о повторе.

Вопрос: можно ли отменить выполняющуюся задачу? Ответ: как правило, отмена не поддерживается; даже если бы поддерживалась, очередь / вычислительный слот обычно уже заняты. Выгоднее дать ей завершиться и проверить результат.

Вопрос: тот же запрос вчера работал, а сегодня зависает? Ответ: в подавляющем большинстве случаев это накопление очереди на уровне модели (причина 1). Попробуйте модель со схожими возможностями или подождите 5–10 минут, пока очередь спадёт.

Вопрос: каждая задача уходит в таймаут — это проблема моего аккаунта? Ответ: сначала зайдите в консоль hiapi, проверьте объявления уровня аккаунта, затем убедитесь, не ограничен ли ваш лимит запросов (см. руководство по 429). Если всё в норме и проваливается только одна конкретная модель, скорее всего, это очередь или бэкенд той модели, а не ваш аккаунт.

Вопрос: будет ли двойная тарификация при повторе зависшей / просроченной задачи? Ответ: каждый POST /v1/tasks — новая тарифицируемая задача. Проваленная задача без результата обычно не тарифицируется за выработку, но очередь / вычислительный слот могли быть заняты. Если важна стоимость, сверьтесь постфактум на странице использования.