Hyperouter API

Versión v1 · Actualizado el 25 de octubre de 2026

Hyperouter es una API HTTP única delante de muchos proveedores de modelos. Envías una solicitud que indica un modelo. Hyperouter elige un proveedor que pueda atenderla, le reenvía la solicitud y cobra de tu saldo el precio de lista de ese proveedor.

Todos los endpoints siguen las estructuras de solicitud y respuesta de OpenAI. Los SDK de OpenAI funcionan cuando cambias la URL base y la clave de API. Hyperouter añade algunos campos a los cuerpos de OpenAI. En esta referencia están marcados como añadidos.

Inicio rápido

1. Inicia sesión y crea una clave de API. Las claves empiezan por sk-hr-v1- y se muestran una sola vez.
2. Guárdala en una variable de entorno, por ejemplo HYPEROUTER_API_KEY.
3. Añade crédito: abre una solicitud de recarga en el panel. El equipo acredita tu saldo cuando se confirma el pago.
4. Apunta cualquier SDK de OpenAI a la URL base anterior y elige un modelo.

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)

Autenticación

Envía tu clave de API como token bearer en cada solicitud.

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

Las claves dan acceso a tu saldo. Guárdalas en tu servidor. Nunca las pongas en código de navegador ni de móvil. Hyperouter guarda solo un hash de cada clave, así que una clave perdida no se puede volver a mostrar: crea una nueva.

En el panel puedes ponerle nombre a cada clave, asignarle un límite de crédito y desactivarla. Una clave desactivada deja de funcionar al instante. Una solicitud que llevaría a una clave más allá de su límite se rechaza con 402 insufficient_credits.

Errores de autenticación

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

Errores

Todos los errores usan el objeto de error de OpenAI y un estado HTTP correspondiente.

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

Tipos y estados

Hyperouter nunca responde 502 ni 504: te llegarían como una página simple de nuestra red perimetral, sin el cuerpo del error. Donde una pasarela respondería con ellos, recibes 503 con el cuerpo de más arriba y el estado de la pasarela en X-Upstream-Status.

Códigos que puedes recibir

Reintentos e idempotencia

Un error de red o un tiempo de espera agotado no te dice si Hyperouter recibió la solicitud. Si la vuelves a enviar, puedes iniciar un segundo trabajo y pagar dos veces. Una Idempotency-Key hace segura la repetición: Hyperouter reconoce la repetición, no inicia un segundo trabajo, no hace una segunda retención y responde a partir de la primera solicitud.

Envía una en cada solicitud que cueste dinero. Genera un valor aleatorio nuevo, como un UUID v4, para cada solicitud nueva. Guárdalo junto con la solicitud y envía el mismo valor cada vez que repitas esa solicitud.

Enviar una clave

El encabezado se acepta en estos endpoints:

Los SDK de OpenAI no envían este encabezado por su cuenta. Pásalo como encabezado adicional; los SDK lo reenvían sin cambios en sus reintentos automáticos.

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

Qué devuelve una repetición

Reglas

• Ámbito. Una clave pertenece a la clave de API que la envió. Dos claves de API pueden usar el mismo valor sin afectarse entre sí.
• Ventana. Una clave se respeta durante 30 minutos después de la primera solicitud. Reintenta dentro de ese plazo.
• Misma solicitud. Dos solicitudes son la misma cuando coinciden el método, la ruta y el cuerpo. El JSON se compara después de analizarlo, así que el orden de los campos y los espacios no importan. Una imagen o un vídeo es una URL en el cuerpo, así que se compara la URL, nunca los bytes que sirve.
• Facturación. Una solicitud hecha con una clave se factura como máximo una vez, sea cual sea el número de repeticiones. Una repetición respondida a partir de la primera solicitud no cuesta nada.
• Garantía. Una clave nunca inicia más de un trabajo, tampoco cuando dos repeticiones llegan al mismo tiempo.

Chat completions

Las respuestas de chat no se reproducen. Una repetición con la misma clave responde 409 con el código idempotency_key_replayed, y error.generation_id es el id de la primera solicitud. La solicitud no se vuelve a ejecutar ni a facturar. Consulta la primera solicitud con GET /v1/generations/{id} para ver su estado, consumo y coste. Si el primer chat completion falló y no se facturó, su clave queda libre y una repetición se ejecuta como solicitud nueva.

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

Reintentos automáticos en los SDK de OpenAI

Los SDK de OpenAI reintentan dos veces, por defecto, una respuesta 408, 409, 429 o 5xx, salvo que la respuesta incluya el encabezado x-should-retry: false. Hyperouter envía x-should-retry: false en toda respuesta en la que un reintento iniciaría un segundo trabajo o un segundo cargo:

• el 503 timeout de una imagen síncrona, cuyo trabajo continúa y se factura si tiene éxito; consulta GET /v1/generations/{id} con su generation_id;
• un 500 después de crear el trabajo, por ejemplo cuando no se puede volver a leer una imagen terminada;
• 409 idempotency_key_reused e idempotency_key_replayed, que un reintento no puede cambiar.

Nunca lo envía en un 429, en un 409 idempotency_key_in_use ni en un 5xx anterior a que exista cualquier trabajo. Esos son seguros de reintentar. Con una Idempotency-Key, todos los reintentos son seguros.

Modelos

Enumera todos los modelos que tu cuenta puede llamar ahora mismo, con sus precios y lo que admiten. Un modelo sin un proveedor habilitado no aparece. Algunos modelos requieren que se conceda acceso a tu cuenta: aparecen una vez concedido. Este endpoint necesita una clave de API y enumera los modelos que puede llamar la cuenta de esa clave. La respuesta puede almacenarse en caché durante 60 segundos, solo por tu cliente.

Parámetros

Ninguno.

Respuesta

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

Errores

Ninguno específico de este endpoint.

Modelos de chat

Precios por 1 M de tokens: entrada / entrada en caché / salida.

En los modelos x-ai/, una solicitud con 200 000 tokens de prompt o más se factura por completo con las tarifas de contexto largo, que son el doble de las anteriores. Los modelos deepseek/ tienen una única tarifa para cualquier longitud de prompt, razonan antes de responder por defecto (reasoning_effort: "none" lo desactiva) y cuentan su razonamiento dentro de max_tokens, con un máximo de 384 000. z-ai/glm-5.3 siempre razona: reasoning_effort es low, high o max, y none se rechaza. Los modelos openai/ también razonan y aceptan prompts de 272 000 tokens como máximo.

Chat completions

Crea la respuesta de un modelo a una conversación. El cuerpo es la solicitud de Chat Completions de OpenAI. Hyperouter añade models, provider y moderation.

Parámetros

Los demás campos se ignoran. supported_parameters de cada modelo en GET /v1/models enumera exactamente lo que admite. Grok 4.20 y posteriores ignoran logprobs y top_logprobs, por lo que no aparecen en la lista.

El objeto provider

Por defecto, Hyperouter envía cada solicitud de chat al proveedor disponible con el precio más bajo para ese modelo, y desempata por el menor tiempo reciente hasta el primer token. Un proveedor que falla repetidamente se omite hasta que se recupera. El objeto provider sigue la estructura de solicitud de OpenRouter.

Respuesta

El chat completion de OpenAI. El id es el id de la solicitud: consúltalo con GET /v1/generations/{id}. Hyperouter añade provider (el nombre público del proveedor que atendió la solicitud, por ejemplo xAI) y usage.cost (el cargo, en USD, como número 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 modelo de reescritura de prompts responde con una opción, un usage de cero tokens y un cost fijo por solicitud.

Streaming

Con "stream": true la respuesta es un flujo de eventos enviados por el servidor en el formato de fragmentos de OpenAI. Termina con data: [DONE]. Cuando defines stream_options.include_usage, el último fragmento antes de [DONE] tiene un array choices vacío y un objeto usage que incluye cost, además de un campo provider. El consumo siempre se registra para la facturación, pidas o no el fragmento.

Hasta que llega el primer token, el stream envía la línea de comentario : processing cada 15 segundos para mantener abierta la conexión. Los clientes SSE ignoran los comentarios.

La conmutación a otro proveedor solo ocurre antes de enviar el primer token. Si un proveedor falla a mitad del stream, este termina con data: {"error": {...}} seguido de data: [DONE], y se te facturan los tokens ya producidos.

Se te facturan los tokens que produce el proveedor, los leas o no. Un stream que abortas, o una respuesta que dejas de esperar, no se detiene en el proveedor, que continúa y factura toda su respuesta: Hyperouter la lee hasta el final (durante 5 minutos más como máximo) y factura eso.

Un proveedor que ha aceptado una solicitud puede estar ejecutándola. Si luego deja de responder (5 minutos sin ningún token en un stream, o más de lo que tarda una respuesta de max_tokens) o su respuesta se corta antes del primer token, la solicitud no se envía a otro proveedor: responde 503 con el código timeout o upstream_error con error.generation_id, y se factura según su retención, con usage_estimated: true en su registro.

Ejemplo

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

Errores

Imágenes

Ambos siguen la API de imágenes de OpenAI y aceptan un cuerpo JSON. /v1/images/edits acepta la forma JSON de OpenAI: las imágenes son images, de 1 a 5 URL https. El images.edit de los SDK de OpenAI envía los archivos de imagen como multipart/form-data, y eso también funciona: el edge de Hyperouter guarda cada archivo (PNG, JPEG o WebP, 20 MiB cada uno, 50 MiB por solicitud) durante 3 días en una URL https://api.hyperouter.app/u/... imposible de adivinar que el proveedor descarga, y luego ejecuta la solicitud como JSON. Un archivo de vídeo se rechaza (400 invalid_video): envía un vídeo como URL https. Ambos aceptan las funciones compartidas que siguen y cualquier parámetro específico del modelo como campos de primer nivel.

Parámetros

Una función compartida que el modelo no lista, como seed en un modelo que no la tiene, se rechaza con 400 unsupported_parameter. Nunca se descarta en silencio, porque cambiaría la salida y el precio.

Respuesta

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

Hyperouter almacena cada resultado durante 30 días, de modo que un enlace nunca apunta a un proveedor. Pasados los 30 días el registro permanece, pero su outputs queda vacío.

Esperar el resultado

• En un modelo cuyos response_modes incluyen sync, la solicitud espera la imagen hasta 90 segundos y responde con su estado real: 200 con las imágenes, o el error. Los errores de validación, saldo y capacidad van primero, con su propio estado.
• Una imagen que no está lista tras 90 segundos responde 503 con el código timeout y el encabezado de respuesta x-should-retry: false, de modo que los SDK de OpenAI no la reintentan ni inician una segunda imagen. El trabajo continúa, y el error lleva su id como generation_id: consulta GET /v1/generations/{id} para obtener el resultado. Solo se te factura si tiene éxito. Para reintentar con seguridad por tu cuenta, envía una Idempotency-Key: un reintento con la misma clave espera al mismo trabajo.
• Un modelo cuyos response_modes son solo async necesita Prefer: respond-async. Sin él, la respuesta es 400 con el código async_required.

• Para evitar una conexión retenida en cualquier modelo que liste async, envía Prefer: respond-async (RFC 7240). El encabezado puede repetirse y puede llevar otras preferencias, por ejemplo Prefer: wait=10, respond-async. Recibes 202 de inmediato con el encabezado de respuesta Preference-Applied: respond-async:

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

  Consulta periódicamente GET /v1/generations/{id}, o recibe un webhook image.completed o image.failed. Los webhooks se disparan para imágenes solo en los trabajos que enviaste con este encabezado.

Ejemplos

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

Errores

El mensaje de un trabajo fallido termina con el motivo del propio proveedor, si lo dio, tras Provider:, para distinguir un prompt rechazado, un proveedor saturado y una caída. Las URL que contenga se sustituyen por <url>.

Modelos de imagen

Algunos modelos requieren que se conceda acceso a tu cuenta. La referencia de modelos del panel enumera todos los modelos que tu cuenta puede llamar, con sus parámetros, precios y notas.

Vídeos

El vídeo sigue la API de vídeos de OpenAI. Un vídeo es un trabajo. Una llamada de creación, edición, extensión o remix responde 200 de inmediato con el objeto Video en estado queued. Consultas GET /v1/videos/{id} hasta que el estado sea completed, o recibes un webhook. Prefer no cambia nada aquí: los vídeos son siempre asíncronos.

Crear un vídeo

El cuerpo es JSON, en todos los endpoints de vídeo; el videos.create de los SDK de OpenAI con un archivo de imagen input_reference también se acepta, y el archivo se trata como en las ediciones de imágenes. Toda imagen y todo vídeo es una URL https a un host público, que se pasa al proveedor tal cual: el proveedor debe poder descargarla, y si no puede descargarla o leerla, el vídeo falla con vendor_rejected y no se cobra nada. Una URL data:, una URL http://, una dirección IP o un nombre interno se rechaza con 400 invalid_image o 400 invalid_video. Un cuerpo multipart/form-data se rechaza con 400 unsupported_content_type.

Editar, extender y remix

El vídeo de origen debe haberse completado. Un vídeo indicado por URL es una URL https, que se pasa al proveedor tal cual, igual que una imagen. Si indicas un vídeo por URL, seconds es obligatorio en los modelos que no tienen un máximo fijo.

Listar, consultar, descargar, eliminar

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

Un vídeo se factura según los segundos que solicitas. El importe se retiene por adelantado y se libera por completo si el trabajo falla.

Ejemplo: x-ai/grok-imagine-video

El modelo x-ai/grok-imagine-video crea un vídeo a partir de un prompt, con una imagen opcional como punto de partida. seconds va de 1 a 15. Precio: $0.050 por segundo.

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
}

A este trabajo se le cobra 8 × $0.050 = $0.40, así que el objeto liquidado muestra "usage": {"cost": 0.4, "seconds": 8}.

Errores

Modelos de vídeo

La referencia de modelos del panel enumera todos los modelos de vídeo que tu cuenta puede llamar.

Generaciones

Devuelve el registro de una de tus solicitudes, de cualquier tipo: su estado, consumo, cargo, tiempos y, para imágenes y vídeos, enlaces firmados a las salidas. Úsalo para consultar periódicamente una solicitud de imagen que enviaste con Prefer: respond-async y para conciliar el gasto. El texto del prompt y de la respuesta nunca está en el registro. Hyperouter lo conserva cifrado durante 180 días solo para cumplir obligaciones legales, y ninguna API ni página del panel lo devuelve (Política de privacidad).

Parámetros

Respuesta

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

Errores

Parámetros específicos de cada modelo

Algunos modelos tienen campos que otros modelos no tienen. Son los parámetros adicionales. Los envías como campos de primer nivel del cuerpo de la solicitud, como cualquier otro campo. Cualquier SDK de OpenAI puede enviarlos (extra_body en Python, propiedades adicionales en JavaScript).

GET /v1/models enumera los parámetros adicionales de cada modelo en extra_parameters. Cada entrada tiene:

La referencia de modelos del panel describe los parámetros adicionales de cada modelo que tu cuenta puede llamar.

Reglas

• Un parámetro conocido que el modelo no tiene se rechaza: 400 invalid_request_error con el código unsupported_parameter, param con el nombre del campo (por ejemplo loras) y el mensaje This model does not support "loras". Un parámetro es conocido cuando algún modelo del catálogo lo declara. La misma regla cubre las funciones compartidas (resolution, ratio, audio, seed, negative_prompt, first_frame, last_frame, reference_images, reference_videos, prompt_extend). Nada se descarta en silencio, porque cambiaría la salida y el precio.
• Un valor de tipo incorrecto se rechaza con 400 invalid_body, param con el nombre y un mensaje como loras must be of type array.
• Un valor fuera de values se rechaza con 400 invalid_body y el mensaje <name> must be one of [...].
• Un campo que ningún modelo declara se ignora, igual que la API de OpenAI ignora los campos desconocidos.
• Cada modelo comprueba sus parámetros con su propio esquema: valores permitidos, mínimo y máximo, campos obligatorios y longitudes de lista. Un valor fuera del esquema responde 400 invalid_body con param nombrando el campo, por ejemplo seconds must be one of 5, 8.
• Una combinación que un proveedor no permite, como medios de referencia junto con fotogramas clave, responde 400 invalid_combination con el motivo. Las comprobaciones se ejecutan antes de cobrar nada.
• Los campos que cambian el precio, como resolution y audio, se valoran en la retención previa, por lo que la retención es exacta.

Funciones compartidas

Estos campos tienen el mismo nombre en todos los modelos que los tienen. Un modelo lista los que admite en supported_parameters.

Expansión del prompt

Con "prompt_expand": true, Hyperouter reescribe tu prompt para el modelo antes de generar: una descripción más completa para una imagen y un guion segundo a segundo para un vídeo. Está desactivada por defecto, así que el prompt se envía tal cual. Solo la acepta un modelo cuyo supported_parameters incluya prompt_expand, y solo para crear una imagen o un vídeo; en cualquier otro modelo, y en la edición, extensión o remezcla de un vídeo, se rechaza con 400 unsupported_parameter. Tampoco se puede combinar con prompt_extend: true (400 invalid_body).

La expansión del prompt está disponible para una cuenta cuando Hyperouter la habilita; abre un ticket de soporte para solicitar el acceso. Hasta entonces, GET /v1/models no lista prompt_expand en ningún modelo, y una solicitud con prompt_expand: true en un modelo que lo ofrece responde 403 permission_error, código feature_not_enabled, param prompt_expand, sin retener nada ni enviarlo al proveedor.

• Lo que se generó. La respuesta de imagen, el objeto de vídeo y GET /v1/generations/{id} incluyen expanded_prompt, el prompt que recibió el modelo. Se conserva 30 días tras la solicitud; después se devuelve null. prompt sigue siendo tu propio texto.
• Modelo que escribe. prompt_expand_model indica el modelo de chat que escribe la reescritura; por defecto, x-ai/grok-4.6. Solo es válido con prompt_expand: true (si no, 400 invalid_body). Un modelo que no existe o que no es de chat da 400 unknown_model, y uno que tu cuenta no puede llamar da 403 model_not_enabled, ambos antes de retener nada. Si el modelo lee imágenes, se le muestran las imágenes de la solicitud; si no, escribe solo a partir del texto.
• Precio. La reescritura se cobra en la misma solicitud, a los precios por token del modelo que la escribió (prompt_expand_model; si no, x-ai/grok-4.6) según los tokens que usó, y su importe máximo se retiene por adelantado junto con la generación. La referencia de modelos detalla cada modelo.
• Cuándo no se ejecuta. Si la reescritura falla, agota el tiempo o no se puede usar, se genera con tu prompt tal cual, se devuelve expanded_prompt: null y no cuesta nada.
• Idioma. Los diálogos de un vídeo siguen locale (si no, el inglés) cuando el modelo habla ese idioma.

La reescritura como modelo de chat

Una cuenta con expansión del prompt también tiene un modelo de chat que devuelve la reescritura en lugar de generarla; tu referencia de modelos lo nombra. Llámalo en POST /v1/chat/completions con exactamente un mensaje user: su texto es el prompt, y sus partes image_url (URL https, 5 como máximo) son las imágenes; una URL data: o http:// devuelve 400 invalid_image con param igual a messages. target_model es obligatorio: un modelo que liste prompt_expand. seconds, locale y negative_prompt son opcionales. Un destino de vídeo con una imagen se escribe a partir de ese primer fotograma. No admite streaming (stream: true devuelve 400 unsupported_parameter), y cualquier otro mensaje, incluido un mensaje system, devuelve 400 invalid_body.

Este modelo de chat usa siempre x-ai/grok-4.6; no admite prompt_expand_model. choices[0].message.content es una cadena JSON, {"prompt": "...", "negative_prompt": "..."}, más "beats" (una línea por segundo) para un destino de vídeo. Se factura a los precios por token de x-ai/grok-4.6, que figuran en usage. Un prompt que pide las instrucciones del modelo devuelve 400 prompt_rejected; una reescritura rechazada o vacía devuelve 422 expansion_refused, y una que falla, 503 upstream_error. Ninguno de estos casos se cobra.

Moderación

El campo moderation es de OpenAI. Funciona en /v1/chat/completions, /v1/images/generations, /v1/images/edits y /v1/videos con sus llamadas de edición, extensión y remix.

Cualquier otro valor se rechaza: 400 invalid_request_error, código invalid_body, param moderation, mensaje moderation must be auto or low.

low está disponible para una cuenta una vez que Hyperouter lo ha habilitado; abre un ticket de soporte para solicitarlo. Hasta entonces, una solicitud con low responde 403 permission_error, código moderation_not_enabled, param moderation, y no se envía al proveedor.

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

La respuesta no indica si se usó la exclusión voluntaria. Las políticas de los Términos del servicio siguen aplicándose. Una solicitud que el filtro del proveedor rechaza falla con 400 content_rejected y no se cobra.

Webhooks

En lugar de consultar periódicamente, un endpoint tuyo puede recibir una solicitud cuando termina un trabajo. Añade endpoints en el panel. La estructura es la de los webhooks de OpenAI, firmados con el esquema Standard Webhooks, por lo que los SDK de OpenAI los verifican.

La carga útil lleva un id, nunca un resultado, un prompt ni un cargo. Obtén el objeto con tu clave de API: data.id es el id que aceptan GET /v1/videos/{id} y GET /v1/generations/{id}. En una tarea directa es el X-Generation-Id que devolvió la creación.

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

Encabezados y verificación

Cada entrega es un POST con content-type: application/json y estos encabezados:

• webhook-id: el id del evento. Es el mismo en cada reintento, así que úsalo para eliminar duplicados.
• webhook-timestamp: segundos Unix.
• webhook-signature: v1, y el HMAC-SHA256 en base64 de id.timestamp.body, con la clave secreta del endpoint.

El secreto de firma empieza por whsec_. Se muestra una sola vez, cuando creas el endpoint y cuando lo rotas. Verifica el cuerpo bruto de la solicitud, antes de analizarlo:

// 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 lanza una excepción cuando la firma no se verifica; responde a una solicitud así con un estado de error. La llamada posterior usa la misma URL base que el resto de esta API.

Endpoints, reintentos y límites

• Un endpoint debe ser https en el puerto 443 (o sin puerto) y un nombre de host, no una dirección IP. El host debe resolverse a una dirección pública; Hyperouter lo vuelve a comprobar al conectarse. No se siguen las redirecciones.
• Una cuenta tiene como máximo 10 endpoints. Cada endpoint elige los tipos de evento que quiere.
• Un 2xx en 10 segundos es un éxito. Cualquier otra cosa se reintenta tras unos 5 segundos, 1 minuto, 5 minutos, 30 minutos, 2 horas, 5 horas, 10 horas y 10 horas, y después la entrega se marca como fallida.
• Un endpoint cuyas entregas fallan todas durante 3 días se desactiva, y el panel indica el motivo. Vuelve a activarlo después de arreglar el receptor.
• El panel lista las entregas de cada endpoint con su estado, intentos, último estado HTTP y último error. Tiene Resend (mismo id de evento) y Send test event, que entrega un evento webhook.test cuyo data.id es el id del endpoint.

Servidor MCP

Un asistente de IA puede trabajar con tu cuenta de Hyperouter a través del Model Context Protocol (MCP). El servidor gestiona el panel: claves de API, actividad, créditos, tickets, webhooks y la lista de modelos. No ejecuta modelos. Las llamadas a modelos siguen yendo a /v1 con una clave de API.

El servidor habla Streamable HTTP y JSON-RPC 2.0. Admite las revisiones de MCP 2025-11-25 y 2025-06-18. No tiene estado: no hay sesiones, y GET /mcp responde 405.

Tokens de acceso

Un cliente MCP se autentica con un token de acceso del panel, no con una clave de API.

• Crea un token en el panel. Dale un nombre, un ámbito y, opcionalmente, una fecha de caducidad.
• Un token empieza por hr_dt_. Se muestra una sola vez. Hyperouter guarda solo un hash.
• Un usuario de la cuenta puede tener como máximo 25 tokens no caducados ni revocados. Revoca un token en el panel para detenerlo al instante.
• Un token no funciona en /v1, y una clave de API no funciona en /mcp.
• Un token actúa como el usuario que lo creó, con los permisos de ese usuario. Los permisos se comprueban en cada mensaje, así que un cambio de rol se aplica en la siguiente llamada.

Envía el token como token bearer:

Authorization: Bearer hr_dt_...

Protocolo

Una notificación, o una respuesta al servidor, responde 202 sin cuerpo. Un lote JSON-RPC se rechaza con el error -32600. Un mensaje no debe superar 1 MiB. Un encabezado MCP-Protocol-Version desconocido responde 400. Una solicitud de navegador debe proceder de https://dash.hyperouter.app; un cliente que no envía el encabezado Origin no se ve afectado.

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

Herramientas

tools/list devuelve el conjunto actual de herramientas. Cada herramienta corresponde a una ruta del panel y lleva un esquema JSON Schema para sus argumentos. Las herramientas cubren:

• Cuenta y claves: get_me, list_api_keys, create_api_key, update_api_key.
• Actividad y créditos: 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.
• Modelos: list_models.
• Las herramientas de personal, con el prefijo admin_, aparecen solo para los usuarios que tienen el permiso de personal.

Una herramienta responde con un elemento de contenido de texto que contiene el cuerpo JSON de la ruta. Cuando la ruta falla, el resultado tiene isError: true y el texto <message> (<code>, HTTP <status>). Una herramienta desconocida, o una que tu token no puede ver, es el error JSON-RPC -32602.

Aprobaciones

Una escritura sensible, como acreditar una cuenta, no se ejecuta de inmediato. La herramienta no la ejecuta. Responde con status igual a approval_required y una approval_url en el panel. El usuario abre el enlace, confirma con un segundo factor y aprueba la acción. Una aprobación caduca a las 24 horas. El usuario también puede rechazarla.

Facturación y límites

• Las solicitudes se pagan con un saldo prepagado en USD, facturadas al precio de lista del proveedor que las atendió, sin recargo.
• Retener y liquidar. Antes de ejecutar una solicitud, Hyperouter retiene lo máximo que puede costar: tu entrada más max_tokens en chat, la cantidad solicitada en imágenes y los segundos en vídeo. Cuando termina, se te cobra lo que se usó y el resto de la retención se libera. El saldo nunca es negativo.
• Una solicitud fallida, o un trabajo de imagen o vídeo fallido, no cuesta nada. Un intento de reserva que falla no cuesta nada.
• Cada respuesta incluye su cargo como usage.cost, un número JSON en USD: en chat, en imágenes, en un vídeo liquidado y en GET /v1/generations/{id}. El panel muestra todas las solicitudes y tu gasto por día, modelo y clave.
• Los importes son exactos: el dinero se cuenta en milmillonésimas de dólar y nunca se redondea a través de un float. Los precios de GET /v1/models son cadenas decimales.
• Por ahora las recargas son manuales. Abre una solicitud de recarga en el panel con el importe, la referencia del pago y una captura de pantalla del pago. El equipo comprueba el pago y acredita tu saldo, y responde en el mismo ticket.
• Comisión por recarga. Cada recarga lleva una comisión del 5,5 % del importe pagado, con un mínimo de $0.80, que se descuenta cuando se acredita la recarga: un pago de $100 acredita $94.50, y un pago de $10 acredita $9.20. La comisión vigente se muestra en la página Credits antes de que solicites una recarga, y cada recarga de tu historial muestra el importe pagado y la comisión. Las solicitudes en sí no llevan ninguna comisión.

Límites de velocidad

Cada cuenta tiene un límite de solicitudes por minuto y de solicitudes en curso a la vez. Ambos cuentan juntas todas las claves de API de la cuenta, y se aplican a toda solicitud que inicia trabajo: chat completions, creaciones de imagen y vídeo, y creaciones directas. Leer un resultado (GET /v1/generations/{id}, GET /v1/videos…, una consulta directa de tarea) no cuenta; las consultas directas se cuentan aparte, por proveedor, con el mismo límite de solicitudes por minuto.

Tu nivel depende del total que hayas recargado, antes de la comisión por recarga:

Tus límites actuales aparecen en la página Credits. Son los valores por defecto; el personal puede cambiarlos para la plataforma o para una cuenta concreta, y el cambio se aplica en un minuto.

Si se supera cualquiera de los dos límites, la solicitud se rechaza antes de retener o reenviar nada, con 429, type: rate_limit_error, code: rate_limited y un encabezado Retry-After en segundos. El mensaje indica el límite alcanzado. Una solicitud cuenta para el minuto aunque se rechace. Una solicitud en curso, incluido un stream, cuenta hasta que termina.

Como protección contra el intento de adivinar claves, Hyperouter cuenta las comprobaciones fallidas de clave de API por dirección de cliente. Más de 30 en un minuto bloquean esa dirección en todas las rutas /v1 durante 15 minutos: 429, rate_limit_error, too_many_auth_failures, con Retry-After. Una clave válida no levanta el bloqueo.

Soporte

Abre un ticket en el panel para dudas sobre facturación, recargas y la API; el equipo responde en el mismo hilo. También puedes escribir a [email protected]. Incluye el id de la respuesta cuando informes de una solicitud concreta.