Hyperouter API

Version v1 · Updated October 25, 2026

Hyperouter is one HTTP API in front of many model vendors. You send a request that names a model. Hyperouter picks a provider that can serve it, forwards the request, and charges your balance at that provider’s list price.

Every endpoint follows OpenAI’s request and response shapes. The OpenAI SDKs work when you change the base URL and the API key. Hyperouter adds a few fields to OpenAI’s bodies. They are marked as additions in this reference.

Quickstart

1. Sign in and create an API key. Keys start with sk-hr-v1- and are shown once.
2. Store it in an environment variable, for example HYPEROUTER_API_KEY.
3. Add credits: open a top-up request in the dashboard. Staff credit your balance when the payment is confirmed.
4. Point any OpenAI SDK at the base URL above and pick a model.

curl https://api.hyperouter.app/v1/chat/completions \
  -H "Authorization: Bearer $HYPEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "x-ai/grok-4.7",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.hyperouter.app/v1",
  apiKey: process.env.HYPEROUTER_API_KEY,
});

const res = await client.chat.completions.create({
  model: "x-ai/grok-4.7",
  messages: [{ role: "user", content: "Hello" }],
});
console.log(res.choices[0].message.content);

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.hyperouter.app/v1",
    api_key=os.environ["HYPEROUTER_API_KEY"],
)

res = client.chat.completions.create(
    model="x-ai/grok-4.7",
    messages=[{"role": "user", "content": "Hello"}],
)
print(res.choices[0].message.content)

Authentication

Send your API key as a bearer token on every request.

Authorization: Bearer sk-hr-v1-...

Keys carry access to your balance. Keep them on your server. Never put them in browser or mobile code. Hyperouter stores only a hash of each key, so a lost key cannot be shown again: create a new one.

In the dashboard you can name each key, give it a credit limit, and disable it. A disabled key stops working at once. A request that would take a key past its limit is refused with 402 insufficient_credits.

Authentication errors

curl https://api.hyperouter.app/v1/generations/0194f2c4-7a1e-7b3c-9d02-5f6a1c0e8b21 \
  -H "Authorization: Bearer $HYPEROUTER_API_KEY"

{ "error": { "message": "The API key is not valid.", "type": "authentication_error", "code": "invalid_api_key", "param": null } }

Errors

Every error uses OpenAI’s error object and a matching HTTP status.

{
  "error": {
    "message": "n must be an integer from 1 to 128",
    "type": "invalid_request_error",
    "code": "invalid_body",
    "param": "n"
  }
}

Types and statuses

Hyperouter never answers 502 or 504: those would reach you as a bare page from our edge network, without the error body. Where a gateway would answer them, you get 503 with the body below and the gateway status in X-Upstream-Status.

Codes you can get

Retries and idempotency

A network error or a timeout does not tell you whether Hyperouter received the request. If you send it again, you may start a second job and pay twice. An Idempotency-Key makes a repeat safe: Hyperouter recognises the repeat, starts no second job, places no second hold, and answers from the first request.

Send one on every request that costs money. Generate a new random value, such as a UUID v4, for each new request. Keep it with the request, and send the same value every time you send that request again.

Sending a key

The header is accepted on these endpoints:

The OpenAI SDKs do not send this header on their own. Pass it as an extra header; the SDKs then re-send it unchanged on their automatic retries.

curl https://api.hyperouter.app/v1/images/generations \
  -H "Authorization: Bearer $HYPEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -d '{"model": "x-ai/grok-imagine-image", "prompt": "A lighthouse at dusk", "n": 1}'

import uuid

key = str(uuid.uuid4())  # one per request; reuse it when you retry this request
img = client.images.generate(
    model="x-ai/grok-imagine-image",
    prompt="A lighthouse at dusk",
    extra_headers={"Idempotency-Key": key},
)

import { randomUUID } from "node:crypto";

const key = randomUUID(); // one per request; reuse it when you retry this request
const img = await client.images.generate(
  { model: "x-ai/grok-imagine-image", prompt: "A lighthouse at dusk" },
  { headers: { "Idempotency-Key": key } },
);

What a repeat returns

Rules

• Scope. A key belongs to the API key that sent it. Two API keys can use the same value without affecting each other.
• Window. A key is honoured for 30 minutes after the first request. Retry within that time.
• Same request. Two requests are the same when the method, the path and the body match. JSON is compared after parsing, so field order and whitespace do not matter. A picture or video is a URL in the body, so the URL is compared, never the bytes it serves.
• Billing. A request made under a key is billed at most once, whatever the number of repeats. A repeat answered from the first request costs nothing.
• Guarantee. One key never starts more than one job, including when two repeats arrive at the same time.

Chat completions

Chat replies are not replayed. A repeat with the same key answers 409 with code idempotency_key_replayed, and error.generation_id is the first request's id. The request is not run or billed again. Look the first request up with GET /v1/generations/{id} to see its status, usage and cost. If the first chat completion failed and was not billed, its key is freed, and a repeat runs as a new request.

{
  "error": {
    "message": "A request with this Idempotency-Key already ran as generation 019a1f3c-5b7e-7d21-9c4a-2e8f6b0d3a17. Chat replies are not replayed: GET /v1/generations/019a1f3c-5b7e-7d21-9c4a-2e8f6b0d3a17 for its record.",
    "type": "conflict",
    "code": "idempotency_key_replayed",
    "param": null,
    "generation_id": "019a1f3c-5b7e-7d21-9c4a-2e8f6b0d3a17"
  }
}

Automatic retries in the OpenAI SDKs

The OpenAI SDKs retry a 408, 409, 429 or 5xx answer twice by default, unless the answer carries the response header x-should-retry: false. Hyperouter sends x-should-retry: false on every answer where a retry would start a second job or a second charge:

• the 503 timeout of a sync image, whose job goes on and is billed when it succeeds; poll GET /v1/generations/{id} with its generation_id;
• a 500 after the job was created, for example when a finished image cannot be read back;
• 409 idempotency_key_reused and idempotency_key_replayed, which a retry cannot change.

It never sends it on a 429, on 409 idempotency_key_in_use, or on a 5xx from before any job exists. Those are safe to retry. With an Idempotency-Key, every retry is safe.

Models

Lists every model your account can call right now, with its prices and what it supports. A model with no enabled provider is not listed. Some models need access granted to your account: they are listed once it is. This endpoint needs an API key, and lists the models that key's account can call. The answer can be cached for 60 seconds, by your client only.

Parameters

None.

Response

{
  "data": [{
    "id": "x-ai/grok-4.7",
    "name": "Grok 4.7",
    "kind": "chat",
    "context_length": 500000,
    "architecture": { "input_modalities": ["text", "image"], "output_modalities": ["text"] },
    "pricing": {
      "prompt": "0.000002", "completion": "0.000006", "input_cache_read": "0.0000005",
      "request": "0", "image": "0", "video_second": "0"
    },
    "top_provider": { "context_length": 500000, "max_completion_tokens": 32768 },
    "response_modes": ["sync", "stream"],
    "supported_parameters": ["max_tokens", "temperature", "top_p", "stop", "stream", "tools", "tool_choice", "response_format", "seed", "frequency_penalty", "presence_penalty"],
    "extra_parameters": {}
  }]
}

curl https://api.hyperouter.app/v1/models \
  -H "Authorization: Bearer $HYPEROUTER_API_KEY"

Errors

None specific to this endpoint.

Chat models

Prices per 1M tokens: input / cached input / output.

On the x-ai/ models, a request with 200,000 prompt tokens or more is billed entirely at the long-context rates, which are twice these. The deepseek/ models have one rate at every prompt length, reason before they answer by default (reasoning_effort: "none" turns it off), and count their reasoning in max_tokens, at most 384,000. z-ai/glm-5.3 always reasons: reasoning_effort is low, high or max, and none is refused. The openai/ models reason too and take prompts of at most 272,000 tokens.

Chat completions

Creates a model response for a conversation. The body is OpenAI’s Chat Completions request. Hyperouter adds models, provider and moderation.

Parameters

Other fields are ignored. supported_parameters of each model in GET /v1/models lists exactly what it takes. Grok 4.20 and newer ignore logprobs and top_logprobs, so they are not listed.

The provider object

By default Hyperouter sends each chat request to the healthy provider with the lowest price for that model, and breaks ties by the lowest recent time to first token. A provider that errors repeatedly is skipped until it recovers. The provider object follows OpenRouter’s request shape.

Response

OpenAI’s chat completion. The id is the request id: look it up with GET /v1/generations/{id}. Hyperouter adds provider (the public name of the provider that filled the request, for example xAI) and usage.cost (the charge, in USD, as a JSON number).

{
  "id": "0194f2c4-7a1e-7b3c-9d02-5f6a1c0e8b21",
  "object": "chat.completion",
  "model": "x-ai/grok-4.7",
  "provider": "xAI",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "Hello! How can I help?" },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 8,
    "total_tokens": 17,
    "prompt_tokens_details": { "cached_tokens": 0 },
    "cost": 0.000066
  }
}

A prompt-rewrite model answers with one choice, a usage of zero tokens and a fixed cost per request.

Streaming

With "stream": true the response is a stream of server-sent events in the OpenAI chunk format. It ends with data: [DONE]. When you set stream_options.include_usage, the last chunk before [DONE] has an empty choices array and a usage object that includes cost, and a provider field. Usage is always collected for billing, whether or not you ask for the chunk.

Until the first token arrives, the stream sends the comment line : processing every 15 seconds to keep the connection open. SSE clients ignore comments.

Fallback to another provider happens only before the first token is sent. If a provider fails mid-stream, the stream ends with data: {"error": {...}} followed by data: [DONE], and you are billed for the tokens already produced.

You are billed for the tokens the provider produces, whether or not you read them. A stream you abort, or a reply you stop waiting for, is not stopped at the provider, which goes on and bills its whole answer: Hyperouter reads it to its end (for at most 5 more minutes) and bills that.

A provider that has accepted a request may be running it. If it then stops answering (5 minutes with no token on a stream, or longer than a reply of max_tokens takes) or its answer breaks off before the first token, the request is not sent to another provider: it answers 503 with code timeout or upstream_error with error.generation_id, and is billed on its hold, with usage_estimated: true on its record.

Example

curl https://api.hyperouter.app/v1/chat/completions \
  -H "Authorization: Bearer $HYPEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "x-ai/grok-4.7",
    "models": ["x-ai/grok-4.6"],
    "provider": { "sort": "latency" },
    "messages": [{ "role": "user", "content": "Hello" }]
  }'

Errors

Images

Both follow OpenAI’s Images API and take a JSON body. /v1/images/edits takes OpenAI’s JSON form: the pictures are images, 1 to 5 https URLs. The OpenAI SDKs' images.edit sends picture files as multipart/form-data, and that works too: Hyperouter's edge stores each file (PNG, JPEG or WebP, 20 MiB each, 50 MiB a request) for 3 days at an unguessable https://api.hyperouter.app/u/... URL that the provider fetches, then runs the request as JSON. A video file is refused (400 invalid_video): send a video as an https URL. Both take the shared features below and any model-specific parameters as top-level fields.

Parameters

A shared feature that the model does not list, such as seed on a model without it, is refused with 400 unsupported_parameter. It is never dropped silently, because it would change the output and the price.

Response

{
  "created": 1730000000,
  "data": [{ "url": "https://..." }],
  "usage": { "cost": 0.02 },
  "id": "0194f2c4-7a1e-7b3c-9d02-5f6a1c0e8b21"
}

Hyperouter stores every result for 30 days, so a link never points at a vendor. After 30 days the record stays but its outputs is empty.

Waiting for the result

• On a model whose response_modes include sync, the request waits for the image for up to 90 seconds and answers with its real status: 200 with the images, or the error. Validation, balance and capacity errors come first, with their own status.
• An image that is not ready after 90 seconds answers 503 with code timeout and the response header x-should-retry: false, so the OpenAI SDKs do not retry it and start a second image. The job goes on, and the error carries its id as generation_id: poll GET /v1/generations/{id} for the result. You are billed only if it succeeds. To retry safely yourself, send an Idempotency-Key: a retry with the same key waits on the same job.
• A model whose response_modes are only async needs Prefer: respond-async. Without it the answer is 400 with code async_required.

• To avoid a held connection on any model that lists async, send Prefer: respond-async (RFC 7240). The header may repeat and may carry other preferences, for example Prefer: wait=10, respond-async. You get 202 at once with the response header Preference-Applied: respond-async:

  { "id": "0194f2c4-7a1e-7b3c-9d02-5f6a1c0e8b21", "status": "queued" }

  Poll GET /v1/generations/{id}, or receive an image.completed or image.failed webhook. Webhooks fire for images only for jobs you sent with this header.

Examples

curl https://api.hyperouter.app/v1/images/generations \
  -H "Authorization: Bearer $HYPEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "x-ai/grok-imagine-image", "prompt": "A lighthouse at dusk", "n": 1}'

curl https://api.hyperouter.app/v1/images/edits \
  -H "Authorization: Bearer $HYPEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "x-ai/grok-imagine-image", "prompt": "make it night",
       "images": [{"image_url": "https://example.com/photo.png"}]}'

Errors

A failed job’s message ends with the provider’s own reason when it gave one, after Provider:, so a refused prompt, a busy provider and an outage read apart. URLs in it are replaced by <url>.

Image models

Some models need access granted to your account. The model reference in the dashboard lists every model your account can call, with its parameters, prices and notes.

Videos

Video follows OpenAI’s Videos API. A video is a job. A create, edit, extension or remix call answers 200 at once with the Video object in status queued. You poll GET /v1/videos/{id} until the status is completed, or receive a webhook. Prefer changes nothing here: videos are always asynchronous.

Create a video

The body is JSON, on every video endpoint; the OpenAI SDKs' videos.create with an input_reference picture file is also accepted, the file handled as for image edits. Every picture and video is an https URL to a public host, which is passed to the provider as it is: the provider must be able to fetch it, and one it cannot fetch or read fails the video with vendor_rejected, and nothing is charged. A data: URL, an http:// URL, an IP address or an internal name is refused with 400 invalid_image or invalid_video. A multipart/form-data body is refused with 400 unsupported_content_type.

Edit, extend and remix

The source video must have completed. A video given by URL is an https URL, passed to the provider as it is, like a picture. If you give a video by URL, seconds is needed on models that have no fixed maximum.

List, read, download, delete

The Video object

{
  "id": "0194f2c4-7a1e-7b3c-9d02-5f6a1c0e8b21",
  "object": "video",
  "model": "x-ai/grok-imagine-video",
  "status": "completed",
  "progress": 100,
  "prompt": null,
  "seconds": "8",
  "size": "",
  "created_at": 1730000000,
  "completed_at": 1730000137,
  "expires_at": 1732592000,
  "error": null,
  "remixed_from_video_id": null,
  "usage": { "cost": 0.4, "seconds": 8 }
}

A video is billed on the seconds you request. The amount is held up front, and released in full if the job fails.

Example: x-ai/grok-imagine-video

Model x-ai/grok-imagine-video makes a video from a prompt, with an optional picture to start from. seconds is 1 to 15. Price: $0.050 per second.

curl https://api.hyperouter.app/v1/videos \
  -H "Authorization: Bearer $HYPEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "x-ai/grok-imagine-video",
    "prompt": "She turns to the camera and smiles",
    "input_reference": { "image_url": "https://example.com/portrait.png" },
    "seconds": 8
  }'

{
  "id": "0194f2c4-7a1e-7b3c-9d02-5f6a1c0e8b21",
  "object": "video",
  "model": "x-ai/grok-imagine-video",
  "status": "queued",
  "progress": 0,
  "prompt": "She turns to the camera and smiles",
  "seconds": "8",
  "size": "",
  "created_at": 1730000000,
  "completed_at": null,
  "expires_at": 1732592000,
  "error": null,
  "remixed_from_video_id": null,
  "usage": null
}

This job is charged 8 × $0.050 = $0.40, so the settled object shows "usage": {"cost": 0.4, "seconds": 8}.

Errors

Video models

The model reference in the dashboard lists every video model your account can call.

Generations

Returns the record of one of your requests, of any kind: its status, usage, charge, timing and, for images and videos, signed links to the outputs. Use it to poll an image request you sent with Prefer: respond-async and to reconcile spend. Prompt and completion text are never in the record. Hyperouter keeps them encrypted for 180 days only to meet legal obligations, and no API or dashboard page returns them (Privacy Policy).

Parameters

Response

{
  "data": {
    "id": "0194f2c4-7a1e-7b3c-9d02-5f6a1c0e8b21",
    "kind": "chat",
    "model": "x-ai/grok-4.7",
    "provider_name": "xAI",
    "status": "done",
    "created_at": "2026-10-24T08:12:00Z",
    "finished_at": "2026-10-24T08:12:02Z",
    "usage": {
      "input_tokens": 120, "output_tokens": 300, "cache_read_tokens": 0,
      "image": 0, "video_seconds": 0, "cost": 0.00204
    },
    "usage_estimated": false,
    "ttft_ms": 320,
    "latency_ms": 2100,
    "error": null,
    "outputs": []
  }
}

curl https://api.hyperouter.app/v1/generations/0194f2c4-7a1e-7b3c-9d02-5f6a1c0e8b21 \
  -H "Authorization: Bearer $HYPEROUTER_API_KEY"

Errors

Model-specific parameters

Some models have fields that other models do not. These are extra parameters. You send them as top-level fields of the request body, like any other field. Every OpenAI SDK can send them (extra_body in Python, extra properties in JavaScript).

GET /v1/models lists each model’s extra parameters in extra_parameters. Each entry has:

The model reference in the dashboard describes the extra parameters of each model your account can call.

Rules

• A known parameter that the model does not have is refused: 400 invalid_request_error with code unsupported_parameter, param set to the field name (for example loras) and the message This model does not support "loras". A parameter is known when some model in the catalog declares it. The same rule covers the shared features (resolution, ratio, audio, seed, negative_prompt, first_frame, last_frame, reference_images, reference_videos, prompt_extend). Nothing is dropped silently, because it would change the output and the price.
• A value of the wrong type is refused with 400 invalid_body, param set to the name and a message such as loras must be of type array.
• A value outside values is refused with 400 invalid_body and the message <name> must be one of [...].
• A field that no model declares is ignored, as OpenAI’s API ignores unknown fields.
• Every model checks its parameters against its own schema: allowed values, minimum and maximum, required fields and list lengths. A value outside it answers 400 invalid_body with param naming the field, for example seconds must be one of 5, 8.
• A combination a vendor does not allow, such as reference media together with keyframes, answers 400 invalid_combination with the reason. The checks run before anything is charged.
• Fields that change the price, such as resolution and audio, are priced in the up-front hold, so the hold is exact.

Shared features

These fields have the same name on every model that has them. A model lists the ones it takes in supported_parameters.

Prompt expansion

With "prompt_expand": true, Hyperouter rewrites your prompt for the model before it renders: a fuller description for a picture, a second-by-second script for a video. It is off by default, so a prompt goes as written. Only a model whose supported_parameters lists prompt_expand takes it, and only to create an image or a video; on any other model, and on a video edit, extension or remix, it is refused with 400 unsupported_parameter, and it cannot be combined with prompt_extend: true (400 invalid_body).

Prompt expansion is available to an account once Hyperouter has enabled it; open a support ticket to request access. Until then GET /v1/models does not list prompt_expand for any model, and a request with prompt_expand: true on a model that offers it answers 403 permission_error, code feature_not_enabled, param prompt_expand, with nothing held or sent to the provider.

• What rendered. The image answer, the video object and GET /v1/generations/{id} carry expanded_prompt, the prompt the model received. It is kept for 30 days after the request, then answered as null. prompt stays your own text.
• Writer. prompt_expand_model names the chat model that writes the rewrite; the default is x-ai/grok-4.6. It is valid only with prompt_expand: true (else 400 invalid_body). A model that does not exist or is not a chat model is 400 unknown_model, and one your account cannot call is 403 model_not_enabled, both before anything is held. A writer that reads images is shown the request's pictures; one that does not writes from the text alone.
• Price. The rewrite is billed on the same request, at the token prices of the model that wrote it (prompt_expand_model, else x-ai/grok-4.6) for the tokens it used, and its most is held up front with the render. The model reference gives each model's details.
• When it does not run. A rewrite that fails, times out or cannot be used renders your prompt as sent, answers expanded_prompt: null and costs nothing.
• Language. Spoken lines in a video follow locale (else English) where the model speaks that language.

The rewrite as a chat model

An account with prompt expansion also gets a chat model that answers the rewrite instead of rendering it; your model reference names it. Call it on POST /v1/chat/completions with exactly one user message: its text is the prompt, and its image_url parts (https URLs, at most 5) are the pictures; a data: or http:// URL is 400 invalid_image with param messages. target_model is required: a model that lists prompt_expand. seconds, locale and negative_prompt are optional. A video target with a picture is written from that first frame. It does not stream (stream: true is 400 unsupported_parameter), and any other message, a system message included, is 400 invalid_body.

This chat model always uses x-ai/grok-4.6; it does not take prompt_expand_model. choices[0].message.content is a JSON string, {"prompt": "...", "negative_prompt": "..."}, plus "beats" (one line per second) for a video target. It is billed at x-ai/grok-4.6's token prices, shown in usage. A prompt that asks for the model's instructions answers 400 prompt_rejected; a rewrite that is refused or comes back empty answers 422 expansion_refused, and one that fails 503 upstream_error. None of these is charged.

Moderation

The moderation field is OpenAI’s. It works on /v1/chat/completions, /v1/images/generations, /v1/images/edits and /v1/videos with its edit, extension and remix calls.

Any other value is refused: 400 invalid_request_error, code invalid_body, param moderation, message moderation must be auto or low.

low is available to an account once Hyperouter has enabled it; open a support ticket to request it. Until then a request with low answers 403 permission_error, code moderation_not_enabled, param moderation, and is not sent to the provider.

{
  "model": "qwen/qwen-image-2.0",
  "prompt": "...",
  "moderation": "low"
}

The response does not say whether the opt-out was used. The policies in the Terms of Service still apply. A request that the vendor’s filter refuses fails with 400 content_rejected and is not charged.

Webhooks

Instead of polling, an endpoint of yours can receive a request when a job ends. Add endpoints in the dashboard. The shape is OpenAI’s webhooks, signed with the Standard Webhooks scheme, so the OpenAI SDKs verify them.

The payload carries an id, never a result, a prompt or a charge. Fetch the object with your API key: data.id is the id that GET /v1/videos/{id} and GET /v1/generations/{id} take. For a raw task it is the X-Generation-Id that the create answered.

{
  "id": "evt_0194f2c4-7a1e-7b3c-9d02-5f6a1c0e8b21",
  "object": "event",
  "type": "video.completed",
  "created_at": 1761300000,
  "data": { "id": "0194f2c4-7a1e-7b3c-9d02-5f6a1c0e8b21" }
}

Headers and verification

Each delivery is a POST with content-type: application/json and these headers:

• webhook-id: the event id. It is the same on every retry, so use it to de-duplicate.
• webhook-timestamp: Unix seconds.
• webhook-signature: v1, and the base64 HMAC-SHA256 of id.timestamp.body, keyed with the endpoint’s secret.

The signing secret starts with whsec_. It is shown once, when you create the endpoint and when you rotate it. Verify the raw request body, before you parse it:

// Node, with the OpenAI SDK
const event = client.webhooks.unwrap(rawBody, req.headers, process.env.HYPEROUTER_WEBHOOK_SECRET);
if (event.type === "video.completed") {
  const video = await client.videos.retrieve(event.data.id);
}

unwrap throws when the signature does not verify; answer such a request with an error status. The follow-up call uses the same base URL as the rest of this API.

Endpoints, retries and limits

• An endpoint must be https on port 443 (or no port) and a host name, not an IP address. The host must resolve to a public address; Hyperouter checks again when it connects. Redirects are not followed.
• An account has at most 10 endpoints. Each endpoint picks the event types it wants.
• A 2xx within 10 seconds is success. Anything else is retried after about 5 seconds, 1 minute, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours and 10 hours, then the delivery is marked failed.
• An endpoint whose deliveries all fail for 3 days is disabled, and the dashboard says why. Enable it again after you fix the receiver.
• The dashboard lists each endpoint’s deliveries with status, attempts, last HTTP status and last error. It has Resend (same event id) and Send test event, which delivers a webhook.test event whose data.id is the endpoint’s id.

MCP server

An SI assistant can work with your Hyperouter account through the Model Context Protocol (MCP). The server manages the dashboard: API keys, activity, credits, tickets, webhooks and the model list. It does not run models. Model calls still go to /v1 with an API key.

The server speaks Streamable HTTP and JSON-RPC 2.0. It supports MCP revisions 2025-11-25 and 2025-06-18. It is stateless: there are no sessions, and GET /mcp answers 405.

Access tokens

An MCP client authenticates with a dashboard access token, not with an API key.

• Create a token in the dashboard. Give it a name, a scope and, optionally, an expiry.
• A token starts with hr_dt_. It is shown once. Hyperouter stores only a hash of it.
• An account user can hold at most 25 unexpired, unrevoked tokens. Revoke a token in the dashboard to stop it at once.
• A token does not work on /v1, and an API key does not work on /mcp.
• A token acts as the user who created it, with that user's permissions. The permissions are checked on every message, so a role change applies on the next call.

Send the token as a bearer token:

Authorization: Bearer hr_dt_...

Protocol

A notification, or a response to the server, answers 202 with no body. A JSON-RPC batch is refused with error -32600. A message must not exceed 1 MiB. An unknown MCP-Protocol-Version header answers 400. A browser request must come from https://dash.hyperouter.app; a client that sends no Origin header is not affected.

curl https://api.hyperouter.app/mcp \
  -H "Authorization: Bearer $HYPEROUTER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

Tools

tools/list returns the current tool set. Each tool maps to one dashboard route and carries a JSON Schema for its arguments. The tools cover:

• Account and keys: get_me, list_api_keys, create_api_key, update_api_key.
• Activity and credits: list_activity, get_activity, get_activity_summary, get_credits, get_topup_fee.
• Tickets: list_tickets, create_ticket, get_ticket, reply_to_ticket, close_ticket.
• Webhooks: list_webhooks, create_webhook, update_webhook, rotate_webhook_secret, delete_webhook, list_webhook_deliveries, resend_webhook_delivery, send_test_webhook.
• Models: list_models.
• Staff tools, with the admin_ prefix, appear only for users who hold the staff permission.

A tool answers with one text content item that holds the JSON body of the route. When the route fails, the result has isError: true and the text <message> (<code>, HTTP <status>). An unknown tool, or one that your token cannot see, is JSON-RPC error -32602.

Approvals

A sensitive write, such as crediting an account, is not run at once. The tool does not execute it. It answers with status set to approval_required and an approval_url on the dashboard. The user opens the link, confirms with a second factor and approves the action. An approval expires after 24 hours. The user can also reject it.

Billing & limits

• Requests are paid from a prepaid USD balance, billed at the list price of the provider that served them, with no markup.
• Hold, then settle. Before a request runs, Hyperouter holds the most it can cost: your input plus max_tokens for chat, the requested count for images and the seconds for video. When it finishes you are charged for what was used and the rest of the hold is released. The balance never goes negative.
• A failed request, or a failed image or video job, costs nothing. A fallback attempt that fails costs nothing.
• Every response carries its charge as usage.cost, a JSON number of USD: on chat, on images, on a settled video, and in GET /v1/generations/{id}. The dashboard shows every request and your spend by day, model and key.
• Amounts are exact: money is counted in billionths of a dollar and never rounded through a float. Prices in GET /v1/models are decimal strings.
• Top-ups are manual for now. Open a top-up request in the dashboard with the amount, the payment reference and a screenshot of the payment. Staff check the payment and credit your balance, and reply in the same ticket.
• Top-up fee. Each top-up carries a fee of 5.5% of the amount paid, with a minimum of $0.80, deducted when the top-up is credited: a $100 payment credits $94.50, and a $10 payment credits $9.20. The fee in force is shown on the Credits page before you request a top-up, and each top-up in your history shows the amount paid and the fee. Requests themselves carry no fee.

Rate limits

Each account has a limit on requests per minute and on requests in flight at once. Both count every API key of the account together, and apply to every request that starts work: chat completions, image and video creates, and raw creates. Reading a result (GET /v1/generations/{id}, GET /v1/videos…, a raw task poll) does not count; raw polls have their own count, per provider, with the same requests-per-minute limit.

Your tier follows the total you have topped up, before the top-up fee:

Your current limits are on the Credits page. These are the defaults; staff can change them for the platform or for one account, and a change applies within a minute.

Over either limit, the request is refused before anything is held or forwarded, with 429, type: rate_limit_error, code: rate_limited and a Retry-After header in seconds. The message names the limit you reached. A request counts toward the minute even when it is refused. A request in flight, a stream included, counts until it ends.

As a guard against key guessing, Hyperouter counts failed API key checks per client address. More than 30 in a minute blocks that address from every /v1 route for 15 minutes: 429, rate_limit_error, too_many_auth_failures, with Retry-After. A valid key does not lift the block.

Support

Open a ticket in the dashboard for billing, top-ups and API questions; staff reply in the same thread. You can also write to [email protected]. Please include the id from the response when you report a specific request.