HopBase DocsConcurrency, timeouts, and billing
Concurrency caps, timeouts, request size limits, and when requests are billed.
This page covers the runtime rules worth knowing before you integrate. For error codes and retry policy, see Error codes and retries.
Concurrency
| Scope | Default | Range | Over the cap |
|---|---|---|---|
| Account | 5 requests in flight | Raised on request | 429 user_concurrency_limit |
| API key | No key-level cap | Any whole number from 1 up, set on the key under API Keys; empty or 0 = no key-level cap | 429 apikey_concurrency_limit |
- When both caps are set, the lower one applies.
- Chat, image generation, video submission and
/v1/messages/count_tokensconsume concurrency; task polling andGET /v1/modelsdo not. - Over the cap you get 429
User concurrency limit reached, please retry laterorAPI key concurrency limit reached, please retry later, withRetry-After: 1. - Contact us to raise the cap.
Requests beyond the cap are rejected immediately with 429; nothing waits server-side. Throttle in your client, or retry as Retry-After says.
Timeouts
| Case | Server behaviour | Suggested client read timeout |
|---|---|---|
| Chat on Gemini direct plans | A single generation that has not finished in about 100 seconds is treated as timed out and retried, so total wait can be longer | 240s or more |
| Non-streaming chat elsewhere | Total time is capped (Claude: 300s, then 504); large contexts can take over a minute to first token | 300s or more; stream long outputs |
| Streaming chat | No output for about 90–150s (by model), or about 150s of silence mid-stream, counts as stalled: retried or ended with an error. Heartbeats keep the connection open | 300s or more; enable reasoning summaries on heavy-reasoning models |
| Synchronous image generation | Large images commonly take 30–100 seconds | 300s or more |
| Async images and video | Submission returns immediately; results come from polling. Unfinished tasks fail after 24h (Seedance) or 2h (Kling, Midjourney, Wan / HappyHorse, MiniMax) | 60s is enough for the submission |
Request size
| Limit | Minimum | Maximum | Over the limit |
|---|---|---|---|
| Request body, any endpoint | — | 60 MB | 413 request_too_large |
input on /v1/audio/speech (speech-2.8-hd / speech-2.8-turbo) | 1 character | 4,096 characters | 400 |
text on /v1/t2a_v2 (speech-2.8-hd / speech-2.8-turbo) | 1 character | 10,000 characters | 400 |
input on /v1/audio/speech (seed-tts-2.0 / seed-icl-2.0 / seed-audio-1.0) | 1 character | 5,000 characters for seed-tts-2.0 and seed-icl-2.0, 3,000 for seed-audio-1.0 (a Chinese character counts as 1) | 400 |
Recording audio on /v1/voice_clone (seed-icl-2.0) | — | 10 MB decoded; 16 MiB request body | 400 / 413 |
Base64 images and video reach 60 MB quickly, so compress them or pass a URL where the model supports it. Split long speech scripts client-side; see Text-to-speech API. Per-model limits on media (image count, file size, duration) are listed on each model's guide.
Billing
| Situation | Billed |
|---|---|
| Successful request | Yes, per the model's unit (tokens / image / second / character — a Han character counts 2 for speech) |
| Failed request (4xx, 5xx) | No in principle; output already produced is billed (e.g. Responses failing after generating tokens) |
| Stream interrupted midway, or client disconnected early | Yes, for the output already produced |
| Failed async task | No |
Also worth knowing:
- An empty balance blocks new requests: once the available balance reaches zero, new requests return 402. Requests already in flight are unaffected.
- Video submissions reserve balance: the estimated cost is reserved up front, so a positive balance can still return 402 when "reserved in flight + this estimate" exceeds it. Reservations are released when the task ends.
- Key quotas: if a key has its own quota, exhausting it returns 402
insufficient_quotawith "API key quota exhausted".
Checking balance and usage
curl https://api.hop-base.com/v1/usage \
-H "Authorization: Bearer sk-your-key"balance is what this key can still spend right now. Field meanings, units and the error cases are in Account and catalog API. For itemised records, open Usage in the console.
Result links for images and video expire on different schedules — see Image generation API and Video generation.
Next steps
- Error codes and retries: what each error code means and whether to retry
- Account and catalog API: check the balance, usage, and model catalog over the API
- Available models: find the model IDs available to a key