Descubrimiento de modelos

Use la página de Modelos o la API de Modelos para inspeccionar los modelos de texto disponibles. Los metadatos del modelo incluyen proveedor, proveedor de servicio, modalidad, longitud de contexto, familias de API soportadas, capacidades soportadas, disponibilidad, límites a nivel de cuenta y precios en créditos.

Endpoint: GET /v1/models Propósito: Listar los modelos disponibles para la cuenta actual.

curl --request GET \
  --url https://api.basicrouter.ai/api/v1/models \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

Matriz de capacidades

Matriz de compatibilidad de familias de API

Autenticación

Cada solicitud API usa un token bearer. Guarde las claves en variables de entorno del lado del servidor, rótelas cuando cambie el acceso del equipo y registre los IDs de solicitud para depuración.

Recomendaciones de seguridad de claves

1. Mantenga las claves API en el servidor. No exponga las claves en código de cliente del navegador o móvil.
2. Use claves separadas para desarrollo, staging, producción e integraciones de terceros.
3. Limite las claves por entorno, servicio, cliente o inquilino cuando esté disponible.
4. Rote las claves tras la salida de empleados, cambios de acceso de proveedores o sospecha de fuga.
5. Guarde las claves en gestores de secretos o variables de entorno, no en código fuente.

Agentes de programación

BasicRouter funciona con agentes de programación y herramientas de desarrollo de IA que soportan endpoints API compatibles con OpenAI o Anthropic. Use alias de enrutamiento como mwf/coding-auto para que BasicRouter pueda enrutar al mejor modelo de programación disponible sin requerir que los desarrolladores cambien la configuración de la herramienta.

Configuración genérica compatible con OpenAI

Use esta configuración para Cursor, Codex, Hermes, OpenClaw, Continue, Aider, Cline, agentes basados en LangChain, agentes basados en LlamaIndex y runtimes de agentes personalizados compatibles con OpenAI.

export OPENAI_BASE_URL="https://api.basicrouter.ai/api/v1"
export OPENAI_API_KEY="$BASICROUTER_API_KEY"
export OPENAI_MODEL="mwf/coding-auto"

Configuración genérica compatible con Anthropic

Use esta configuración para clientes y herramientas compatibles con Claude que esperan el formato Anthropic Messages.

export ANTHROPIC_BASE_URL="https://api.basicrouter.ai/api/anthropic"
export ANTHROPIC_API_KEY="$BASICROUTER_API_KEY"
export ANTHROPIC_MODEL="mwf/coding-auto"

Modelos de agente recomendados

Guía rápida de Cursor

Use el endpoint compatible con OpenAI.

Base URL: https://api.basicrouter.ai/api/v1
API Key:  BASICROUTER_API_KEY
Model:    mwf/coding-auto

Pasos recomendados:

1. Abra la configuración de Cursor.
2. Agregue o habilite la configuración de clave API compatible con OpenAI.
3. Establezca la URL base de OpenAI en https://api.basicrouter.ai/api/v1.
4. Agregue un modelo personalizado como mwf/coding-auto, mwf/coding-fast o mwf/coding-long.
5. Use un modelo que soporte streaming y llamada a herramientas para el mejor comportamiento del agente.

Solución de problemas:

Guía rápida de Claude Code

Use el endpoint de puerta de enlace compatible con Anthropic.

export ANTHROPIC_BASE_URL="https://api.basicrouter.ai/api/anthropic"
export ANTHROPIC_API_KEY="$BASICROUTER_API_KEY"
export ANTHROPIC_MODEL="mwf/coding-auto"

BasicRouter soporta esta ruta compatible con Anthropic para Claude Code y compatibilidad con el SDK de Anthropic:

POST /api/v1/messages

Requisitos recomendados:

Guía rápida de Codex

Use BasicRouter como proveedor de modelos personalizado compatible con OpenAI.

Configuración de proveedor de ejemplo:

[model_providers.basicrouter]
name = "BasicRouter"
base_url = "https://api.basicrouter.ai/api/v1"
env_key = "BASICROUTER_API_KEY"
wire_api = "responses"

model_provider = "basicrouter"
model = "mwf/coding-auto"

Variable de entorno:

export BASICROUTER_API_KEY="br_xxx"

Modelos recomendados:

Solución de problemas:

Guía rápida de Hermes

Use el endpoint compatible con OpenAI a menos que su despliegue de Hermes esté configurado para otro protocolo.

export OPENAI_BASE_URL="https://api.basicrouter.ai/api/v1"
export OPENAI_API_KEY="$BASICROUTER_API_KEY"
export OPENAI_MODEL="mwf/coding-auto"

Política de modelo recomendada:

Guía rápida de OpenClaw

Use el endpoint compatible con OpenAI para la configuración de runtime de agente estilo OpenAI.

export OPENAI_BASE_URL="https://api.basicrouter.ai/api/v1"
export OPENAI_API_KEY="$BASICROUTER_API_KEY"
export OPENAI_MODEL="mwf/coding-auto"

Si OpenClaw soporta múltiples proveedores, configure BasicRouter como proveedor compatible con OpenAI y use alias de enrutamiento de BasicRouter para la selección de modelos.

{
  "provider": "openai-compatible",
  "base_url": "https://api.basicrouter.ai/api/v1",
  "api_key_env": "BASICROUTER_API_KEY",
  "model": "mwf/coding-auto"
}

Lista de verificación de compatibilidad de agentes

Uso de la Consola

La Consola de BasicRouter es el plano de control operativo para el acceso API, la disponibilidad de modelos, las políticas de enrutamiento, la visibilidad de uso y la administración de facturación. Ofrece a los administradores de cuenta una vista centralizada de claves, modelos, solicitudes, créditos y controles a nivel de cuenta para el tráfico de modelos en producción.

Gestión de claves API

Cree, rote, revoque y etiquete claves API desde la consola. Use claves separadas para desarrollo, staging, producción y servicios individuales para que el uso pueda ser auditado y aislado por entorno o aplicación.

Lista de modelos

Use la página de Modelos para revisar los modelos disponibles para la cuenta. Cada entrada de modelo puede incluir proveedor, proveedor de servicio, modalidad, familias de API soportadas, longitud de contexto, indicadores de capacidad, estado de disponibilidad e información de precios.

Para aplicaciones en producción, verifique las capacidades del modelo antes de habilitar el tráfico. Algunos parámetros y características dependen del modelo y pueden no estar soportados en todas las familias de API.

Uso y registros

La vista de Uso y Registros proporciona visibilidad operativa del tráfico API. Los equipos pueden inspeccionar el volumen de solicitudes, los modelos seleccionados, los destinos de enrutamiento resueltos, el consumo de créditos, la latencia, los códigos de error y los IDs de solicitud.

• Solucionar solicitudes fallidas.
• Identificar cargas de trabajo de alto costo.
• Comparar el uso de modelos entre aplicaciones y entornos.
• Validar el comportamiento de enrutamiento y respaldo.
• Investigar problemas de latencia o disponibilidad del proveedor.
• Proporcionar IDs de solicitud al contactar con soporte.

Cada respuesta API incluye o expone un ID de solicitud de BasicRouter. Guarde este ID en los registros de su aplicación para hacer que la depuración en producción y la escalada de soporte sean más eficientes.

Respaldo

El respaldo es el mecanismo de resiliencia de BasicRouter. Cuando el modelo principal o la política de enrutamiento falla, el sistema cambia automáticamente a un modelo de respaldo para seguir procesando la solicitud. Esto mantiene su aplicación receptiva y minimiza el riesgo de interrupción del servicio.

Por qué importa el respaldo

En producción, los servicios de modelos pueden encontrar varios problemas impredecibles:

• Falla del servicio de modelo: la API de origen queda temporalmente no disponible o se agota el tiempo de espera.
• Fluctuación de rendimiento: una alta carga del modelo provoca respuestas lentas o fallidas.
• Falla de enrutamiento: todos los modelos candidatos seleccionados por el enrutamiento inteligente quedan no disponibles.

El respaldo mantiene su aplicación disponible proporcionando una ruta de respaldo confiable.

Ventajas principales

Configuración global de modelo de respaldo

BasicRouter permite configurar un modelo de respaldo global desde el backend de la consola. Todas las solicitudes usan automáticamente este modelo como respaldo cuando fallan.

Cómo configurarlo:

1. Vaya a la página de configuración de estrategia de BasicRouter.
2. Busque el ajuste Modelo de respaldo predeterminado.
3. Seleccione su modelo de respaldo global de la lista desplegable.
4. Guarde el ajuste para aplicarlo inmediatamente.

Ventajas de la configuración global:

• Sin cambios en el código: configure una vez y se aplica globalmente, sin necesidad de repetir el ajuste en cada solicitud.
• Gestión centralizada: administre la política de respaldo en un solo lugar para facilitar el ajuste y monitoreo.
• Mantenimiento simplificado: reduce la complejidad del código y la posibilidad de errores de configuración.
• Reemplazo flexible: la configuración de respaldo a nivel de solicitud tiene prioridad y puede anular el ajuste global para escenarios específicos.

Configuración de respaldo a nivel de solicitud

Para escenarios de negocio específicos, puede especificar un modelo de respaldo en una solicitud individual para anular la configuración global.

Especifique el modelo de respaldo con el parámetro router.fallBackModels:

{
  "model": "claude-sonnet-4",
  "messages": [
    {
      "role": "user",
      "content": "Explain what quantum computing is"
    }
  ],
  "router": {
    "fallBackModels": ["glm-5.2"]
  }
}

Reglas de prioridad

Cuando hay múltiples configuraciones de respaldo, la prioridad va de mayor a menor:

1. router.fallBackModels a nivel de solicitud: el modelo de respaldo especificado en una solicitud individual.
2. Modelo de respaldo predeterminado global: el modelo de respaldo global configurado en la consola.
3. Sin respaldo: si no se configura ninguno, la solicitud devuelve un error al fallar.

Administración de cuenta

Dependiendo del tipo de cuenta, la consola puede incluir habilitación de modelos a nivel de cuenta, controles de revendedor o distribuidor, configuración de facturación y ajustes de acceso. Los administradores pueden usar estos controles para alinear el acceso a modelos, la visibilidad de uso y la responsabilidad de facturación con aplicaciones, cuentas de cliente o unidades de negocio.

Lista de verificación de operaciones de producción

Facturación y créditos

BasicRouter usa un modelo de facturación basado en créditos para cargas de trabajo de texto, imagen, video y otros modelos soportados. Los créditos proporcionan una unidad unificada para el uso de múltiples modelos y proveedores, de modo que los equipos puedan gestionar el consumo de manera consistente entre modalidades y familias de API.

Los precios detallados de los modelos están disponibles en la página de Modelos o a través de las APIs de metadatos de modelos. Los precios pueden variar según el modelo, proveedor, modalidad, resolución, tipo de token, longitud de salida, duración de la tarea, tipo de cuenta y acuerdo comercial.

Recargar y monedero

Las cuentas pueden añadir créditos de monedero de pago por uso para un uso flexible. Los créditos del monedero se usan después de que se hayan consumido los créditos del plan mensual y los paquetes de recursos, a menos que se aplique una regla de facturación personalizada a la cuenta.

Los créditos del monedero no expiran a menos que se especifique lo contrario en los términos comerciales aplicables. Se cobra una tarifa de servicio al recargar el monedero de pago por uso.

Planes mensuales y paquetes de recursos

Cada usuario o cuenta puede seleccionar un plan mensual activo. Los planes mensuales proporcionan una cantidad definida de capacidad de uso, términos comerciales y configuración de acceso a nivel de cuenta para el período de facturación.

Los usuarios también pueden comprar múltiples paquetes de recursos para capacidad de uso adicional. Los paquetes de recursos pueden separar el uso comprometido del saldo del monedero de pago por uso y son útiles para uso intensivo de texto, imagen, video o cargas de trabajo dedicadas.

Orden de deducción

A menos que se configuren reglas de facturación personalizadas, los créditos se deducen en el siguiente orden:

Para cuentas con términos comerciales personalizados, el orden de deducción, las reglas de expiración, el uso incluido y los precios pueden diferir. Las reglas específicas de cuenta se muestran en la consola o se proporcionan a través del acuerdo comercial.

Precios personalizados

Los precios pueden personalizarse para cada usuario o cuenta. Los clientes empresariales, las cuentas de revendedor, las cuentas de distribuidor y los clientes de alto volumen pueden ser elegibles para precios personalizados. Contacte con ventas para obtener una cotización.

Los precios personalizados pueden configurarse por cuenta, modelo, proveedor, modalidad, región, volumen de uso o acuerdo comercial. Cuando se habilitan precios personalizados, la consola y las APIs de facturación reflejan los precios y reglas de deducción específicos de la cuenta cuando estén disponibles.

Unidades de precio

Diferentes modalidades de modelo usan diferentes unidades de medida. BasicRouter convierte estas unidades en créditos según las reglas de precios del modelo.

Las unidades de precio pueden variar según el modelo. Consulte siempre la página de detalles del modelo o los metadatos de precios antes de habilitar un modelo en producción.

Atribución de uso

El uso de BasicRouter puede revisarse por cuenta, clave API, modelo, modalidad o rango de tiempo. Esto permite a los equipos atribuir costos a aplicaciones, entornos, clientes o unidades de negocio internas.

Saldo de créditos

Verifique cuántos créditos están disponibles en su cuenta. El saldo se divide en tres monederos que se deducen en orden: la asignación del plan mensual, los paquetes de recursos comprados y el monedero de pago por uso. También está disponible un total combinado de recursos (plan mensual + paquetes de recursos, excluyendo pago por uso) para rastrear el uso incluido separadamente del gasto de recarga.

Para obtener esto mediante programación, consulte GET /v1/billing/balance en la Referencia API.

Detalles de uso

Revise una lista paginada y cronológica de registros de uso individuales para reportes, monitoreo y asignación interna de costos. Cada registro muestra el modelo, el tipo de modelo (texto, imagen o video), los créditos deducidos y un desglose de qué monedero se usó para cada deducción. Los resultados pueden filtrarse a un rango de tiempo específico.

Para obtener esto mediante programación, consulte GET /v1/usage en la Referencia API.

Historial de transacciones

Use el historial de transacciones para revisar movimientos de créditos, incluyendo recargas, asignaciones de planes, concesiones de paquetes de recursos, deducciones de uso, ajustes y correcciones administrativas.

Para obtener esto mediante programación, consulte GET /v1/billing/transactions en la Referencia API.

Solicitudes fallidas y reembolsos

Los errores de validación, los errores de autenticación y los errores de permisos generalmente no se facturan porque no ocurre ejecución del modelo. Las solicitudes que llegan a un modelo de origen o que generan salida parcial pueden consumir créditos dependiendo del modelo, el proveedor y el estado de la respuesta.

Para tareas asíncronas de imagen y video, el comportamiento de facturación depende de si la tarea fue aceptada, iniciada, completada, fallida o cancelada. La respuesta de detalle de la tarea incluye información de uso cuando se han consumido créditos.

Las recargas, los planes mensuales, los paquetes de recursos y los créditos consumidos no son reembolsables a menos que se especifique lo contrario en el acuerdo comercial aplicable o lo exija la ley.

Referencia API

Convenciones comunes

URL base

Todos los endpoints se sirven bajo el prefijo /v1.

Autenticación

Las llamadas a los endpoints /v1/* usan autenticación de Clave API (no JWT). La clave API se pasa mediante el siguiente encabezado:

Las claves faltantes o inválidas devuelven 401.

Verificación previa de saldo

Todos los endpoints de llamada a modelos ejecutan una verificación previa de saldo antes de la ejecución:

• Un saldo insuficiente devuelve Insufficient credit, asignado a:
  • Protocolo OpenAI: HTTP 400, code = insufficient_quota
  • Protocolo Anthropic: HTTP 402, type = billing_error
• Algunos endpoints también estiman un costo mínimo por modelo para una segunda verificación previa.

POST https://api.basicrouter.ai/api/v1/chat/completions

Endpoint compatible con OpenAI Chat Completions. Soporta streaming y no streaming, llamadas a herramientas, modo JSON y entrada multimodal.

Campos de Message:

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/chat/completions \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "glm-5.2",
    "messages": [{"role": "user", "content": "Describe Hangzhou in one sentence."}],
    "stream": false,
    "temperature": 0.7
  }'

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1721380000,
  "model": "glm-5.2",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "Hangzhou is ..."},
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 12, "completion_tokens": 18, "total_tokens": 30}
}

Campos de respuesta (no streaming):

Ejemplo de respuesta en streaming:

data: {"object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant","content":"..."}}]}

data: {"object":"chat.completion.chunk","choices":[{"delta":{"content":"..."}}]}

data: [DONE]

POST https://api.basicrouter.ai/api/v1/responses

Endpoint compatible con OpenAI Responses. Usa input en lugar de messages, instructions en lugar de un mensaje del sistema, y un bloque text en lugar de response_format.

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/responses \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "glm-5.2",
    "input": "Describe Hangzhou in one sentence.",
    "instructions": "Be concise.",
    "stream": false
  }'

{
  "id": "resp_xxx",
  "object": "response",
  "model": "glm-5.2",
  "status": "completed",
  "created_at": 1721380000,
  "output": [
    {
      "id": "msg_xxx",
      "type": "message",
      "role": "assistant",
      "content": [{"type": "output_text", "text": "Hangzhou is ..."}],
      "status": "completed"
    }
  ],
  "usage": {"input_tokens": 12, "output_tokens": 18, "total_tokens": 30}
}

Campos de respuesta (no streaming):

El streaming sigue los eventos de la API de Responses:

POST https://api.basicrouter.ai/api/v1/messages

Endpoint compatible con Anthropic Messages. Acepta encabezados x-api-key y anthropic-version: 2023-06-01. Los bloques de contenido soportan text, image, tool_use, tool_result, thinking y redacted_thinking.

Ejemplos de bloque de imagen:

{ "type": "image", "source": { "type": "base64", "media_type": "...", "data": "..." } }
{ "type": "image", "source": { "type": "url", "url": "..." } }

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/messages \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "claude-sonnet-4.6",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Describe Hangzhou in one sentence."}]
  }'

{
  "id": "msg_xxx",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-4.6",
  "content": [{"type": "text", "text": "Hangzhou is ..."}],
  "stop_reason": "end_turn",
  "usage": {"input_tokens": 12, "output_tokens": 18}
}

Campos de respuesta (no streaming):

GET https://api.basicrouter.ai/api/v1/models

Devuelve todos los modelos API en línea y habilitados.

curl --request GET \
  --url https://api.basicrouter.ai/api/v1/models \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "glm-5.2",
      "object": "model",
      "display_name": "glm-5.2",
      "created": 1721380000,
      "owned_by": "Zai",
      "input_modalities": ["text", "image"],
      "output_modalities": ["text"],
      "context_length": 128000
    }
  ]
}

Campos de cada entrada de modelo (data[]):

GET https://api.basicrouter.ai/api/v1/models/{model}

Devuelve un único modelo con la misma estructura que una entrada de lista. Devuelve HTTP 404 cuando el modelo no existe.

curl --request GET \
  --url https://api.basicrouter.ai/api/v1/models/gpt-5.5 \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

Respuesta exitosa: un objeto de modelo único con los mismos campos que una entrada de lista de /v1/models.

Cuando el modelo no existe, devuelve HTTP 404:

{"error": {"message": "The model 'xxx' does not exist", "type": "invalid_request_error", "code": "invalid_model_error"}}

GET https://api.basicrouter.ai/api/v1/image-models

Consulta las resoluciones, relaciones y cantidades máximas soportadas por un modelo de imagen antes de llamar a /v1/image-generations. No requiere autenticación.

curl --request GET \
  --url https://api.basicrouter.ai/api/v1/image-models \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "gpt-image-2",
      "object": "image_model",
      "displayName": "GPT Image 1",
      "description": "...",
      "icon": "...",
      "created": 1721380000,
      "maxCount": 4,
      "fileMax": 10,
      "resolutions": ["720p", "1080p"],
      "ratios": ["1:1", "3:2"]
    }
  ]
}

GET https://api.basicrouter.ai/api/v1/video-models

Consulta los valores de videoType soportados, el rango de duración, las resoluciones y las relaciones de un modelo de video antes de llamar a /v1/video-generations. No requiere autenticación.

Campos de VideoTypeOption:

curl --request GET \
  --url https://api.basicrouter.ai/api/v1/video-models \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "sora-2",
      "object": "video_model",
      "displayName": "Sora 2",
      "description": "...",
      "icon": "...",
      "created": 1721380000,
      "allowedVideoTypes": [
        {"code": 1, "name": "text-to-video"},
        {"code": 2, "name": "image-to-video"},
        {"code": 3, "name": "image-to-video (first/last frame)"}
      ],
      "videoDurationMin": 5,
      "videoDurationMax": 10,
      "videoDurationSuggest": [5, 8, 10],
      "resolutions": ["1080p", "720p"],
      "ratios": ["16:9", "9:16"],
      "fileMax": 5
    }
  ]
}

POST https://api.basicrouter.ai/api/v1/image-generations

Envía asíncronamente una tarea de generación de imágenes. Devuelve un taskId inmediatamente; recupere el resultado consultando GET /v1/image-generations/{taskId} o a través de un webhook callbackUrl.

El model, los valores soportados de resolution / ratio, el límite superior de count y el límite de subida de imágenes de referencia (fileMax) deben obtenerse primero de GET /v1/image-models. Solo se aceptan los valores anunciados por la especificación de ese modelo.

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/image-generations \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "seedream-4.5",
    "text": "A cat drinking water by the river",
    "count": 1,
    "resolution": "2k",
    "ratio": "1:1",
    "imageUrls": []
  }'

{
  "code": 200,
  "message": "image task is commit",
  "data": {"taskId": "img_xxx"}
}

Respuestas de error:

// Insufficient credit
{ "code": 500, "message": "Insufficient credit" }

// Model not found
{ "code": 404, "message": "Model not found: xxx" }

GET https://api.basicrouter.ai/api/v1/image-generations/{taskId}

Consulta una tarea de generación de imágenes. status es pending / success / failed. images es un arreglo de URLs de imágenes serializado en JSON; text contiene cualquier descripción de texto adjunta por el modelo (por ejemplo, salida multimodal de Gemini), null en caso contrario.

curl --request GET \
  --url https://api.basicrouter.ai/api/v1/image-generations/img_xxx \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "img_xxx",
    "status": "success",
    "errorMessage": null,
    "images": "[\"https://.../1.png\"]",
    "text": null
  }
}

Campos de respuesta data:

Tarea no encontrada:

{ "code": 500, "message": "task not found" }

Si se proporcionó callbackUrl al enviar, el servidor envía el resultado final success / failed a través del webhook con la misma estructura de data.

Ejemplo completo (envío + consulta)

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class ImageGenerationExample {
  private static final String BASE = "https://api.basicrouter.ai/api/v1";
  private static final String API_KEY = System.getenv("BASICROUTER_API_KEY");

  public static void main(String[] args) throws Exception {
    HttpClient http = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(10)).build();

    // 1. Submit the task.
    String body = "{"
        + "\"model\":\"seedream-4.5\","
        + "\"text\":\"A cat drinking water by the river\","
        + "\"count\":1,"
        + "\"resolution\":\"2k\","
        + "\"ratio\":\"1:1\","
        + "\"imageUrls\":[]"
        + "}";
    HttpResponse<String> submit = http.send(
        HttpRequest.newBuilder(URI.create(BASE + "/image-generations"))
            .header("Authorization", "Bearer " + API_KEY)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body)).build(),
        HttpResponse.BodyHandlers.ofString());

    String taskId = extract(submit.body(), "taskId");
    System.out.println("taskId = " + taskId);

    // 2. Poll until terminal status.
    String status = "pending";
    while ("pending".equals(status)) {
      Thread.sleep(15_000L);
      HttpResponse<String> poll = http.send(
          HttpRequest.newBuilder(URI.create(BASE + "/image-generations/" + taskId))
              .header("Authorization", "Bearer " + API_KEY).GET().build(),
          HttpResponse.BodyHandlers.ofString());
      status = extract(poll.body(), "status");
      System.out.println("status = " + status);
    }

    if (!"success".equals(status)) {
      throw new RuntimeException("image generation failed: " + status);
    }
    // images is a JSON-stringified array of URLs.
    String images = extract(pollResult(http, taskId), "images");
    System.out.println("images = " + images);
  }

  // Minimal JSON field extractor — use Jackson/Gson in production.
  private static String extract(String json, String field) {
    int i = json.indexOf("\"" + field + "\":");
    if (i < 0) return null;
    i += field.length() + 3;
    if (json.charAt(i) == '\"') {
      int end = json.indexOf('\"', i + 1);
      return json.substring(i + 1, end);
    }
    int end = i;
    while (end < json.length() && "0123456789.".indexOf(json.charAt(end)) >= 0) end++;
    return json.substring(i, end);
  }

  private static String pollResult(HttpClient http, String taskId) throws Exception {
    return http.send(HttpRequest.newBuilder(URI.create(BASE + "/image-generations/" + taskId))
        .header("Authorization", "Bearer " + API_KEY).GET().build(),
        HttpResponse.BodyHandlers.ofString()).body();
  }
}

import os
import time
import requests

BASE = "https://api.basicrouter.ai/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['BASICROUTER_API_KEY']}"}

# 1. Submit the task.
resp = requests.post(
    f"{BASE}/image-generations",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={
        "model": "seedream-4.5",
        "text": "A cat drinking water by the river",
        "count": 1,
        "resolution": "2k",
        "ratio": "1:1",
        "imageUrls": [],
    },
)
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print(f"taskId = {task_id}")

# 2. Poll until terminal status.
while True:
    time.sleep(15)
    poll = requests.get(f"{BASE}/image-generations/{task_id}", headers=HEADERS)
    poll.raise_for_status()
    data = poll.json()["data"]
    status = data["status"]
    print(f"status = {status}")
    if status != "pending":
        break

if status != "success":
    raise RuntimeError(f"image generation failed: {data.get('errorMessage')}")

# images is a JSON-stringified array of URLs.
import json
images = json.loads(data["images"])
print(f"images = {images}")

POST https://api.basicrouter.ai/api/v1/video-generations

Envía asíncronamente una tarea de generación de video. Devuelve un taskId inmediatamente; recupere el resultado consultando GET /v1/video-generations/{taskId} o a través de un webhook callbackUrl.

El model, los valores permitidos de videoType, el rango de duración (videoDurationMin/Max), la resolution / ratio soportadas y el límite de subida de recursos de referencia (fileMax) deben obtenerse primero de GET /v1/video-models. Solo se aceptan los códigos de videoType listados en allowedVideoTypes de ese modelo.

Ejemplos para cada videoType:

1. Texto a video (videoType=1)

Genera un video solo a partir de un prompt de texto; no se necesitan recursos de referencia.

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/video-generations \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "videoType": 1,
    "text": "A cat jumping on a bed",
    "resolution": "480p",
    "ratio": "16:9",
    "duration": 4,
    "model": "seedance-2.0"
  }'

2. Imagen a video - primer frame (videoType=2)

Proporcione un único frame inicial en imageUrls; el modelo genera un video que comienza desde ese frame.

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/video-generations \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "videoType": 2,
    "text": "Happily shaking head",
    "resolution": "480p",
    "ratio": "16:9",
    "duration": 4,
    "model": "seedance-2.0",
    "imageUrls": ["https://basicrouter-flie.oss-accelerate.aliyuncs.com/test/first-frame.png"]
  }'

3. Imagen a video - primer y último frame (videoType=3)

Proporcione tanto el primer como el último frame en imageUrls (orden: [primero, último]); el modelo genera un video de transición entre los dos frames.

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/video-generations \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "videoType": 3,
    "text": "Put on the hat",
    "resolution": "480p",
    "ratio": "16:9",
    "duration": 4,
    "model": "seedance-2.0",
    "imageUrls": [
      "https://basicrouter-flie.oss-accelerate.aliyuncs.com/test/first-frame.png",
      "https://basicrouter-flie.oss-accelerate.aliyuncs.com/test/last-frame.png"
    ]
  }'

4. Imagen a video - referencia (videoType=4)

Proporcione una o más imágenes de referencia en imageUrls; el modelo usa su estilo/contenido como referencia (no como primer/último frame forzado) para generar el video.

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/video-generations \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "videoType": 4,
    "text": "Two cats playing together",
    "resolution": "480p",
    "ratio": "16:9",
    "duration": 4,
    "model": "kling-v3-omni-video",
    "imageUrls": [
      "https://basicrouter-flie.oss-accelerate.aliyuncs.com/test/ref-1.png",
      "https://basicrouter-flie.oss-accelerate.aliyuncs.com/test/ref-2.png"
    ]
  }'

5. Toda referencia (videoType=5)

Referencias mixtas de imagen / video / audio. Referencie recursos por posición en el prompt: la 1ª entrada en imageUrls es @图片 1, la 1ª en videoUrls es @视频 1, la 1ª en audioUrls es @音频 1. videoUrls también acepta cadenas de URL simples.

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/video-generations \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "videoType": 5,
    "text": "Use the first-person framing of @视频 1 and @音频 1 as background music. First-person tea ad; start frame is @图片 1 ... end frame is @图片 2.",
    "model": "seedance-2.0",
    "imageUrls": [
      "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic1.jpg",
      "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic2.jpg"
    ],
    "videoUrls": ["https://ark-project.tos-cn-beijing.volces.com/doc_video/r2v_tea_video1.mp4"],
    "audioUrls": ["https://ark-project.tos-cn-beijing.volces.com/doc_audio/r2v_tea_audio1.mp3"],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 11
  }'

Respuesta de envío (los cinco tipos):

{
  "code": 200,
  "message": "success",
  "data": {"taskId": "vid_xxx"}
}

GET https://api.basicrouter.ai/api/v1/video-generations/{taskId}

Consulta una tarea de generación de video. status es pending / success / failed; videoUrl es la URL del video generado y lastFrameUrl es la URL del último frame (escenarios de image-to-video).

curl --request GET \
  --url https://api.basicrouter.ai/api/v1/video-generations/vid_xxx \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

{
  "code": 200,
  "message": "success",
  "data": {
    "status": "success",
    "videoUrl": "https://.../out.mp4",
    "lastFrameUrl": null,
    "message": null
  }
}

Campos de respuesta data:

Si se proporcionó callbackUrl al enviar, el servidor envía el resultado final a través del webhook con la misma estructura de data.

Ejemplo completo (envío + consulta)

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class VideoGenerationExample {
  private static final String BASE = "https://api.basicrouter.ai/api/v1";
  private static final String API_KEY = System.getenv("BASICROUTER_API_KEY");

  public static void main(String[] args) throws Exception {
    HttpClient http = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(10)).build();

    // 1. Submit the task (videoType=1: text-to-video).
    String body = "{"
        + "\"videoType\":1,"
        + "\"text\":\"A cat jumping on a bed\","
        + "\"resolution\":\"480p\","
        + "\"ratio\":\"16:9\","
        + "\"duration\":4,"
        + "\"model\":\"seedance-2.0\""
        + "}";
    HttpResponse<String> submit = http.send(
        HttpRequest.newBuilder(URI.create(BASE + "/video-generations"))
            .header("Authorization", "Bearer " + API_KEY)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body)).build(),
        HttpResponse.BodyHandlers.ofString());

    String taskId = extract(submit.body(), "taskId");
    System.out.println("taskId = " + taskId);

    // 2. Poll until terminal status. Video tasks take longer — poll every 20s.
    String status = "pending";
    String lastBody = null;
    while ("pending".equals(status)) {
      Thread.sleep(20_000L);
      HttpResponse<String> poll = http.send(
          HttpRequest.newBuilder(URI.create(BASE + "/video-generations/" + taskId))
              .header("Authorization", "Bearer " + API_KEY).GET().build(),
          HttpResponse.BodyHandlers.ofString());
      lastBody = poll.body();
      status = extract(lastBody, "status");
      System.out.println("status = " + status);
    }

    if (!"success".equals(status)) {
      throw new RuntimeException("video generation failed: " + status);
    }
    String videoUrl = extract(lastBody, "videoUrl");
    System.out.println("videoUrl = " + videoUrl);
  }

  // Minimal JSON field extractor — use Jackson/Gson in production.
  private static String extract(String json, String field) {
    int i = json.indexOf("\"" + field + "\":");
    if (i < 0) return null;
    i += field.length() + 3;
    if (json.charAt(i) == '\"') {
      int end = json.indexOf('\"', i + 1);
      return json.substring(i + 1, end);
    }
    int end = i;
    while (end < json.length() && "0123456789.".indexOf(json.charAt(end)) >= 0) end++;
    return json.substring(i, end);
  }
}

import os
import time
import requests

BASE = "https://api.basicrouter.ai/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['BASICROUTER_API_KEY']}"}

# 1. Submit the task (videoType=1: text-to-video).
resp = requests.post(
    f"{BASE}/video-generations",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={
        "videoType": 1,
        "text": "A cat jumping on a bed",
        "resolution": "480p",
        "ratio": "16:9",
        "duration": 4,
        "model": "seedance-2.0",
    },
)
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print(f"taskId = {task_id}")

# 2. Poll until terminal status. Video tasks take longer — poll every 20s.
while True:
    time.sleep(20)
    poll = requests.get(f"{BASE}/video-generations/{task_id}", headers=HEADERS)
    poll.raise_for_status()
    data = poll.json()["data"]
    status = data["status"]
    print(f"status = {status}")
    if status != "pending":
        break

if status != "success":
    raise RuntimeError(f"video generation failed: {data.get('message')}")

print(f"videoUrl = {data['videoUrl']}")
if data.get("lastFrameUrl"):
    print(f"lastFrameUrl = {data['lastFrameUrl']}")

GET https://api.basicrouter.ai/api/v1/billing/balance

Devuelve el saldo de la cuenta dividido en tres monederos: plan mensual, paquetes de recursos y crédito de pago por uso.

curl --request GET \
  --url https://api.basicrouter.ai/api/v1/billing/balance \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

{
  "totalCredit": 128.50,
  "totalResourceCredit": 30.00,
  "wallets": {
    "monthlyPlan": {"id": "pkg_xxx", "credit": 50.00, "name": "Monthly plan"},
    "resourcePacks": [
      {"id": "rp_xxx", "credit": 30.00, "name": "Video resource pack"}
    ],
    "payAsYouGo": 48.50
  }
}

Campos de respuesta:

Campos de WalletDetailVO::

GET https://api.basicrouter.ai/api/v1/usage

Detalles de facturación de llamadas a modelos paginadas, con instantánea por precio (priceSnapshotId), ordenados por tiempo de creación del orden de forma descendente. Solo se devuelven los registros de cobro normales (reason = model usage).

Parámetros de consulta:

curl --request GET \
  --url "https://api.basicrouter.ai/api/v1/usage?page=1&size=20&startTime=2026-07-01T00:00:00&endTime=2026-07-31T23:59:59" \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

Contenedor de respuesta:

{
  "code": 0,
  "message": "success",
  "data": { ... }
}

Campos de UsageDetailVO:

Campos de CreditDetailItem:

Convención de valores nulos: solo se completan los campos relevantes para cada modelType; el resto son null. text completa los campos de tokens; image completa imageCount/imageResolution/imageRatio; video completa videoResolution/videoRatio/videoDurationSec.

Ejemplo de respuesta:

{
  "code": 200,
  "message": "success",
  "data": {
    "records": [
      {
        "priceSnapshotId": "snap_9f3c1a2b",
        "taskId": "task_5e8a1c33",
        "credit": 0.0342,
        "model": "glm-5.2",
        "modelType": "text",
        "inputTokens": 1280,
        "outputTokens": 642,
        "totalTokens": 1922,
        "cacheReadTokens": 0,
        "cacheWriteTokens": 0,
        "imageCount": null,
        "imageResolution": null,
        "imageRatio": null,
        "videoResolution": null,
        "videoRatio": null,
        "videoDurationSec": null,
        "orderCreatedAt": "2026-07-18T14:23:11",
        "creditDetails": [
          {
            "credit": 0.0342,
            "deductionSource": "balance",
            "packageName": ""
          }
        ]
      },
      {
        "priceSnapshotId": "snap_a12f77c0",
        "taskId": "task_c71e44a2",
        "credit": 1.8000,
        "model": "seedance-2.0",
        "modelType": "video",
        "inputTokens": null,
        "outputTokens": null,
        "totalTokens": null,
        "cacheReadTokens": null,
        "cacheWriteTokens": null,
        "imageCount": null,
        "imageResolution": null,
        "imageRatio": null,
        "videoResolution": "1080p",
        "videoRatio": "16:9",
        "videoDurationSec": 8,
        "orderCreatedAt": "2026-07-17T22:41:09",
        "creditDetails": [
          {
            "credit": 1.5000,
            "deductionSource": "Monthly Package",
            "packageName": "基础月度套餐"
          },
          {
            "credit": 0.3000,
            "deductionSource": "Resource Package",
            "packageName": "byteplus视频资源包"
          }
        ]
      }
    ],
    "total": 128,
    "current": 1,
    "size": 20,
    "pages": 7
  }
}

GET https://api.basicrouter.ai/api/v1/billing/transactions

Lista paginada de las transacciones de recarga pagadas (status=2) del usuario actual, ordenadas por created_at de forma descendente.

curl --request GET \
  --url "https://api.basicrouter.ai/api/v1/billing/transactions?page=1&size=20&startTime=2026-07-01%2000:00:00&endTime=2026-07-31%2023:59:59" \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

Contenedor de respuesta:

{
  "code": 0,
  "message": "success",
  "data": { ... }
}

Campos de TransactionVO:

Campos de TransactionVO:

{
  "code": 200,
  "message": "success",
  "data": {
    "records": [
      {
        "orderNo": "R20260718abc123",
        "thirdPartyOrderNo": "wx_pay_xxx",
        "amount": 50.00,
        "actualAmount": 48.50,
        "discount": 1.50,
        "paymentMethod": "wechat",
        "serviceFeeAmount": 0.00,
        "paymentChannel": "wechat",
        "source": "recharge",
        "packageName": null,
        "createdAt": "2026-07-18T14:23:11"
      }
    ],
    "total": 28,
    "current": 1,
    "size": 20,
    "pages": 2
  }
}

Operativo

Errores

BasicRouter devuelve códigos de error estables para que las aplicaciones puedan manejar reintentos, respaldos, problemas de facturación y depuración de forma consistente.

Los endpoints compatibles con proveedores intentan preservar la forma de error de la familia de API original cuando es posible. Los endpoints nativos de BasicRouter usan el objeto de error de BasicRouter.

Mapeo de estados HTTP y códigos de error

Códigos de error comunes