How do I avoid API timeouts?

Short Answer

Three golden rules that cover 90% of timeout problems:

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.
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.
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` / `vip.apiyi.com`	Slow whether streaming or not
Long text output (10k+ words)	300s or more	`api.apiyi.com` / `vip.apiyi.com`	❌ Not the CDN node
Image generation / editing	360s baseline	`api.apiyi.com` / `vip.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 billedAfter 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

① Synchronous image endpoints: set the timeout to 360 seconds

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.

Occasionally a log shows the image finished in 30 seconds while the client waited 5 minutes. That comes from upstream withholding the tail of the response and is within normal variance — with a generous timeout you still get the image.

② Reasoning models: slow with and without streaming

Regular text models return in seconds, which makes it easy to assume text calls never need timeout tuning. Reasoning models are the exception:

gemini-3.1-pro-preview
gpt-5.6-sol
gpt-5.5-pro (pricier and slower)
Any model running at a high thinking budget (high reasoning effort)

These models think internally for a long time before producing an answer, and several minutes of total latency is normal.Key point: streaming does not solve this. Many people assume stream=True means data arrives immediately, but a reasoning model can emit no tokens at all during the thinking phase, so your read timeout still fires — and the total time from first token to last is still long.Recommendation: set the timeout to 300-600 seconds for reasoning models, and match your thinking tier (reasoning_effort / thinking) to the time you have allowed — a higher tier needs more headroom.

③ Base URL selection: the CDN node cannot carry long requests

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 (recommended in mainland China) or vip.apiyi.com (recommended overseas). Full node comparison in the Base URL guide.

④ Hitting 429 concurrency limits: contact support

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:

Implement exponential backoff so you do not saturate the limit in bursts
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? for the rules.

Code examples

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"
  }'

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

Step 1: Confirm the SDK timeout actually applies

Some frameworks wrap another timeout around the HTTP client. Print the effective configuration and confirm the parameter you changed is the one being used.

Step 2: Check every hop in the path

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.

Step 3: Confirm you are not on the CDN node

Check whether your Base URL is api-cf.apiyi.com. For long requests, switch to api.apiyi.com or vip.apiyi.com.Rule of thumb: a 524 almost always means a Cloudflare-layer timeout, not a slow model.

Step 4: Distinguish timeouts from concurrency limits

Read the status code: 524 and dropped connections are timeout problems; 429 is a quota problem. The fixes are entirely different.

Step 5: Check call logs for actual latency

Look up the request’s real duration and billing in the console call logs, then derive a sensible timeout from it.

Common questions

Can I get a refund for a request that timed out?

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.

Can you offer an async endpoint so I can fetch results by ID after a disconnect?

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?Video models are natively async and are not affected by this.

Does streaming prevent timeouts?

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.

Is there a downside to setting a very large 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.

What is the difference between 524 and 429?

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.

Image API best practices

Per-model timeout table and output format reference

How do I set the Base URL?

Differences between the four nodes and how to choose

Are image endpoints sync or async?

Synchronous mode and client-side task management

How much concurrency can I use?

Concurrency limits by model type and quota requests

Contact Us

WeCom Support

Scan the QR code or click to contact supportTimeout troubleshooting and concurrency quota requests

Email

Support: [email protected]Business: [email protected]

Site Features

Models & API

Tokens & Logs

Enterprise Services

Billing & Security

Network & Connection

Account & Login

Short Answer

Timeout cheat sheet

The four keys in detail

Code examples

Still timing out after raising the timeout? Check every hop

Common questions

Image API best practices

How do I set the Base URL?

Are image endpoints sync or async?

How much concurrency can I use?

Contact Us

WeCom Support

Email

​Short Answer

​Timeout cheat sheet

​The four keys in detail

​Code examples

​Still timing out after raising the timeout? Check every hop

​Common questions

​Related Documentation

Image API best practices

How do I set the Base URL?

Are image endpoints sync or async?

How much concurrency can I use?

​Contact Us

WeCom Support

Email

Short Answer

Timeout cheat sheet

The four keys in detail

Code examples

Still timing out after raising the timeout? Check every hop

Common questions

Related Documentation

Contact Us