API reference
HopBase API Base URLs, per-group API key authentication, request IDs, error shapes and concurrency limits, plus an index of every endpoint.
HopBase is a multi-model API gateway: chat, images, video and speech are all called through a single domain, https://api.hop-base.com, using the official OpenAI and Anthropic formats, so existing SDKs only need a new Base URL and API key. This section has one page per endpoint; parameter tables and examples are generated from the OpenAPI description.
Endpoints
/v1/chat/completionsCreate chat completionPOST/v1/responsesCreate responsePOST/v1/messagesCreate message/v1/images/generationsCreate imagePOST/v1/images/editsEdit imageGET/v1/images/tasksGet image task/v1/video/generateSubmit video taskGET/v1/video/tasks/{task_id}Get video taskGET/v1/video/tasksList video tasksPOST/v1/kling/subjectsCreate custom subjectGET/v1/kling/subjectsList custom subjectsPOST/v1/kling/facesLip-sync face identification/v1/audio/speechCreate speechPOST/v1/t2a_v2Create T2A v2 audioPOST/v1/files/uploadUpload clone audioGET/v1/files/listList clone audioGET/v1/files/retrieveRetrieve clone audioPOST/v1/files/deleteDelete clone audioPOST/v1/voice_cloneCreate a cloned voicePOST/v1/get_voiceList voicesPOST/v1/delete_voiceDelete voiceBase URL
| Protocol | Base URL | Used for |
|---|---|---|
| OpenAI-compatible | https://api.hop-base.com/v1 | Chat, Responses, images, video, speech, /v1/models, /v1/usage |
| Anthropic | https://api.hop-base.com | /v1/messages for Claude models (without /v1 in the SDK) |
The protocol is determined by the client and the model type, not by the key format. For the full mapping by scenario (Claude Code, Codex CLI, each model family), see Base URL and protocols. Wan / HappyHorse use the native video path /api/v1/services/aigc/video-generation/video-synthesis, mounted at the domain root.
Authentication
Every endpoint authenticates with an sk- key created under API Keys in the console. Use either request header:
Authorization: Bearer sk-your-key
x-api-key: sk-your-keyThe Gemini native protocol (/v1beta/models/{model}:generateContent) also accepts x-goog-api-key: sk-your-key and the ?key= URL parameter. GET /v1/usage accepts only Authorization: Bearer.
When you create or edit a key you choose one or more groups (for example "Codex Pro", "Claude Max Enterprise" and "GPT Image (all models)"), across platforms. The key can only call the models those groups offer, and each request must use an endpoint its model supports: Claude models accept /v1/messages and /v1/chat/completions but not /v1/responses, so a Claude-only key calling /v1/responses returns 404 "This API path is not supported by the current platform", and a model outside all of the key's groups returns 404 model_not_found. If one project needs both chat and image generation, add both groups to the same key (or edit an existing key to add a group). Groups whose models overlap cannot share a key, and a subscription group must be a key's only group. Each request is served and billed by the one group that covers the requested model; it never switches to another group behind your back. The one exception is GPT Official Direct (Azure) combined with Codex Plus or Codex Pro, or with GPT Image (all models): models in both groups go to Azure first, a request that fails on Azure before any output switches to the other group, and it is billed by — and shown in usage records under — the group that actually served it (see Which group to choose). The models available to a key are whatever GET /v1/models returns for it: the union of all its groups.
Inject keys through environment variables or your deployment platform; never hard-code them in source or commit them to Git.
Request ID
Every response carries an x-request-id header that uniquely identifies the request. When reporting a problem, include the x-request-id, the time it happened (with time zone), the model ID and the full error text. Server-side failures do not show the original error in the console; investigations rely on x-request-id.
curl -i https://api.hop-base.com/v1/models \
-H "Authorization: Bearer $HOPBASE_API_KEY"
# HTTP/2 200
# x-request-id: …Some model responses carry their own rate-limit headers (x-ratelimit-*, anthropic-ratelimit-*). They do not describe the limits of your account or key, so do not throttle based on them.
Errors
OpenAI protocol endpoints return {"error": {"message", "type", "code"}}; /v1/messages returns the Anthropic shape {"type": "error", "error": {"type", "message"}}, with no code. Message language follows Accept-Language and defaults to English. In code, branch on the HTTP status and code, never on the message text.
| Status | Meaning | Retryable |
|---|---|---|
| 400 / 413 | Invalid parameters / request body over 60 MB | No, fix the request first |
| 401 | Missing, invalid or expired API key | No |
| 402 | Balance or quota exhausted; for video submissions, the balance does not cover in-flight reservations | After topping up |
| 403 | Account or member disabled, or not allowed to use this group | No |
| 404 | The model or path is not served by any of this key's groups | No |
| 429 | Account or key concurrency cap reached, or the service is busy | Retry per Retry-After |
| 502 / 503 / 504 | Service temporarily unavailable or timed out | Retry with backoff |
Once a streaming request starts producing output, the HTTP status is already 200 and later errors arrive as events; see Streaming events. For the full list of error codes and retry rules, see Error codes and retries.
Concurrency and rate limits
HopBase limits the number of requests in flight at the same time, not requests per minute: an account allows 5 requests in flight by default. If your traffic keeps hitting the cap, it is raised automatically for a while (up to a level that depends on your balance), and a permanent increase is available on request; each key can have its own cap set in the console, and the lower of the two applies. Requests over the cap return 429 immediately (user_concurrency_limit / apikey_concurrency_limit, with Retry-After: 1 and Retry-After-Ms); nothing is queued server-side.
Chat, image generation, video submission and /v1/messages/count_tokens consume concurrency; task polling and GET /v1/models do not. For timeout behavior and recommended client read timeouts, see Concurrency, timeouts, and billing.
Billing
Successful requests are billed in the model's pricing unit (tokens / image / second / character). Failed requests are not billed in principle; interrupted streams are billed for the output already produced; failed async tasks are not billed. Check your balance with GET /v1/usage; official list prices are in the public catalog GET /api/v1/models/pricing (field reference).
Machine-readable descriptions
/openapi.json: OpenAPI 3.1 description of every endpoint in this section; import it into Postman, Apifox or an SDK generator./spec/models/index.json: one request-body JSON Schema per image model, with numbers taken from the gateway validation code.- Request builder: build a valid image generation request for a model in the browser and generate code for it.