HopBase DocsAPI 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-keyx-goog-api-key and the ?key= URL parameter are not supported. GET /v1/usage accepts only Authorization: Bearer.
Every key is bound to one group (for example "Codex Pro", "Claude Max (Official, Full Quota)" or "GPT Image (all models)") and can only call the models that group offers, on endpoints of that group's protocol: a Claude key calling /v1/chat/completions returns 404 "The current platform does not support this API path", and a chat group key calling an image model returns 404 model_not_found. If one project needs both chat and image generation, create two keys and put them in separate environment variables. The models available to a key are whatever GET /v1/models returns for it.
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 does not belong to this key's group | 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, which can be raised 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.