Integration guide

Revision 2 · Updated 2026-11-12 · 2 min read

Connect models to Runtoken through their native protocols.

Prerequisites#

Before you start, prepare:

• Create a platform API key in the console; keep it on the server.
• Copy the model ID and native protocol from the catalogue.
• Prepare an HTTP client or SDK environment that can access the gateway.

Platform endpoint#

Every protocol shares one host. SDKs that expect an OpenAI-style base URL take the /v1 path.

Supported protocols#

Native asynchronous video tasks use a separate API, configured per model.

Example request#

Streaming chat request. Pick the protocol your model speaks.

# Optional: prefer a channel with -H 'Channel-Slug: your-channel-slug'
curl -N 'https://api.runtoken.net/v1/chat/completions' \
  -H 'Authorization: Bearer YOUR_PLATFORM_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [{ "role": "user", "content": "Hello!" }],
    "stream": true
  }'

curl -N 'https://api.runtoken.net/v1/responses' \
  -H 'Authorization: Bearer YOUR_PLATFORM_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "YOUR_MODEL_ID",
    "input": "Hello!",
    "stream": true
  }'

curl -N 'https://api.runtoken.net/v1/messages' \
  -H 'x-api-key: YOUR_PLATFORM_KEY' \
  -H 'anthropic-version: 2023-06-01' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "YOUR_MODEL_ID",
    "max_tokens": 1024,
    "messages": [{ "role": "user", "content": "Hello!" }],
    "stream": true
  }'

curl -N 'https://api.runtoken.net/v1beta/models/YOUR_MODEL_ID:streamGenerateContent?alt=sse' \
  -H 'x-goog-api-key: YOUR_PLATFORM_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [{ "parts": [{ "text": "Hello!" }] }]
  }'

Replace these placeholders before running the example.

Routing#

Add an optional Channel-Slug header to prefer a channel. Copy the slug from the model’s price details.

How failover works#

• If the preferred channel is unavailable or failing, the request falls back to the normal platform order before any output starts.
• Once output has started, a request never switches channels.
• Routes fixed by an administrator take precedence and never switch.

Billing & usage#

• The platform requests usage from the model on every call. Interrupted streams may go to billing review.
• Media is billed only on explicit evidence. Prices by count, characters or duration use zero token rates.
• For transcription, use verbose_json to get duration where the model supports it.

Errors#

Errors return a JSON body with a type and a human-readable message.

200

Request succeeded.

400

The request body or a parameter is invalid.

401

Missing, invalid, expired or revoked key.

429

A rate or spend limit was reached. The error names the limit and when it resets.

503

Service temporarily unavailable. Retry with backoff.

Not supported yet#

Next steps#