Skip to content

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

Base URL

ProtocolBase URLUsed for
OpenAI-compatiblehttps://api.hop-base.com/v1Chat, Responses, images, video, speech, /v1/models, /v1/usage
Anthropichttps://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-key

The 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.

A key calls the models of the groups it includes.

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.

StatusMeaningRetryable
400 / 413Invalid parameters / request body over 60 MBNo, fix the request first
401Missing, invalid or expired API keyNo
402Balance or quota exhausted; for video submissions, the balance does not cover in-flight reservationsAfter topping up
403Account or member disabled, or not allowed to use this groupNo
404The model or path is not served by any of this key's groupsNo
429Account or key concurrency cap reached, or the service is busyRetry per Retry-After
502 / 503 / 504Service temporarily unavailable or timed outRetry 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.