API reference

The machine-readable OpenAPI 3.1 description is available at /openapi.json. Treat model availability as key-specific: use the authenticated GET /v1/models response instead of hard-coding a model list.

Choose the server for your key

The paths below are relative to the selected API origin. Do not add the /token prefix to an API-credit key, and do not omit it for a token-budget key.

Authentication

Send the secret from a trusted server environment. OpenAI-compatible routes and the usage route use Authorization: Bearer $CLOUDSERVICE_API_KEY. Anthropic-compatible routes accept that bearer header or x-api-key: $CLOUDSERVICE_API_KEY. Send one authentication method, not both, and never expose a key in browser JavaScript or a public repository.

# API-credit key
export CLOUDSERVICE_API_ORIGIN="https://api.yourdomain.example"

# Token-budget key (use this instead for a token key)
# export CLOUDSERVICE_API_ORIGIN="https://api.yourdomain.example/token"

export CLOUDSERVICE_API_KEY="YOUR_CLOUDSERVICE_API_KEY"

Endpoints

GET /v1/models

Returns the public catalog when no credential is supplied. With a valid credential, the response is filtered to that key’s provider scope and entitlements. If an authentication header is present but invalid, the request fails instead of falling back to the public catalog.

curl "$CLOUDSERVICE_API_ORIGIN/v1/models" \
  -H "Authorization: Bearer $CLOUDSERVICE_API_KEY"

The response is an OpenAI-style list object. Copy the exact data[].id value into generation requests.

POST /v1/chat/completions

Creates an OpenAI-compatible chat completion. Required fields are model and a non-empty messages array. Optional fields include stream, max_tokens, and supported OpenAI-format tools.

curl "$CLOUDSERVICE_API_ORIGIN/v1/chat/completions" \
  -H "Authorization: Bearer $CLOUDSERVICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_AUTHENTICATED_MODEL_ID",
    "messages": [{"role": "user", "content": "Reply with hello."}],
    "max_tokens": 32
  }'

POST /v1/responses

Creates an OpenAI-compatible Responses API result. Supply model and input. Use max_output_tokens to cap output and stream: true for server-sent events.

curl "$CLOUDSERVICE_API_ORIGIN/v1/responses" \
  -H "Authorization: Bearer $CLOUDSERVICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_AUTHENTICATED_MODEL_ID",
    "input": "Reply with hello.",
    "max_output_tokens": 32
  }'

POST /v1/messages

Creates an Anthropic-compatible message. Supply model and a non-empty messages array. max_tokens defaults to 1,024 when omitted and is capped at the selected model’s published output limit.

curl "$CLOUDSERVICE_API_ORIGIN/v1/messages" \
  -H "Authorization: Bearer $CLOUDSERVICE_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_AUTHENTICATED_MODEL_ID",
    "messages": [{"role": "user", "content": "Reply with hello."}],
    "max_tokens": 32
  }'

POST /v1/messages/count_tokens

Returns an input_tokens estimate for a valid Anthropic-format request without creating a model response or deducting model-generation usage.

curl "$CLOUDSERVICE_API_ORIGIN/v1/messages/count_tokens" \
  -H "Authorization: Bearer $CLOUDSERVICE_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_AUTHENTICATED_MODEL_ID",
    "messages": [{"role": "user", "content": "Reply with hello."}]
  }'

GET /v1/usage

Returns the authenticated key’s status, billing mode, provider scope, rate limit, request count, token totals, and credit or token balance. The response uses object: "usage.summary" and is intended for server-side account and diagnostics views.

curl "$CLOUDSERVICE_API_ORIGIN/v1/usage" \
  -H "Authorization: Bearer $CLOUDSERVICE_API_KEY"

Streaming, retries, and errors

• Generation routes return JSON by default and server-sent events when stream is true.
• Supply a stable Idempotency-Key when a client may retry the same logical POST request.
• Do not retry after response content has started. For a 429 or safe transient failure, respect Retry-After.
• Record the x-request-id response header when contacting support. OpenAI-compatible and Anthropic-compatible routes use their respective error envelope shapes.

Detailed guides

• Chat Completions fields and tool use
• OpenAI compatibility boundaries
• Streaming event handling
• Authentication and key modes
• Error codes and recovery
• Rate limits, headers, and retry behavior
• Model IDs, context limits, and pricing

Runnable examples

• cURL examples — model discovery and a first chat completion from a terminal.
• Python SDK examples — OpenAI-compatible client setup and streaming.
• JavaScript SDK examples — Node and TypeScript client setup.
• OpenAI SDK examples — Chat Completions and Responses through the official SDK.