Hyperouter API

Version v1 · Mis à jour le 25 octobre 2026

Hyperouter est une API HTTP unique devant de nombreux éditeurs de modèles. Vous envoyez une requête qui nomme un modèle. Hyperouter choisit un fournisseur capable de la servir, lui transmet la requête et débite votre solde au tarif public de ce fournisseur.

Chaque endpoint suit les formats de requête et de réponse d’OpenAI. Les OpenAI SDK fonctionnent dès que vous changez l’URL de base et la clé API. Hyperouter ajoute quelques champs aux corps d’OpenAI. Ils sont signalés comme ajouts dans cette référence.

Démarrage rapide

1. Connectez-vous et créez une clé API. Les clés commencent par sk-hr-v1- et ne sont affichées qu’une seule fois.
2. Stockez-la dans une variable d’environnement, par exemple HYPEROUTER_API_KEY.
3. Ajoutez des crédits : ouvrez une demande de recharge dans le tableau de bord. Notre équipe crédite votre solde une fois le paiement confirmé.
4. Pointez n’importe quel OpenAI SDK vers l’URL de base ci-dessus et choisissez un modèle.

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)

Authentification

Envoyez votre clé API comme bearer token dans chaque requête.

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

Les clés donnent accès à votre solde. Gardez-les côté serveur. Ne les mettez jamais dans du code navigateur ou mobile. Hyperouter ne stocke que le hash de chaque clé : une clé perdue ne peut donc pas être affichée de nouveau, il faut en créer une nouvelle.

Dans le tableau de bord, vous pouvez nommer chaque clé, lui fixer une limite de crédit et la désactiver. Une clé désactivée cesse de fonctionner immédiatement. Une requête qui ferait dépasser sa limite à une clé est refusée avec 402 insufficient_credits.

Erreurs d’authentification

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 } }

Erreurs

Chaque erreur utilise l’objet d’erreur d’OpenAI et un statut HTTP correspondant.

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

Types et statuts

Hyperouter ne répond jamais 502 ni 504 : ils vous parviendraient sous forme de page brute de notre réseau en périphérie, sans le corps d’erreur. Là où une passerelle répondrait ces statuts, vous recevez 503 avec le corps ci-dessous et le statut de la passerelle dans X-Upstream-Status.

Codes possibles

Nouvelles tentatives et idempotence

Une erreur réseau ou un délai dépassé ne vous dit pas si Hyperouter a reçu la requête. Si vous la renvoyez, vous pouvez démarrer une seconde tâche et payer deux fois. Une Idempotency-Key rend la répétition sûre : Hyperouter reconnaît la répétition, ne démarre pas de seconde tâche, ne bloque pas de second montant, et répond à partir de la première requête.

Envoyez-en une sur chaque requête qui coûte de l’argent. Générez une nouvelle valeur aléatoire, par exemple un UUID v4, pour chaque nouvelle requête. Conservez-la avec la requête et envoyez la même valeur chaque fois que vous renvoyez cette requête.

Envoyer une clé

L’en-tête est accepté sur ces endpoints :

Les OpenAI SDK n’envoient pas cet en-tête d’eux-mêmes. Passez-le comme en-tête supplémentaire ; les SDK le renvoient alors inchangé lors de leurs nouvelles tentatives automatiques.

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 } },
);

Ce que renvoie une répétition

Règles

• Portée. Une clé appartient à la clé API qui l’a envoyée. Deux clés API peuvent utiliser la même valeur sans s’influencer.
• Fenêtre. Une clé est honorée pendant 30 minutes après la première requête. Réessayez dans ce délai.
• Même requête. Deux requêtes sont identiques lorsque la méthode, le chemin et le corps correspondent. Le JSON est comparé après analyse : l’ordre des champs et les espaces n’ont pas d’importance. Une image ou une vidéo est une URL dans le corps : c’est l’URL qui est comparée, jamais les octets qu’elle sert.
• Facturation. Une requête effectuée sous une clé est facturée au plus une fois, quel que soit le nombre de répétitions. Une répétition servie à partir de la première requête ne coûte rien.
• Garantie. Une clé ne démarre jamais plus d’une tâche, y compris lorsque deux répétitions arrivent en même temps.

Chat completions

Les réponses de chat ne sont pas rejouées. Une répétition avec la même clé répond 409 avec le code idempotency_key_replayed, et error.generation_id est l’id de la première requête. La requête n’est ni réexécutée ni refacturée. Retrouvez la première requête avec GET /v1/generations/{id} pour voir son statut, sa consommation et son coût. Si la première chat completion a échoué et n’a pas été facturée, sa clé est libérée et une répétition s’exécute comme une nouvelle requête.

{
  "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"
  }
}

Nouvelles tentatives automatiques dans les OpenAI SDK

Les OpenAI SDK réessaient deux fois par défaut une réponse 408, 409, 429 ou 5xx, sauf si la réponse porte l’en-tête x-should-retry: false. Hyperouter envoie x-should-retry: false sur toute réponse pour laquelle une nouvelle tentative démarrerait une seconde tâche ou un second débit :

• le 503 timeout d’une image synchrone, dont la tâche continue et est facturée si elle réussit ; interrogez GET /v1/generations/{id} avec son generation_id ;
• un 500 après la création de la tâche, par exemple lorsqu’une image terminée ne peut pas être relue ;
• 409 idempotency_key_reused et idempotency_key_replayed, qu’une nouvelle tentative ne peut pas changer.

Il ne l’envoie jamais sur un 429, sur un 409 idempotency_key_in_use, ni sur un 5xx survenu avant l’existence de toute tâche. Dans ces cas, réessayer est sans risque. Avec une Idempotency-Key, chaque nouvelle tentative est sûre.

Modèles

Liste tous les modèles que votre compte peut appeler à l’instant, avec leurs prix et ce qu’ils prennent en charge. Un modèle sans fournisseur activé n’est pas listé. Certains modèles exigent un accès accordé à votre compte : ils sont listés dès qu’il l’est. Cet endpoint exige une clé API et liste les modèles que le compte de cette clé peut appeler. La réponse peut être mise en cache pendant 60 secondes, par votre client uniquement.

Paramètres

Aucun.

Réponse

{
  "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"

Erreurs

Aucune propre à cet endpoint.

Modèles de chat

Prix par million de tokens : entrée / entrée en cache / sortie.

Sur les modèles x-ai/, une requête de 200 000 tokens de prompt ou plus est facturée intégralement aux tarifs de long contexte, qui sont le double de ceux-ci. Les modèles deepseek/ ont un seul tarif quelle que soit la longueur du prompt, raisonnent avant de répondre par défaut (reasoning_effort: "none" le désactive), et comptent leur raisonnement dans max_tokens, au plus 384 000. z-ai/glm-5.3 raisonne toujours : reasoning_effort vaut low, high ou max, et none est refusé. Les modèles openai/ raisonnent aussi et acceptent des prompts de 272 000 tokens au plus.

Chat completions

Crée une réponse de modèle pour une conversation. Le corps est la requête Chat Completions d’OpenAI. Hyperouter ajoute models, provider et moderation.

Paramètres

Les autres champs sont ignorés. supported_parameters de chaque modèle dans GET /v1/models liste exactement ce qu’il accepte. Grok 4.20 et les versions plus récentes ignorent logprobs et top_logprobs, qui ne sont donc pas listés.

L’objet provider

Par défaut, Hyperouter envoie chaque requête de chat au fournisseur en bonne santé dont le prix est le plus bas pour ce modèle, et départage les égalités par le plus court temps récent jusqu’au premier token. Un fournisseur qui renvoie des erreurs à répétition est ignoré jusqu’à son rétablissement. L’objet provider suit le format de requête d’OpenRouter.

Réponse

La chat completion d’OpenAI. L’id est l’id de la requête : retrouvez-la avec GET /v1/generations/{id}. Hyperouter ajoute provider (le nom public du fournisseur qui a exécuté la requête, par exemple xAI) et usage.cost (le coût, en USD, sous forme de nombre JSON).

{
  "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
  }
}

Un modèle de réécriture de prompt répond avec un seul choix, un usage de zéro token et un cost fixe par requête.

Streaming

Avec "stream": true, la réponse est un flux de server-sent events au format de chunk d’OpenAI. Il se termine par data: [DONE]. Lorsque vous définissez stream_options.include_usage, le dernier chunk avant [DONE] a un tableau choices vide, un objet usage qui inclut cost, et un champ provider. La consommation est toujours collectée pour la facturation, que vous demandiez ou non ce chunk.

Tant que le premier token n’est pas arrivé, le flux envoie la ligne de commentaire : processing toutes les 15 secondes pour garder la connexion ouverte. Les clients SSE ignorent les commentaires.

Le repli vers un autre fournisseur n’a lieu qu’avant l’envoi du premier token. Si un fournisseur échoue en cours de flux, le flux se termine par data: {"error": {...}} suivi de data: [DONE], et vous êtes facturé pour les tokens déjà produits.

Vous êtes facturé pour les tokens que le fournisseur produit, que vous les lisiez ou non. Un flux que vous interrompez, ou une réponse que vous cessez d’attendre, n’est pas arrêté chez le fournisseur, qui continue et facture sa réponse entière : Hyperouter la lit jusqu’au bout (pendant 5 minutes au plus) et la facture.

Un fournisseur qui a accepté une requête peut être en train de l’exécuter. S’il cesse ensuite de répondre (5 minutes sans token sur un flux, ou plus longtemps que ne prend une réponse de max_tokens) ou si sa réponse s’interrompt avant le premier token, la requête n’est pas envoyée à un autre fournisseur : elle répond 503 avec le code timeout ou upstream_error et error.generation_id, et est facturée sur son montant bloqué, avec usage_estimated: true sur son enregistrement.

Exemple

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" }]
  }'

Erreurs

Images

Les deux suivent l’Images API d’OpenAI et prennent un corps JSON. /v1/images/edits prend la forme JSON d’OpenAI : les images sont images, de 1 à 5 URL https. Le images.edit des OpenAI SDK envoie les fichiers d’image en multipart/form-data, et cela fonctionne aussi : l’edge d’Hyperouter conserve chaque fichier (PNG, JPEG ou WebP, 20 MiB chacun, 50 MiB par requête) pendant 3 jours à une URL https://api.hyperouter.app/u/... impossible à deviner, que le fournisseur récupère, puis exécute la requête comme du JSON. Un fichier vidéo est refusé (400 invalid_video) : envoyez une vidéo sous forme d’URL https. Les deux acceptent les fonctionnalités communes ci-dessous et tous les paramètres propres au modèle comme champs de premier niveau.

Paramètres

Une fonctionnalité commune que le modèle ne liste pas, comme seed sur un modèle qui ne l’a pas, est refusée avec 400 unsupported_parameter. Elle n’est jamais ignorée en silence, car cela changerait la sortie et le prix.

Réponse

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

Hyperouter stocke chaque résultat pendant 30 jours, de sorte qu’un lien ne pointe jamais vers un éditeur. Au-delà de 30 jours, l’enregistrement subsiste mais son outputs est vide.

Attendre le résultat

• Sur un modèle dont les response_modes incluent sync, la requête attend l’image jusqu’à 90 secondes et répond avec son véritable statut : 200 avec les images, ou l’erreur. Les erreurs de validation, de solde et de capacité passent en premier, avec leur propre statut.
• Une image qui n’est pas prête au bout de 90 secondes répond 503 avec le code timeout et l’en-tête de réponse x-should-retry: false, de sorte que les OpenAI SDK ne la réessaient pas et ne démarrent pas une seconde image. La tâche continue, et l’erreur porte son id dans generation_id : interrogez GET /v1/generations/{id} pour obtenir le résultat. Vous n’êtes facturé que si elle réussit. Pour réessayer vous-même en toute sécurité, envoyez une Idempotency-Key : une nouvelle tentative avec la même clé attend la même tâche.
• Un modèle dont les response_modes ne contiennent que async exige Prefer: respond-async. Sans cet en-tête, la réponse est 400 avec le code async_required.

• Pour éviter une connexion maintenue sur tout modèle qui liste async, envoyez Prefer: respond-async (RFC 7240). L’en-tête peut être répété et porter d’autres préférences, par exemple Prefer: wait=10, respond-async. Vous recevez aussitôt 202 avec l’en-tête de réponse Preference-Applied: respond-async :

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

  Interrogez GET /v1/generations/{id}, ou recevez un webhook image.completed ou image.failed. Les webhooks ne se déclenchent pour les images que pour les tâches envoyées avec cet en-tête.

Exemples

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"}]}'

Erreurs

Le message d’une tâche échouée se termine par la raison donnée par le fournisseur, s’il en a donné une, après Provider:, afin de distinguer un prompt refusé, un fournisseur saturé et une panne. Les URL qu’elle contient sont remplacées par <url>.

Modèles d’image

Certains modèles exigent un accès accordé à votre compte. La référence des modèles du tableau de bord liste tous les modèles que votre compte peut appeler, avec leurs paramètres, leurs prix et leurs notes.

Vidéos

La vidéo suit la Videos API d’OpenAI. Une vidéo est une tâche. Un appel de création, de modification, de prolongation ou de remix répond aussitôt 200 avec l’objet Video au statut queued. Vous interrogez GET /v1/videos/{id} jusqu’à ce que le statut soit completed, ou vous recevez un webhook. Prefer ne change rien ici : les vidéos sont toujours asynchrones.

Créer une vidéo

Le corps est du JSON, sur tous les endpoints vidéo ; le videos.create des OpenAI SDK avec un fichier d’image input_reference est aussi accepté, le fichier étant traité comme pour les modifications d’images. Chaque image et chaque vidéo est une URL https vers un hôte public, transmise telle quelle au fournisseur : il doit pouvoir la récupérer, et une URL qu’il ne peut pas récupérer ou lire fait échouer la vidéo avec vendor_rejected, sans aucun débit. Une URL data:, une URL http://, une adresse IP ou un nom interne est refusé avec 400 invalid_image ou 400 invalid_video. Un corps multipart/form-data est refusé avec 400 unsupported_content_type.

Modifier, prolonger et remixer

La vidéo source doit être terminée. Une vidéo donnée par URL est une URL https, transmise telle quelle au fournisseur, comme une image. Si vous donnez une vidéo par URL, seconds est requis sur les modèles qui n’ont pas de maximum fixe.

Lister, lire, télécharger, supprimer

L’objet Video

{
  "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 }
}

Une vidéo est facturée sur les secondes que vous demandez. Le montant est bloqué à l’avance, puis libéré intégralement si la tâche échoue.

Exemple : x-ai/grok-imagine-video

Le modèle x-ai/grok-imagine-video produit une vidéo à partir d’un prompt, avec une image de départ facultative. seconds va de 1 à 15. Prix : $0.050 par seconde.

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
}

Cette tâche est facturée 8 × $0.050 = $0.40, de sorte que l’objet réglé affiche "usage": {"cost": 0.4, "seconds": 8}.

Erreurs

Modèles vidéo

La référence des modèles du tableau de bord liste tous les modèles vidéo que votre compte peut appeler.

Generations

Renvoie l’enregistrement de l’une de vos requêtes, de n’importe quel type : son statut, sa consommation, son coût, ses durées et, pour les images et les vidéos, des liens signés vers les sorties. Utilisez-le pour interroger une requête d’image envoyée avec Prefer: respond-async et pour rapprocher vos dépenses. Le texte des prompts et des completions ne figure jamais dans l’enregistrement. Hyperouter les conserve chiffrés pendant 180 jours uniquement pour respecter ses obligations légales, et aucune API ni page du tableau de bord ne les renvoie (Politique de confidentialité).

Paramètres

Réponse

{
  "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"

Erreurs

Paramètres propres à chaque modèle

Certains modèles ont des champs que d’autres n’ont pas. Ce sont les paramètres supplémentaires. Vous les envoyez comme champs de premier niveau du corps de la requête, comme n’importe quel autre champ. Tous les OpenAI SDK peuvent les envoyer (extra_body en Python, propriétés supplémentaires en JavaScript).

GET /v1/models liste les paramètres supplémentaires de chaque modèle dans extra_parameters. Chaque entrée comporte :

La référence des modèles du tableau de bord décrit les paramètres supplémentaires de chaque modèle que votre compte peut appeler.

Règles

• Un paramètre connu que le modèle n’a pas est refusé : 400 invalid_request_error avec le code unsupported_parameter, param défini sur le nom du champ (par exemple loras) et le message This model does not support "loras". Un paramètre est connu lorsqu’un modèle du catalogue le déclare. La même règle s’applique aux fonctionnalités communes (resolution, ratio, audio, seed, negative_prompt, first_frame, last_frame, reference_images, reference_videos, prompt_extend). Rien n’est ignoré en silence, car cela changerait la sortie et le prix.
• Une valeur du mauvais type est refusée avec 400 invalid_body, param défini sur le nom et un message tel que loras must be of type array.
• Une valeur hors de values est refusée avec 400 invalid_body et le message <name> must be one of [...].
• Un champ qu’aucun modèle ne déclare est ignoré, comme l’API d’OpenAI ignore les champs inconnus.
• Chaque modèle vérifie ses paramètres selon son propre schéma : valeurs autorisées, minimum et maximum, champs requis et longueurs de listes. Une valeur hors schéma répond 400 invalid_body avec param désignant le champ, par exemple seconds must be one of 5, 8.
• Une combinaison qu’un éditeur n’autorise pas, comme des médias de référence avec des images clés, répond 400 invalid_combination avec la raison. Les vérifications s’exécutent avant tout débit.
• Les champs qui modifient le prix, comme resolution et audio, sont inclus dans le montant bloqué à l’avance, qui est donc exact.

Fonctionnalités communes

Ces champs portent le même nom sur tous les modèles qui les ont. Un modèle liste ceux qu’il accepte dans supported_parameters.

Expansion du prompt

Avec "prompt_expand": true, Hyperouter réécrit votre prompt pour le modèle avant le rendu : une description plus complète pour une image, un script seconde par seconde pour une vidéo. Elle est désactivée par défaut : le prompt part tel quel. Seul un modèle dont supported_parameters liste prompt_expand l’accepte, et uniquement pour créer une image ou une vidéo ; sur tout autre modèle, et pour une modification, une extension ou un remix de vidéo, elle est refusée avec 400 unsupported_parameter. Elle ne peut pas non plus être combinée avec prompt_extend: true (400 invalid_body).

L’expansion du prompt est disponible pour un compte une fois que Hyperouter l’a activée ; ouvrez un ticket de support pour en demander l’accès. D’ici là, GET /v1/models ne liste prompt_expand pour aucun modèle, et une requête avec prompt_expand: true sur un modèle qui le propose répond 403 permission_error, code feature_not_enabled, param prompt_expand, sans rien réserver ni envoyer au fournisseur.

• Ce qui a servi au rendu. La réponse image, l’objet vidéo et GET /v1/generations/{id} contiennent expanded_prompt, le prompt reçu par le modèle. Il est conservé 30 jours après la requête, puis renvoyé à null. prompt reste votre propre texte.
• Modèle rédacteur. prompt_expand_model désigne le modèle de chat qui écrit la réécriture ; par défaut, x-ai/grok-4.6. Il n’est valide qu’avec prompt_expand: true (sinon 400 invalid_body). Un modèle inexistant ou qui n’est pas un modèle de chat donne 400 unknown_model, et un modèle que votre compte ne peut pas appeler donne 403 model_not_enabled, tous deux avant tout blocage. Un rédacteur qui lit les images reçoit celles de la requête ; sinon il écrit à partir du texte seul.
• Prix. La réécriture est facturée sur la même requête, aux prix par token du modèle qui l’a écrite (prompt_expand_model, sinon x-ai/grok-4.6) pour les tokens utilisés, et son montant maximal est bloqué d’avance avec le rendu. La référence des modèles détaille chaque modèle.
• Quand elle ne s’exécute pas. Si la réécriture échoue, expire ou ne peut pas être utilisée, le rendu se fait avec votre prompt tel quel, expanded_prompt vaut null et rien n’est facturé.
• Langue. Les répliques d’une vidéo suivent locale (sinon l’anglais) lorsque le modèle parle cette langue.

La réécriture comme modèle de chat

Un compte doté de l’expansion du prompt dispose aussi d’un modèle de chat qui renvoie la réécriture au lieu de la rendre ; votre référence des modèles le nomme. Appelez-le sur POST /v1/chat/completions avec exactement un message user : son texte est le prompt, et ses parties image_url (URL https, 5 au plus) sont les images ; une URL data: ou http:// renvoie 400 invalid_image avec param valant messages. target_model est obligatoire : un modèle qui liste prompt_expand. seconds, locale et negative_prompt sont facultatifs. Une cible vidéo accompagnée d’une image est écrite à partir de cette première image. Il ne diffuse pas en streaming (stream: true renvoie 400 unsupported_parameter), et tout autre message, message system compris, renvoie 400 invalid_body.

Ce modèle de chat utilise toujours x-ai/grok-4.6 ; il n’accepte pas prompt_expand_model. choices[0].message.content est une chaîne JSON, {"prompt": "...", "negative_prompt": "..."}, plus "beats" (une ligne par seconde) pour une cible vidéo. Il est facturé aux prix par token de x-ai/grok-4.6, indiqués dans usage. Un prompt qui demande les instructions du modèle renvoie 400 prompt_rejected ; une réécriture refusée ou vide renvoie 422 expansion_refused, et une réécriture en échec 503 upstream_error. Aucun de ces cas n’est facturé.

Modération

Le champ moderation est celui d’OpenAI. Il fonctionne sur /v1/chat/completions, /v1/images/generations, /v1/images/edits et /v1/videos avec ses appels de modification, de prolongation et de remix.

Toute autre valeur est refusée : 400 invalid_request_error, code invalid_body, param moderation, message moderation must be auto or low.

low est disponible pour un compte une fois qu’Hyperouter l’a activé ; ouvrez un ticket de support pour le demander. D’ici là, une requête avec low répond 403 permission_error, code moderation_not_enabled, param moderation, et n’est pas envoyée au fournisseur.

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

La réponse n’indique pas si la désactivation a été utilisée. Les politiques des Conditions d’utilisation continuent de s’appliquer. Une requête que le filtre de l’éditeur refuse échoue avec 400 content_rejected et n’est pas facturée.

Webhooks

Au lieu d’interroger, un de vos endpoints peut recevoir une requête lorsqu’une tâche se termine. Ajoutez des endpoints dans le tableau de bord. Le format est celui des webhooks d’OpenAI, signé selon le schéma Standard Webhooks, de sorte que les OpenAI SDK les vérifient.

Le payload porte un id, jamais un résultat, un prompt ou un coût. Récupérez l’objet avec votre clé API : data.id est l’id que prennent GET /v1/videos/{id} et GET /v1/generations/{id}. Pour une tâche brute, c’est le X-Generation-Id renvoyé par la création.

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

En-têtes et vérification

Chaque livraison est un POST avec content-type: application/json et ces en-têtes :

• webhook-id : l’id de l’événement. Il est identique à chaque nouvelle tentative : utilisez-le pour dédupliquer.
• webhook-timestamp : secondes Unix.
• webhook-signature : v1, suivi du HMAC-SHA256 en base64 de id.timestamp.body, avec le secret de l’endpoint comme clé.

Le secret de signature commence par whsec_. Il n’est affiché qu’une fois, à la création de l’endpoint et lors de sa rotation. Vérifiez le corps brut de la requête, avant de l’analyser :

// 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 lève une exception lorsque la signature ne se vérifie pas ; répondez à une telle requête par un statut d’erreur. L’appel suivant utilise la même URL de base que le reste de cette API.

Endpoints, nouvelles tentatives et limites

• Un endpoint doit être en https sur le port 443 (ou sans port) et un nom d’hôte, pas une adresse IP. L’hôte doit se résoudre en une adresse publique ; Hyperouter vérifie à nouveau lors de la connexion. Les redirections ne sont pas suivies.
• Un compte a au plus 10 endpoints. Chaque endpoint choisit les types d’événements qu’il souhaite.
• Un 2xx en moins de 10 secondes est un succès. Tout le reste est retenté après environ 5 secondes, 1 minute, 5 minutes, 30 minutes, 2 heures, 5 heures, 10 heures et 10 heures, puis la livraison est marquée comme échouée.
• Un endpoint dont toutes les livraisons échouent pendant 3 jours est désactivé, et le tableau de bord en indique la raison. Réactivez-le après avoir corrigé le récepteur.
• Le tableau de bord liste les livraisons de chaque endpoint avec leur statut, le nombre de tentatives, le dernier statut HTTP et la dernière erreur. Il propose Renvoyer (même id d’événement) et Envoyer un événement de test, qui livre un événement webhook.test dont data.id est l’id de l’endpoint.

Serveur MCP

Un assistant IA peut travailler avec votre compte Hyperouter via le Model Context Protocol (MCP). Le serveur gère le tableau de bord : clés API, activité, crédits, tickets, webhooks et liste des modèles. Il n’exécute pas de modèles. Les appels aux modèles continuent d’aller vers /v1 avec une clé API.

Le serveur parle Streamable HTTP et JSON-RPC 2.0. Il prend en charge les révisions MCP 2025-11-25 et 2025-06-18. Il est sans état : il n’y a pas de sessions, et GET /mcp répond 405.

Jetons d’accès

Un client MCP s’authentifie avec un jeton d’accès du tableau de bord, pas avec une clé API.

• Créez un jeton dans le tableau de bord. Donnez-lui un nom, une portée et, facultativement, une expiration.
• Un jeton commence par hr_dt_. Il n’est affiché qu’une fois. Hyperouter n’en stocke que le hash.
• Un utilisateur du compte peut détenir au plus 25 jetons non expirés et non révoqués. Révoquez un jeton dans le tableau de bord pour l’arrêter immédiatement.
• Un jeton ne fonctionne pas sur /v1, et une clé API ne fonctionne pas sur /mcp.
• Un jeton agit comme l’utilisateur qui l’a créé, avec les permissions de cet utilisateur. Les permissions sont vérifiées à chaque message : un changement de rôle s’applique donc dès l’appel suivant.

Envoyez le jeton comme bearer token :

Authorization: Bearer hr_dt_...

Protocole

Une notification, ou une réponse adressée au serveur, répond 202 sans corps. Un lot JSON-RPC est refusé avec l’erreur -32600. Un message ne doit pas dépasser 1 MiB. Un en-tête MCP-Protocol-Version inconnu répond 400. Une requête de navigateur doit provenir de https://dash.hyperouter.app ; un client qui n’envoie pas d’en-tête Origin n’est pas concerné.

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"}'

Outils

tools/list renvoie l’ensemble actuel des outils. Chaque outil correspond à une route du tableau de bord et porte un JSON Schema pour ses arguments. Les outils couvrent :

• Compte et clés : get_me, list_api_keys, create_api_key, update_api_key.
• Activité et crédits : 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.
• Modèles : list_models.
• Les outils du personnel, avec le préfixe admin_, n’apparaissent que pour les utilisateurs qui détiennent la permission du personnel.

Un outil répond avec un seul élément de contenu texte qui contient le corps JSON de la route. Lorsque la route échoue, le résultat porte isError: true et le texte <message> (<code>, HTTP <status>). Un outil inconnu, ou que votre jeton ne peut pas voir, donne l’erreur JSON-RPC -32602.

Approbations

Une écriture sensible, comme créditer un compte, n’est pas exécutée immédiatement. L’outil ne l’exécute pas. Il répond avec status défini sur approval_required et une approval_url sur le tableau de bord. L’utilisateur ouvre le lien, confirme avec un second facteur et approuve l’action. Une approbation expire au bout de 24 heures. L’utilisateur peut aussi la rejeter.

Facturation et limites

• Les requêtes sont payées sur un solde prépayé en USD, facturées au tarif public du fournisseur qui les a servies, sans aucune majoration.
• Bloquer, puis régler. Avant l’exécution d’une requête, Hyperouter bloque le maximum qu’elle peut coûter : votre entrée plus max_tokens pour le chat, le nombre demandé pour les images et les secondes pour la vidéo. À la fin, vous êtes débité de ce qui a été utilisé et le reste du montant bloqué est libéré. Le solde ne devient jamais négatif.
• Une requête échouée, ou une tâche d’image ou de vidéo échouée, ne coûte rien. Une tentative de repli qui échoue ne coûte rien.
• Chaque réponse porte son coût dans usage.cost, un nombre JSON en USD : sur le chat, sur les images, sur une vidéo réglée, et dans GET /v1/generations/{id}. Le tableau de bord affiche chaque requête et vos dépenses par jour, par modèle et par clé.
• Les montants sont exacts : l’argent est compté en milliardièmes de dollar et jamais arrondi via un flottant. Les prix de GET /v1/models sont des chaînes décimales.
• Les recharges sont manuelles pour l’instant. Ouvrez une demande de recharge dans le tableau de bord avec le montant, la référence du paiement et une capture d’écran du paiement. Notre équipe vérifie le paiement, crédite votre solde et répond dans le même ticket.
• Frais de recharge. Chaque recharge supporte des frais de 5,5 % du montant payé, avec un minimum de 0,80 $, déduits lorsque la recharge est créditée : un paiement de 100 $ crédite 94,50 $, et un paiement de 10 $ crédite 9,20 $. Les frais en vigueur sont affichés sur la page Crédits avant que vous ne demandiez une recharge, et chaque recharge de votre historique indique le montant payé et les frais. Les requêtes elles-mêmes ne supportent aucuns frais.

Limites de débit

Chaque compte a une limite de requêtes par minute et de requêtes en cours simultanément. Les deux comptent ensemble toutes les clés API du compte, et s’appliquent à chaque requête qui démarre un travail : chat completions, créations d’images et de vidéos, et créations brutes. Lire un résultat (GET /v1/generations/{id}, GET /v1/videos…, une interrogation de tâche brute) ne compte pas ; les interrogations brutes sont comptées à part, par fournisseur, avec la même limite de requêtes par minute.

Votre palier dépend du total que vous avez rechargé, avant déduction des frais de recharge :

Vos limites actuelles figurent sur la page Crédits. Ce sont les valeurs par défaut ; notre équipe peut les modifier pour la plateforme ou pour un compte, et un changement s’applique en moins d’une minute.

Au-delà de l’une ou l’autre limite, la requête est refusée avant que quoi que ce soit ne soit bloqué ou transmis, avec 429, type: rate_limit_error, code: rate_limited et un en-tête Retry-After en secondes. Le message nomme la limite atteinte. Une requête compte pour la minute même lorsqu’elle est refusée. Une requête en cours, flux compris, compte jusqu’à sa fin.

Pour se protéger contre la devinette de clés, Hyperouter compte les vérifications de clé API échouées par adresse client. Plus de 30 en une minute bloquent cette adresse sur toutes les routes /v1 pendant 15 minutes : 429, rate_limit_error, too_many_auth_failures, avec Retry-After. Une clé valide ne lève pas le blocage.

Support

Ouvrez un ticket dans le tableau de bord pour la facturation, les recharges et les questions sur l’API ; notre équipe répond dans le même fil. Vous pouvez aussi écrire à [email protected]. Veuillez indiquer l’id de la réponse lorsque vous signalez une requête précise.