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

# API 请求超时怎么办？timeout 该设多少

> 老张API请求超时多半是客户端或中间层等待时间短于生成时间。本页给出文本、推理模型、图片生成的建议 timeout，说明断开后为什么仍会扣费，以及怎样逐层排查。

请求超时多半是你的客户端或中间代理等得太短，而模型还在生成。客户端断开不会取消已经发给上游的请求，生成完成后照常扣费，所以要一次把 timeout 设够，而不是设一个小值再靠重试。

<Warning>
  **超时后立即重试，可能付两次钱却一个结果都拿不到。**

  * 断开前发出的那次请求通常仍会完成并扣费。
  * SDK 自带的自动重试会在超时后再发一次同样的请求。
  * 重试前先在[调用日志](https://api.laozhang.ai/log)查看上一次请求的状态和扣费。
</Warning>

## 按场景设置 timeout

| 调用场景 | 建议 timeout | 说明 |
| - | - | - |
| 普通文本对话 | 60–120 秒 | 通常几秒内返回 |
| 推理模型、长文本输出 | 用流式；非流式 300–600 秒 | 思考档位越高越慢 |
| 图片生成与编辑 | 360 秒 | 图片接口是同步的，断开就拿不到结果 |
| 4K 出图、多张参考图 | 600 秒 | 高峰期更慢 |
| 视频生成 | 按任务轮询 | 提交和查询都很快返回，见各视频模型页 |

推理模型会先长时间思考再输出，一次请求可能持续几分钟，例如：

* `gpt-6-sol`、`gpt-5.6-sol`
* `gpt-5.5-pro`、`o3-pro`
* `gemini-3.1-pro-preview`

## 长输出优先用流式

非流式请求要等整段内容生成完才一次性返回，你的读超时要和整段生成时间竞速。改用流式（`stream=True`）后，内容边生成边返回：

* 首个数据很快到达，之后持续有事件返回；
* 读超时只需覆盖两次事件之间的间隔，通常设 90–120 秒；
* 总耗时不会变短，但不再因为等整段结果而断开。

坚持用非流式时，把 timeout 设到 300–600 秒，并接受生成越久越容易中途断开。

## 关掉长请求的自动重试

OpenAI 官方 Python SDK 默认在超时等错误后自动重试 2 次。图片和推理请求建议把 `max_retries` 设为 0，由业务代码决定是否重试：

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    import os
    from openai import OpenAI

    client = OpenAI(
        api_key=os.environ["LAOZHANG_API_KEY"],
        base_url="https://api.laozhang.ai/v1",
        max_retries=0,  # 长请求不自动重试，避免重复扣费
    )

    response = client.chat.completions.create(
        model="gpt-6-sol",
        messages=[{"role": "user", "content": "分析这段代码的时间复杂度"}],
        timeout=600,  # 推理模型留足时间
    )
    print(response.choices[0].message.content)
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    import OpenAI from "openai";

    const client = new OpenAI({
      apiKey: process.env.LAOZHANG_API_KEY,
      baseURL: "https://api.laozhang.ai/v1",
      timeout: 600 * 1000, // 毫秒
      maxRetries: 0,
    });

    const response = await client.chat.completions.create({
      model: "gpt-6-sol",
      messages: [{ role: "user", content: "写一篇 5000 字的技术分析" }],
    });
    console.log(response.choices[0].message.content);
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    # --max-time 是整个请求的最长秒数
    curl https://api.laozhang.ai/v1/images/generations \
      -H "Authorization: Bearer $LAOZHANG_API_KEY" \
      -H "Content-Type: application/json" \
      --max-time 360 \
      -d '{"model": "gpt-image-2.5-flare-vip", "prompt": "日出时宁静的山间湖泊"}'
    ```
  </Tab>
</Tabs>

## 已经调大 timeout 仍然超时

按顺序检查：

<Steps>
  <Step title="确认新的 timeout 真的生效">
    有些框架在 HTTP 客户端外面还包了一层超时。打印实际生效的配置，确认改的是被使用的那个参数。
  </Step>

  <Step title="检查链路上的每一层">
    任何一层的超时短于生成时间，都会先断开连接。逐一放宽：

    * 自建反向代理，例如 Nginx 的 `proxy_read_timeout` 默认 60 秒；
    * 云负载均衡的空闲连接超时；
    * Serverless 函数的最长执行时间；
    * 任务队列 worker 的单任务超时。
  </Step>

  <Step title="区分超时和限流">
    连接中断、读取超时是等待时间不够；`429` 是速率或容量限制，与耗时无关。`429` 先做有限次数的退避重试，长期出现时联系支持团队。
  </Step>

  <Step title="用调用日志确认实际耗时">
    在[调用日志](https://api.laozhang.ai/log)查看这次请求的用时和是否扣费，按实际耗时再留出余量。
  </Step>
</Steps>

## 常见问题

### 超时断开的请求还会扣费吗？

会，只要上游已经完成生成。断开发生在你的客户端，服务端和上游不会因此停止；返回 `429` 或 `503`、没有进入生成的请求通常不扣费。实际扣费以调用日志为准，退款与余额调整按[用户协议](https://www.laozhang.ai/zh-cn/terms)处理。

### 断开后能凭 ID 取回图片吗？

不能。图片接口是同步的，老张API默认不保存生成结果，断开后这次结果就拿不到了。需要异步体验时，在自己的后端包一层任务队列，做法见[图片生成 API 有异步任务 ID 吗](/faq/image-api-sync)。

### timeout 设得很大有副作用吗？

不影响计费，扣费只看实际用量或调用次数，与等待时间无关。需要注意的是长连接会占用 worker 或连接池，高并发时建议把图片和推理请求放进独立的任务队列。

## 相关文档

* [图片生成 API 有异步任务 ID 吗](/faq/image-api-sync)
* [老张API开发文档：处理调用错误](/api-manual)
* [如何查看和使用调用日志](/faq/call-logs)
* [文本生成 API：三种协议的流式读取](/api-capabilities/text-generation)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.