Как избежать тайм-аутов API?

Краткий ответ

Три золотых правила, которые закрывают 90% проблем с таймаутом:

Установите таймаут 360 секунд для синхронных эндпоинтов генерации изображений. У генерации изображений нет async task ID — если разорвать соединение раньше, с вас все равно будет списана тарификация, но изображение вы не получите.
Дайте reasoning-моделям достаточно времени. gemini-3.1-pro-preview, gpt-5.6-sol и gpt-5.5-pro могут выполняться несколько минут, независимо от того, используете вы потоковую передачу или нет.
Никогда не пропускайте длительные запросы через узел CDN. api-cf.apiyi.com находится за Cloudflare и возвращает 524 примерно после 100 секунд; он подходит только для быстрых текстовых вызовов.

Отдельно: если конкретная модель продолжает возвращать 429 (недостаточно параллельных запросов), обратитесь в поддержку, чтобы проверить вашу квоту.

Шпаргалка по таймаутам

Сценарий	Рекомендуемый таймаут	Рекомендуемый узел	Примечания
Обычный текстовый чат (без рассуждений)	60–120 с	Любой узел	Обычно ответ возвращается за несколько секунд
Модели с рассуждением (thinking / reasoning)	300–600 с	`api.apiyi.com` / `b.apiyi.com`	Медленно как с потоковой передачей, так и без неё
Длинный текстовый вывод (10k+ слов)	300 с или более	`api.apiyi.com` / `b.apiyi.com`	❌ Не узел CDN
Генерация изображений / редактирование	Базовые 360 с	`api.apiyi.com` / `b.apiyi.com`	❌ Не узел CDN
Изображения 4K, несколько референсных изображений	600 с	Как указано выше	См. рекомендации по работе с изображениями

Запрос, завершившийся по таймауту, всё равно тарифицируетсяПосле отключения вашего клиента сервер и вышестоящий провайдер всё равно завершают работу, а запрос тарифицируется в обычном режиме.Иными словами: слишком малый таймаут означает, что вы заплатили, но ничего не получили. Установите безопасный верхний предел один раз, чтобы ваш собственный клиент не обрывал почти завершившийся запрос.

Подробный разбор четырёх ключевых аспектов

① Синхронные эндпоинты генерации изображений: установите таймаут на 360 секунд

Все модели изображений в APIYI являются синхронными: вы отправляете запрос, удерживаете соединение, а результат возвращается в теле ответа. Здесь нет идентификатора асинхронной задачи и эндпоинта для опроса (polling) — при разрыве соединения результат теряется.Почему настройки по умолчанию вам вредят: в стандартных HTTP-клиентах таймаут по умолчанию составляет 30–60 секунд, тогда как генерация изображений — это по-настоящему длительный запрос:

GPT-Image-2 с качеством high в разрешении 2K/4K на практике занимает 3–5 минут
Генерация Nano Banana 4K начинается примерно от 50 секунд и длится дольше в периоды пиковой нагрузки
Задачи с несколькими референсными изображениями часто длятся более 5 минут

Рекомендация: если вы не уверены во времени ответа модели, используйте 360 секунд в качестве базового значения; для тяжёлых задач, таких как 4K и несколько референсных изображений, выделяйте 600 секунд. Значения для конкретных моделей приведены в разделе Рекомендации по работе с Image API.

Иногда лог показывает, что генерация изображения завершилась за 30 секунд, тогда как клиент ждал 5 минут — это происходит потому, что длительность в логе фиксирует лишь момент завершения обработки шлюзом, в то время как вы ожидаете полной доставки тела ответа и сигнала о завершении соединения. Увеличение таймаута помогает не всегда: оно эффективно в случае медленной загрузки, но бессильно, если данные уже переданы целиком и отсутствует лишь сигнал завершения. Выполните проверку по инструкции В логе указано, что запрос завершён, но клиент ничего не получил, и только затем принимайте решение.

② Модели рассуждения и длинного вывода: обычный режим не выдерживает, используйте потоковую передачу

Стандартные текстовые модели отвечают за секунды, из-за чего легко предположить, что текстовые вызовы никогда не требуют настройки таймаута. Модели рассуждения — и любые сценарии, генерирующие десятки тысяч символов за один запрос — являются исключением:

gemini-3.1-pro-preview
gpt-5.6-sol
gpt-5.5-pro (дороже и медленнее)
claude-opus-5 и другие модели с глубоким рассуждением (deep thinking) / высоким уровнем effort
Задачи с длинным выводом: сценарии для фильмов/сериалов, художественные тексты, объёмные переводы, генерация большого количества кода

Такие запросы долго рассуждают, а затем последовательно токен за токеном выводят объёмный текст, поэтому общее время ожидания свыше десяти минут является нормальным.Главное: обычный режим без потоковой передачи не справится, но потоковая передача с разумным таймаутом чтения решает эту проблему. Без потоковой передачи буферизуется весь сгенерированный объём и передаётся единым пакетом, поэтому таймаут чтения должен выдерживать всю генерацию целиком, и любая заминка приводит к сбою. При потоковой передаче первый байт приходит в течение нескольких секунд, а затем каждые несколько десятков секунд поступает событие данных (максимальный замеренный интервал тишины во время рассуждения составляет около 42 с, с периодическими keepalive-пингами между ними), поэтому таймаут чтения должен покрывать только интервал между событиями, а не общее время выполнения.Рекомендация:

Отдавайте предпочтение потоковой передаче для длинного вывода (stream=True) с таймаутом чтения 90–120 секунд, рассчитанным на интервал между событиями, а не задавайте одно гигантское значение на всю генерацию.
Если вам непременно нужен режим без потоковой передачи, установите таймаут на 300–600 секунд и будьте готовы к нестабильности: чем дольше длится выполнение, тем выше вероятность разрыва соединения до получения результата.
Сопоставляйте выбранный уровень рассуждения (reasoning_effort / thinking) с выделенным временем: более высокий уровень требует большего запаса времени.

Полное руководство по работе с длинным выводом (код для потоковой передачи, max_tokens, stop_reason, повторные попытки) приведено в разделе Практика работы с длинным выводом.

③ Выбор Base URL: CDN-узел не подходит для длительных запросов

Эндпоинт api-cf.apiyi.com сервиса APIYI работает через глобальную CDN Cloudflare. Она обеспечивает ускорение по всему миру и низкие задержки из-за рубежа, однако имеет таймаут запроса около 100 секунд, по истечении которого вы получите ошибку 524.⚠️ Это касается не только эндпоинтов генерации изображений. Любой запрос, длительность которого может превысить 100 секунд, плохо подходит для этого узла, включая:

❌ Генерация / редактирование изображений
❌ Генерация видео
❌ Длинный вывод текста (объёмные статьи, крупные переводы, генерация больших фрагментов кода)
❌ Задачи глубокого рассуждения на reasoning-моделях

✅ Для чего подходит: стандартный чат и короткие генерации, укладывающиеся в 100 секунд.Рекомендация: для длительных запросов используйте api.apiyi.com (или резервный b.apiyi.com). Полное сравнение узлов доступно в руководстве по Base URL.

④ Превышение лимита параллельных запросов (429): обратитесь в службу поддержки

Если таймауты сопровождаются частыми ошибками 429 Too Many Requests, проблема, как правило, заключается в квоте на параллельные запросы, а не в самом значении таймаута.Лимиты параллельных запросов действуют для каждой модели отдельно, а не на весь аккаунт целиком. Конкретная модель — особенно недавно запущенная или имеющая ограниченные вычислительные ресурсы — может иметь более низкую квоту.Что делать:

Настройте экспоненциальную задержку (exponential backoff), чтобы всплески запросов не перегружали лимит
Если ошибки 429 сохраняются, обратитесь в службу поддержки APIYI — мы сможем проверить фактическую квоту для данной модели и помочь с её увеличением

Правила и подробности описаны в разделе Какой объём параллельных запросов мне доступен?.

Примеры кода

Python
Node.js
cURL

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1",  # not the api-cf node for long requests
)

# Tier your timeouts by scenario (seconds) instead of one global value
TIMEOUTS = {
    "text":      120,   # regular text
    "reasoning": 600,   # reasoning models
    "image":     360,   # image generation baseline
    "image_4k":  600,   # 4K / multi-image reference
}

resp = client.chat.completions.create(
    model="gpt-5.6-sol",
    messages=[{"role": "user", "content": "Analyze the complexity of this code"}],
    timeout=TIMEOUTS["reasoning"],   # 600s for reasoning models
)
print(resp.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.APIYI_API_KEY,
  baseURL: "https://api.apiyi.com/v1",
  timeout: 600 * 1000,   // milliseconds — 600s for reasoning models
  maxRetries: 0,         // avoid auto-retry on long requests: it double-bills
});

const resp = await client.chat.completions.create({
  model: "gemini-3.1-pro-preview",
  messages: [{ role: "user", content: "Write an 8000-word technical analysis" }],
});
console.log(resp.choices[0].message.content);

# --max-time caps the total request duration in seconds
curl https://api.apiyi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 360 \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a serene mountain lake at sunrise",
    "size": "2048x2048"
  }'

Будьте осторожны с автоповтором при длинных запросах: многие SDK по умолчанию повторяют попытку дважды. Если задача на генерацию изображений или рассуждение завершится по тайм-ауту и выполнит повтор, с вас могут списать оплату три раза, а результата не будет. Установите max_retries в 0 и управляйте повторами в логике своего приложения.

По-прежнему истекает таймаут после его увеличения? Проверьте каждый узел

Шаг 1: Убедитесь, что таймаут SDK действительно применяется

Некоторые фреймворки оборачивают HTTP-клиент в дополнительный таймаут. Выведите действующую конфигурацию и убедитесь, что используется именно измененный вами параметр.

Шаг 2: Проверьте каждый узел на пути следования запроса

Любой уровень с таймаутом короче времени генерации разорвет соединение раньше вашего клиента:

Собственный reverse proxy: Nginx proxy_read_timeout (по умолчанию 60 с)
Облачный балансировщик нагрузки: таймаут неактивного соединения (idle connection timeout)
API-шлюз / CDN: таймаут источника (origin timeout)
Бессерверные функции: лимит времени выполнения (часто 30–60 с по умолчанию)
Воркеры очередей задач: таймаут на уровне отдельной задачи

Таймаут необходимо увеличить на каждом узле — изменение только на стороне клиента ничего не даст.

Шаг 3: Убедитесь, что вы не используете узел CDN

Проверьте, не является ли ваш Base URL api-cf.apiyi.com. Для длительных запросов переключитесь на api.apiyi.com или b.apiyi.com.Практическое правило: 524 почти всегда указывает на таймаут на уровне Cloudflare, а не на медленную работу модели.

Шаг 4: Отличайте таймауты от лимитов параллельных запросов

Обратите внимание на код состояния: 524 и разорванные соединения указывают на проблемы с таймаутом; 429 — это проблема с квотой. Способы решения в этих случаях совершенно разные.

Шаг 5: Проверьте фактическую задержку в журналах вызовов

Посмотрите реальную длительность запроса и тарификацию в консоли в журналах вызовов, а затем задайте на их основе разумный таймаут.

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

Мой таймаут для изображений составляет 200 секунд, и обычно этого достаточно. Почему иногда все равно возникает таймаут?

Большинство изображений генерируются за несколько десятков секунд, поэтому 200 секунд кажутся достаточными с запасом. Однако в часы пик провайдеры ставят запросы в очередь, и отдельная генерация может иногда затягиваться на несколько минут. В таких случаях шлюз автоматически повторяет попытку по другому маршруту в фоновом режиме, пока ваш клиент все еще ожидает.Если ваш таймаут слишком мал, соединение с вашей стороны разрывается до того, как шлюз успеет переключить маршрут, и запрос просто завершается ошибкой. Поэтому для изображений устанавливайте таймаут 360 секунд или 600 секунд для 4K либо нескольких референсных изображений (см. таблицу выше), чтобы оставался запас времени для автоматического переключения.Кроме того, чем больше референсные изображения, тем медленнее идет обработка: при запросе на редактирование с телом 8–10 МБ часть времени уходит только на загрузку, и провайдеру требуется больше времени на его обработку. Если ваш сценарий использования позволяет, сжимайте референсные изображения до 2048 пикселей по длинной стороне и менее 2 МБ каждое. Это работает ощутимо быстрее и практически не влияет на качество; см. раздел Сжатие изображений и разрешение.

Можно ли вернуть средства за запрос, завершившийся по таймауту?

Нет. Как только ваш клиент разрывает соединение, сервер и вышестоящий провайдер все равно завершают выполнение задачи, поэтому расходы фактически списываются.Правильный подход — сразу задать таймаут с безопасным верхним пределом, а не использовать небольшое значение и полагаться на повторные попытки (retries): повторы лишь увеличивают счет.

Предоставляете ли вы асинхронный эндпоинт, чтобы можно было получить результаты по ID после разрыва соединения?

Эндпоинты для изображений в настоящее время работают в режиме сквозной синхронной передачи, и мы не храним бизнес-данные клиентов, поэтому функция «получение по ID после отключения» недоступна.Рекомендуемый шаблон: синхронный вызов + увеличенный таймаут + собственная таблица состояний задач. Фактически это представляет собой легковесную асинхронную очередь. См. раздел Являются ли эндпоинты изображений синхронными или асинхронными?Модели для видео изначально являются асинхронными, и это ограничение на них не распространяется.

Предотвращает ли потоковая передача таймауты?

Частично, но полагаться на это не стоит.Потоковая передача действительно доставляет первый token быстрее, что снижает риск полного отсутствия ответа. Однако модель с рассуждением (reasoning) может ничего не выдавать на этапе размышления, из-за чего таймаут чтения все равно сработает, а генерация полного ответа в целом займет столько же времени.Правильный подход — потоковая передача в сочетании с увеличенным таймаутом.

Есть ли недостатки у установки очень большого таймаута?

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

В чем разница между 524 и 429?

524: таймаут на уровне Cloudflare, означающий, что использовался узел api-cf.apiyi.com и длительность запроса превысила примерно 100 секунд. Переключите ноду.
429: лимит параллельных запросов или лимит запросов, не связанный с длительностью. Настройте экспоненциальную задержку (exponential backoff), а если проблема сохраняется, обратитесь в службу поддержки.

Лучшие практики Image API

Таблица таймаутов по моделям и справка по формату вывода

Как задать базовый URL?

Различия между четырьмя узлами и как выбрать подходящий

Эндпоинты для изображений синхронные или асинхронные?

Синхронный режим и управление задачами на стороне клиента

Сколько параллельных запросов я могу использовать?

Ограничения параллельных запросов по типу модели и запросам на квоту

Свяжитесь с нами

Поддержка WeCom

Сканируйте QR-код или нажмите, чтобы связаться с поддержкойВопросы по устранению таймаутов и запросам квоты на параллельные запросы

Электронная почта

Поддержка: [email protected]Коммерческий отдел: [email protected]

Обзор

Возможности сайта

Tokens и журналы

Корпоративные услуги

Оплата и безопасность

Сеть и подключение

Аккаунт и вход

Как избежать тайм-аутов API?

Краткий ответ

Шпаргалка по таймаутам

Подробный разбор четырёх ключевых аспектов

Примеры кода

По-прежнему истекает таймаут после его увеличения? Проверьте каждый узел

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

Лучшие практики Image API

Как задать базовый URL?

Эндпоинты для изображений синхронные или асинхронные?

Сколько параллельных запросов я могу использовать?

Свяжитесь с нами

Поддержка WeCom

Электронная почта

​Краткий ответ

​Шпаргалка по таймаутам

​Подробный разбор четырёх ключевых аспектов

​Примеры кода

​По-прежнему истекает таймаут после его увеличения? Проверьте каждый узел

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

​Related Documentation

Лучшие практики Image API

Как задать базовый URL?

Эндпоинты для изображений синхронные или асинхронные?

Сколько параллельных запросов я могу использовать?

​Свяжитесь с нами

Поддержка WeCom

Электронная почта

Краткий ответ

Шпаргалка по таймаутам

Подробный разбор четырёх ключевых аспектов

Примеры кода

По-прежнему истекает таймаут после его увеличения? Проверьте каждый узел

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

Related Documentation

Свяжитесь с нами