> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Настройки тайм-аута клиента, насколько медленными на самом деле бывают модели с рассуждением, выбор правильного узла Base URL и проверки параллельных запросов 429 — четыре ключа к предотвращению тайм-аутов

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

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

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

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

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

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

<Warning>
  **Запрос с истекшим тайм-аутом все равно тарифицируется**

  После того как ваш клиент отключится, сервер и upstream-провайдер **все равно завершают задачу**, и запрос **тарифицируется как обычно**.

  Иными словами: **если тайм-аут задан слишком низким, вы заплатили и ничего не получили**. Задайте безопасную верхнюю границу один раз, вместо того чтобы позволить почти успешному запросу оборваться из-за вашего клиента.
</Warning>

## Четыре ключа подробно

<AccordionGroup>
  <Accordion title="① Синхронные эндпоинты изображений: установите таймаут на 360 секунд">
    Все модели генерации изображений APIYI — **синхронные**: вы отправляете запрос, удерживаете соединение, и результат возвращается в теле ответа. Здесь нет ID асинхронной задачи и нет эндпоинта опроса — разорвите соединение, и результат исчезнет.

    **Почему значения по умолчанию вредят вам**: распространенные HTTP-клиенты по умолчанию ставят 30-60 секунд, тогда как генерация изображений — действительно долгий запрос:

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

    **Рекомендация**: если не уверены в задержке модели, используйте **360 секунд** как базовое значение; для тяжелых задач, таких как 4K и multi-image reference, давайте **600 секунд**. Значения для конкретных моделей приведены в [Лучшие практики Image API](/ru/api-capabilities/image-api-best-practices).

    <Tip>
      Иногда в журнале видно, что изображение завершилось за 30 секунд, тогда как клиент ждал 5 минут. Это связано с тем, что upstream удерживает хвост ответа, и это находится в пределах нормальной вариативности — при щедром таймауте вы все равно получите изображение.
    </Tip>
  </Accordion>

  <Accordion title="② Модели рассуждения: медленные как со streaming, так и без него">
    Обычные текстовые модели возвращают ответ за секунды, и легко предположить, что текстовым вызовам никогда не нужна настройка таймаута. **Исключение — модели рассуждения:**

    * `gemini-3.1-pro-preview`
    * `gpt-5.6-sol`
    * `gpt-5.5-pro` (дороже и медленнее)
    * Любая модель, работающая с высоким уровнем рассуждения

    Эти модели долго думают внутри, прежде чем выдать ответ, и **несколько минут общей задержки — это нормально**.

    **Ключевой момент: streaming не решает эту проблему.** Многие считают, что `stream=True` означает немедленное поступление данных, но модель рассуждения может не выдавать никаких tokens вообще во время фазы размышления, поэтому ваш таймаут чтения все равно срабатывает — и **общее** время от первого token до последнего по-прежнему велико.

    **Рекомендация**: установите таймаут на **300-600 секунд** для моделей рассуждения и соотнесите свой уровень рассуждения (`reasoning_effort` / `thinking`) со временем, которое вы выделили — более высокий уровень требует большего запаса.
  </Accordion>

  <Accordion title="③ Выбор базового URL: CDN-узел не выдерживает длинные запросы">
    `api-cf.apiyi.com` APIYI обслуживается глобальной CDN Cloudflare. Она обеспечивает ускорение по всему миру и низкую задержку из-за рубежа, но у нее есть таймаут запроса примерно 100 секунд, после чего вы получаете ошибку `524`.

    ⚠️ **Это касается не только image endpoints.** Любой вызов, который может превысить 100 секунд, плохо подходит, включая:

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

    ✅ **Подходит**: обычный чат и короткие генерации, которые завершаются в пределах 100 секунд.

    **Рекомендация**: для длинных запросов используйте `api.apiyi.com` (рекомендуется в материковом Китае) или `vip.apiyi.com` (рекомендуется за рубежом). Полное сравнение узлов — в [Руководстве по базовому URL](/ru/faq/base-url-config).
  </Accordion>

  <Accordion title="④ Превышение лимитов параллельных запросов 429: обратитесь в поддержку">
    Если таймауты сопровождаются частыми `429 Too Many Requests`, проблема обычно в квоте параллельных запросов, а не в вашем таймауте.

    Лимиты параллельных запросов действуют для каждой модели отдельно, а не для всего вашего аккаунта. У конкретной модели — особенно у недавно запущенной или дефицитной — может быть более низкая квота.

    **Что делать:**

    1. Реализуйте exponential backoff, чтобы не забивать лимит всплесками
    2. Если 429 сохраняются, **обратитесь в поддержку APIYI** — мы можем проверить фактическую квоту этой модели и помочь ее скорректировать

    См. [Сколько параллельных запросов я могу использовать?](/ru/faq/api-concurrency) для правил.
  </Accordion>
</AccordionGroup>

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

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    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)
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    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);
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    # --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"
      }'
    ```
  </Tab>
</Tabs>

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

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

<Steps>
  <Step title="Шаг 1: Подтвердите, что тайм-аут SDK действительно применяется">
    Некоторые фреймворки добавляют еще один тайм-аут поверх HTTP-клиента. Выведите фактическую конфигурацию и убедитесь, что используется именно тот параметр, который вы изменили.
  </Step>

  <Step title="Шаг 2: Проверьте каждый участок пути">
    Любой уровень с тайм-аутом, меньшим, чем время генерации, отключит соединение раньше, чем это сделает ваш клиент:

    * Самостоятельно размещенный обратный прокси: Nginx `proxy_read_timeout` (60с по умолчанию)
    * Облачный балансировщик нагрузки: тайм-аут неактивного соединения
    * API gateway / CDN: тайм-аут origin
    * Serverless-функции: лимит выполнения (часто 30-60с по умолчанию)
    * Воркеры очереди задач: тайм-аут для каждой задачи

    **Каждый участок пути должен быть увеличен** — изменение только на стороне клиента ничего не даст.
  </Step>

  <Step title="Шаг 3: Подтвердите, что вы не на узле CDN">
    Проверьте, что ваш базовый URL — `api-cf.apiyi.com`. Для длительных запросов переключитесь на `api.apiyi.com` или `vip.apiyi.com`.

    Как правило, **`524`** почти всегда означает тайм-аут на уровне Cloudflare, а не медленную модель.
  </Step>

  <Step title="Шаг 4: Отличайте тайм-ауты от лимитов параллельных запросов">
    Смотрите на код статуса: `524` и разорванные соединения — это проблемы с тайм-аутом; `429` — это проблема квоты. Способы исправления совершенно разные.
  </Step>

  <Step title="Шаг 5: Проверьте журналы вызовов на фактическую задержку">
    Посмотрите фактическую длительность запроса и тарификацию в консоли [журналы вызовов](/ru/faq/call-logs), затем определите на ее основе разумный тайм-аут.
  </Step>
</Steps>

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

<AccordionGroup>
  <Accordion title="Могу ли я получить возврат средств за запрос, который завершился по таймауту?">
    Нет. Как только ваш клиент отключается, сервер и upstream все равно завершают задачу, поэтому расходы действительно возникают.

    Правильный подход — **сразу установить таймаут с безопасным верхним пределом**, а не использовать маленькое значение и полагаться на повторные попытки — они только увеличивают счет.
  </Accordion>

  <Accordion title="Можете ли вы предложить асинхронный endpoint, чтобы я мог получить результаты по ID после разрыва соединения?">
    Эндпоинты генерации изображений сейчас работают в **режиме синхронной сквозной передачи**, и мы не храним бизнес-данные клиентов, поэтому вариант «получить по ID после разрыва соединения» недоступен.

    Рекомендуемая схема: синхронный вызов + щедрый таймаут + ваша собственная таблица состояний задач. По сути это легковесная асинхронная очередь. См. [Эндпоинты генерации изображений синхронные или асинхронные?](/ru/faq/image-async-api)

    Модели video generation изначально асинхронны и это их не затрагивает.
  </Accordion>

  <Accordion title="Потоковая передача предотвращает таймауты?">
    **Частично — но не полагайтесь на это.**

    Потоковая передача действительно выдает первый token раньше, что снижает риск полного отсутствия ответа. Но модель рассуждения может не выдавать ничего во время фазы рассуждения, поэтому таймаут чтения все равно срабатывает, а полный вывод в целом занимает столько же времени.

    Правильный подход — потоковая передача **плюс** щедрый таймаут.
  </Accordion>

  <Accordion title="Есть ли недостаток в том, чтобы установить очень большой таймаут?">
    На тарификацию это не влияет — **с вас взимается плата за использованные tokens и вызовы, а не за то, сколько вы ждали**.

    Единственный вопрос — это использование ресурсов на вашей стороне: долгое соединение занимает воркер или слот пула соединений. При высокой параллельности пропускайте запросы на генерацию изображений и рассуждение через асинхронный I/O или выделенную очередь для долгих задач.
  </Accordion>

  <Accordion title="В чем разница между 524 и 429?">
    * **`524`**: таймаут на уровне Cloudflare, то есть вы использовали `api-cf.apiyi.com`, и запрос превысил примерно 100 секунд. Переключитесь на другие узлы.
    * **`429`**: лимит параллельных запросов или rate limit, не связанный с длительностью. Добавьте экспоненциальную задержку между повторами и обратитесь в поддержку, если это сохраняется.
  </Accordion>
</AccordionGroup>

## Related Documentation

<CardGroup cols={2}>
  <Card title="Лучшие практики Image API" icon="image" href="/ru/api-capabilities/image-api-best-practices">
    Таблица таймаутов по моделям и справка по формату вывода
  </Card>

  <Card title="Как задать базовый URL?" icon="link" href="/ru/faq/base-url-config">
    Различия между четырьмя узлами и как выбрать подходящий
  </Card>

  <Card title="Эндпоинты для изображений синхронные или асинхронные?" icon="refresh-cw" href="/ru/faq/image-async-api">
    Синхронный режим и управление задачами на стороне клиента
  </Card>

  <Card title="Сколько параллельных запросов я могу использовать?" icon="gauge" href="/ru/faq/api-concurrency">
    Ограничения параллельных запросов по типу модели и запросам на квоту
  </Card>
</CardGroup>

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

<CardGroup cols={2}>
  <Card title="Поддержка WeCom" icon="message-circle" href="https://work.weixin.qq.com/kfid/kfc9adfd5810ece25ec">
    <img src="https://mintcdn.com/apiyillc/fpi567ydpk7adDt0/images/wecom-qrcode.png?fit=max&auto=format&n=fpi567ydpk7adDt0&q=85&s=7286b96e94110e3a48798b649df1b45b" alt="QR-код поддержки WeCom" style={{maxWidth: "180px"}} width="400" height="400" data-path="images/wecom-qrcode.png" />

    Сканируйте QR-код или [нажмите, чтобы связаться с поддержкой](https://work.weixin.qq.com/kfid/kfc9adfd5810ece25ec)

    Вопросы по устранению таймаутов и запросам квоты на параллельные запросы
  </Card>

  <Card title="Электронная почта" icon="mail">
    **Поддержка**: [support@apiyi.com](mailto:support@apiyi.com)

    **Коммерческий отдел**: [business@apiyi.com](mailto:business@apiyi.com)
  </Card>
</CardGroup>