> ## 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.
# How do I avoid API timeouts?
> Client timeout settings, how slow reasoning models really are, picking the right Base URL node, and 429 concurrency checks — the four keys to avoiding timeouts
## Short Answer
**Three golden rules that cover 90% of timeout problems:**
1. **Set a 360-second timeout for synchronous image endpoints.** Image generation has no async task ID — disconnecting early means you are still billed but get no image.
2. **Give reasoning models enough time.** `gemini-3.1-pro-preview`, `gpt-5.6-sol`, and `gpt-5.5-pro` can take several minutes, whether you stream or not.
3. **Never run long requests through the CDN node.** `api-cf.apiyi.com` sits behind Cloudflare and returns `524` past roughly 100 seconds; it only suits fast text calls.
Separately: if a specific model keeps returning `429` (insufficient concurrency), contact support to review your quota.
## Timeout cheat sheet
| Scenario | Recommended timeout | Recommended node | Notes |
| - | - | - | - |
| Regular text chat (non-reasoning) | 60-120s | Any node | Usually returns in seconds |
| Reasoning models (thinking / reasoning) | **300-600s** | `api.apiyi.com` / `b.apiyi.com` | Slow whether streaming or not |
| Long text output (10k+ words) | **300s or more** | `api.apiyi.com` / `b.apiyi.com` | ❌ Not the CDN node |
| Image generation / editing | **360s baseline** | `api.apiyi.com` / `b.apiyi.com` | ❌ Not the CDN node |
| 4K images, multi-image reference | **600s** | Same as above | See image best practices |
**A timed-out request is still billed**
After your client disconnects, the server and upstream provider **still finish the job**, and the request **is billed as usual**.
In other words: **a timeout set too low means you paid and got nothing**. Set it to a safe upper bound once rather than letting a nearly-successful request get cut off by your own client.
## The four keys in detail
All APIYI image models are **synchronous**: you send the request, hold the connection, and the result comes back in the response body. There is no async task ID and no polling endpoint — disconnect and the result is gone.
**Why defaults hurt you**: mainstream HTTP clients default to 30-60 seconds, while image generation is a genuinely long request:
* GPT-Image-2 at `high` quality with 2K/4K takes 3-5 minutes in practice
* Nano Banana 4K generation starts around 50 seconds and runs longer at peak
* Multi-image reference tasks often exceed 5 minutes
**Recommendation**: when unsure about a model's latency, use **360 seconds** as a baseline; give heavy tasks like 4K and multi-image reference **600 seconds**. Per-model values are in [Image API best practices](/en/api-capabilities/image-api-best-practices).
Occasionally a log shows the image finished in 30 seconds while the client waited 5 minutes — because the log's duration only runs to the point where the gateway finishes processing, while you wait for the body to finish arriving and for the connection's finish signal. **Raising the timeout does not always help**: it does for the slow-download class, but not when the data is already complete and only the finish signal is missing. Measure once following [The log says it finished but my client got nothing](/en/faq/log-duration-vs-client-wait), then decide.
Regular text models return in seconds, which makes it easy to assume text calls never need timeout tuning. **Reasoning models — and any workload that produces tens of thousands of characters in one call — are the exception:**
* `gemini-3.1-pro-preview`
* `gpt-5.6-sol`
* `gpt-5.5-pro` (pricier and slower)
* `claude-opus-5` and other models running deep thinking / high effort
* Long-output tasks: drama scripts, fiction, long translations, large code generation
These calls reason for a long time, then emit a long body token by token, and **ten-plus minutes of total latency is normal**.
**Key point: non-streaming can't hold, but streaming with a sensible read timeout solves it.** Non-streaming buffers the whole generation and sends it at once, so your read timeout has to race the entire generation and any hiccup breaks it. With streaming the first byte arrives within seconds, and after that a data event arrives every few tens of seconds (measured max silent gap during thinking \~42s, with keepalive pings in between), so your read timeout only has to cover the *inter-event gap*, not the total time.
**Recommendation**:
* **Prefer streaming for long output** (`stream=True`), with a read timeout of **90-120 seconds** sized to the inter-event gap — not one huge value covering the whole generation.
* If you insist on non-streaming, set the timeout to **300-600 seconds** and accept the instability; the longer it runs the more likely you disconnect before the result arrives.
* Match your thinking tier (`reasoning_effort` / `thinking`) to the time you have allowed — a higher tier needs more headroom.
For the full long-output recipe (streaming code, max\_tokens, stop\_reason, retries) see [Long-form Output Practices](/en/api-capabilities/long-form-output-practices).
APIYI's `api-cf.apiyi.com` is fronted by the **Cloudflare global CDN**. It offers worldwide acceleration and low latency from overseas, but it has a **request timeout of roughly 100 seconds**, past which you get a `524` error.
⚠️ **This affects more than image endpoints.** Any call that might exceed 100 seconds is a poor fit, including:
* ❌ Image generation / editing
* ❌ Video generation
* ❌ Long text output (long articles, large translations, big code generations)
* ❌ Deep-thinking tasks on reasoning models
✅ **Good fit**: regular chat and short generations that finish within 100 seconds.
**Recommendation**: for long requests use `api.apiyi.com` (or the backup `b.apiyi.com`). Full node comparison in the [Base URL guide](/en/faq/base-url-config).
If timeouts come alongside frequent `429 Too Many Requests`, the problem is usually **concurrency quota**, not your timeout.
Concurrency limits apply **per model**, not across your whole account. A specific model — especially a newly launched or supply-constrained one — may have a lower quota.
**What to do:**
1. Implement exponential backoff so you do not saturate the limit in bursts
2. If 429s persist, **contact APIYI support** — we can check that model's actual quota and help adjust it
See [How much concurrency can I use?](/en/faq/api-concurrency) for the rules.
## Code examples
```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)
```
```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);
```
```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"
}'
```
**Be careful with auto-retry on long requests**: many SDKs retry twice by default. If an image or reasoning task times out and retries, you can end up billed three times with nothing to show. Set `max_retries` to 0 and control retries in your own application logic.
## Still timing out after raising the timeout? Check every hop
Some frameworks wrap another timeout around the HTTP client. Print the effective configuration and confirm the parameter you changed is the one being used.
Any layer with a timeout shorter than the generation time will disconnect before your client does:
* Self-hosted reverse proxy: Nginx `proxy_read_timeout` (60s by default)
* Cloud load balancer: idle connection timeout
* API gateway / CDN: origin timeout
* Serverless functions: execution limit (often 30-60s by default)
* Task queue workers: per-task timeout
**Every hop must be widened** — changing only the client does nothing.
Check whether your Base URL is `api-cf.apiyi.com`. For long requests, switch to `api.apiyi.com` or `b.apiyi.com`.
Rule of thumb: a **`524`** almost always means a Cloudflare-layer timeout, not a slow model.
Read the status code: `524` and dropped connections are timeout problems; `429` is a quota problem. The fixes are entirely different.
Look up the request's real duration and billing in the console [call logs](/en/faq/call-logs), then derive a sensible timeout from it.
## Common questions
No. Once your client disconnects, the server and upstream still complete the job, so the cost is genuinely incurred.
The right approach is to **set the timeout to a safe upper bound in one go**, rather than using a small value and relying on retries — retries only multiply the bill.
Image endpoints currently run in **synchronous pass-through mode**, and we do not store customer business data, so "retrieve by ID after disconnect" is not available.
Recommended pattern: synchronous call + generous timeout + your own task-state table. That is effectively a lightweight async queue. See [Are image endpoints synchronous or asynchronous?](/en/faq/image-async-api)
Video models are natively async and are not affected by this.
**Partly — but do not rely on it.**
Streaming does deliver the first token sooner, which reduces the risk of a total no-response. But a reasoning model may emit nothing during the thinking phase, so the read timeout still fires, and the full output takes just as long overall.
The correct approach is streaming **plus** a generous timeout.
No billing impact — **you are charged for tokens and calls consumed, not for how long you waited**.
The only concern is resource usage on your side: a long connection holds a worker or connection-pool slot. Under high concurrency, run image and reasoning requests through async IO or a dedicated long-task queue.
* **`524`**: a Cloudflare-layer timeout, meaning you used `api-cf.apiyi.com` and the request exceeded roughly 100 seconds. Switch nodes.
* **`429`**: a concurrency or rate limit, unrelated to duration. Add exponential backoff, and contact support if it persists.
## Related Documentation
Per-model timeout table and output format reference
Differences between the four nodes and how to choose
Synchronous mode and client-side task management
Concurrency limits by model type and quota requests
## Contact Us
Scan the QR code or [click to contact support](https://work.weixin.qq.com/kfid/kfc9adfd5810ece25ec)
Timeout troubleshooting and concurrency quota requests
**Support**: [support@apiyi.com](mailto:support@apiyi.com)
**Business**: [business@apiyi.com](mailto:business@apiyi.com)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.