Descoberta de modelos

Use a página de Modelos ou a API de Modelos para inspecionar os modelos de texto disponíveis. Os metadados do modelo incluem fornecedor, provedor de serviço, modalidade, comprimento de contexto, famílias de API suportadas, capacidades suportadas, disponibilidade, limites no nível da conta e preço em créditos.

Endpoint: GET /v1/models Objetivo: Listar modelos disponíveis para a conta atual.

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

Matriz de capacidades

Matriz de compatibilidade de famílias de API

Autenticação

Toda solicitação de API usa um token bearer. Armazene as chaves em variáveis de ambiente do lado do servidor, rotacione-as quando o acesso da equipe mudar e registre os IDs de solicitação para depuração.

Recomendações de segurança de chaves

1. Mantenha as chaves API no servidor. Não exponha as chaves no código do navegador ou do cliente móvel.
2. Use separate keys for development, staging, production, and third-party integrations.
3. Defina o escopo das chaves por ambiente, serviço, cliente ou tenant quando disponível.
4. Rotate keys after employee departures, vendor access changes, or suspected leakage.
5. Armazene as chaves em gerenciadores de segredos ou variáveis de ambiente, não no código-fonte.

Agentes de programação

O BasicRouter funciona com agentes de programação e ferramentas de desenvolvimento de IA que suportam endpoints de API compatíveis com OpenAI ou Anthropic. Use aliases de roteamento como mwf/coding-auto para que o BasicRouter possa rotear para o melhor modelo de programação disponível sem exigir que os desenvolvedores alterem a configuração da ferramenta.

Configuração genérica compatível com OpenAI

Use esta configuração para Cursor, Codex, Hermes, OpenClaw, Continue, Aider, Cline, agentes baseados em LangChain, agentes baseados em LlamaIndex e runtimes de agentes personalizados compatíveis com OpenAI.

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

Configuração genérica compatível com Anthropic

Use esta configuração para clientes compatíveis com Claude e ferramentas que esperam o 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

Guia rápido do Cursor

Use o endpoint compatível com OpenAI.

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

Passos recomendados:

1. Abra as configurações do Cursor.
2. Adicione ou ative a configuração de chave API compatível com OpenAI.
3. Defina a substituição da URL base do OpenAI para https://api.basicrouter.ai/api/v1.
4. Adicione um modelo personalizado como mwf/coding-auto, mwf/coding-fast ou mwf/coding-long.
5. Use um modelo que suporte streaming e chamada de ferramentas para o melhor comportamento do agente.

Solução de problemas:

Guia rápido do Claude Code

Use o endpoint do gateway compatível com Anthropic.

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

O BasicRouter suporta este caminho compatível com Anthropic para compatibilidade com Claude Code e SDK Anthropic:

POST /api/v1/messages

Requisitos recomendados:

Guia rápido do Codex

Use o BasicRouter como um provedor de modelo personalizado compatível com OpenAI.

Exemplo de configuração do provedor:

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

Variável de ambiente:

export BASICROUTER_API_KEY="br_xxx"

Modelos recomendados:

Solução de problemas:

Guia rápido do Hermes

Use o endpoint compatível com OpenAI, a menos que sua implantação do Hermes esteja configurada para outro 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:

Guia rápido do OpenClaw

Use o endpoint compatível com OpenAI para a configuração de runtime de agente no 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"

Se o OpenClaw suportar múltiplos provedores, configure o BasicRouter como um provedor compatível com OpenAI e use aliases de roteamento do BasicRouter para seleção de modelo.

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

Lista de verificação de compatibilidade de agentes

Uso do console

O Console do BasicRouter é o plano de controle operacional para acesso à API, disponibilidade de modelos, políticas de roteamento, visibilidade de uso e administração de cobrança. Ele oferece aos administradores da conta uma visão centralizada de chaves, modelos, solicitações, créditos e controles no nível da conta para tráfego de modelos em produção.

Gerenciamento de chaves API

Crie, rotacione, revogue e rotule chaves API no console. Use chaves separadas para desenvolvimento, homologação, produção e serviços individuais para que o uso possa ser auditado e isolado por ambiente ou aplicação.

Lista de modelos

Use a página de Modelos para revisar os modelos disponíveis para a conta. Cada entrada de modelo pode incluir fornecedor, provedor de serviço, modalidade, famílias de API suportadas, comprimento de contexto, sinalizadores de capacidade, status de disponibilidade e informações de preço.

Para aplicações em produção, verifique as capacidades do modelo antes de ativar o tráfego. Alguns parâmetros e recursos dependem do modelo e podem não ser suportados em todas as famílias de API.

Uso e logs

A visualização de Uso e Logs fornece visibilidade operacional do tráfego da API. As equipes podem inspecionar o volume de solicitações, modelos selecionados, destinos de roteamento resolvidos, consumo de créditos, latência, códigos de erro e IDs de solicitação.

• Solucione falhas em solicitações.
• Identifique cargas de trabalho de alto custo.
• Compare o uso de modelos entre aplicações e ambientes.
• Valide o comportamento de roteamento e fallback.
• Investigue problemas de latência ou disponibilidade do provedor.
• Forneça IDs de solicitação ao contatar o suporte.

Cada resposta da API inclui ou expõe um ID de solicitação do BasicRouter. Armazene este ID nos logs da sua aplicação para tornar a depuração de produção e a escalonamento de suporte mais eficientes.

Fallback

O Fallback é o mecanismo de resiliência do BasicRouter. Quando o modelo principal ou a política de roteamento falha, o sistema alterna automaticamente para um modelo de backup para continuar processando a solicitação. Isso mantém sua aplicação responsiva e minimiza o risco de interrupção do serviço.

Por que o fallback é importante

Em produção, os serviços de modelo podem enfrentar vários problemas imprevisíveis:

• Falha no serviço do modelo: a API upstream fica temporariamente indisponível ou atinge o tempo limite.
• Flutuação de desempenho: alta carga do modelo leva a respostas lentas ou com falha.
• Falha de roteamento: todos os modelos candidatos selecionados pelo roteamento inteligente ficam indisponíveis.

O Fallback mantém sua aplicação disponível fornecendo um caminho de backup confiável.

Principais vantagens

Configuração de modelo de fallback global

O BasicRouter suporta a definição de um modelo de fallback global no backend do console. Todas as solicitações usam automaticamente este modelo como backup quando falham.

Como configurar:

1. Acesse a página de configurações de estratégia do BasicRouter.
2. Encontre a configuração de Modelo de Fallback Padrão.
3. Selecione seu modelo de fallback global na lista suspensa.
4. Salve a configuração para aplicá-la imediatamente.

Vantagens da configuração global:

• Sem alterações de código: configure uma vez e aplica-se globalmente, sem necessidade de repetir a configuração em cada solicitação.
• Gerenciamento centralizado: gerencie a política de fallback em um único local para ajuste e monitoramento mais fáceis.
• Manutenção simplificada: reduz a complexidade do código e a chance de erros de configuração.
• Substituição flexível: a configuração de fallback no nível da solicitação tem prioridade e pode substituir a configuração global para cenários específicos.

Configuração de fallback no nível da solicitação

Para cenários de negócio específicos, você pode especificar um modelo de fallback em uma solicitação individual para substituir a configuração global.

Especifique o modelo de fallback com o parâmetro router.fallBackModels:

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

Regras de prioridade

Quando várias configurações de fallback estão presentes, a prioridade vai da mais alta para a mais baixa:

1. router.fallBackModels no nível da solicitação: o modelo de fallback especificado em uma solicitação individual.
2. Global Default Fallback Model: the global fallback model configured in the console.
3. No fallback: if neither is configured, the request returns an error on failure.

Administração da conta

Dependendo do tipo de conta, o console pode incluir ativação de modelos no nível da conta, controles de revendedor ou distribuidor, configuração de cobrança e configurações de acesso. Os administradores podem usar esses controles para alinhar o acesso a modelos, a visibilidade de uso e a responsabilidade de cobrança com aplicações, contas de cliente ou unidades de negócio.

Lista de verificação de operações de produção

Cobrança e créditos

O BasicRouter usa um modelo de cobrança baseado em créditos para cargas de trabalho de texto, imagem, vídeo e outros modelos suportados. Os créditos fornecem uma unidade unificada para uso de múltiplos modelos e múltiplos provedores, permitindo que as equipes gerenciem o consumo de forma consistente entre modalidades e famílias de API.

Os preços detalhados dos modelos estão disponíveis na página de Modelos ou através das APIs de metadados de modelo. O preço pode variar por modelo, provedor, modalidade, resolução, tipo de token, compramento de saída, duração da tarefa, tipo de conta e acordo comercial.

Recarga e carteira

As contas podem adicionar créditos de carteira pré-pagos para uso flexível. Os créditos da carteira são usados após os créditos do plano mensal e dos pacotes de recursos serem consumidos, a menos que uma regra billing rule applies to the account.

Os créditos da carteira não expiram, salvo especificação em contrário nos termos comerciais aplicáveis. Uma taxa de serviço é cobrada ao recarregar a carteira pré-paga.

Planos mensais e pacotes de recursos

Cada usuário ou conta pode selecionar um plano mensal ativo. Os planos mensais fornecem uma quantidade definida de capacidade de uso, termos comerciais e configuração de acesso no nível da conta para o período de cobrança.

Os usuários também podem comprar vários pacotes de recursos para capacidade de uso adicional. Os pacotes de recursos podem separar o uso comprometido do saldo da carteira pré-paga e são úteis para uso de alto volume de texto, imagem, vídeo ou cargas de trabalho dedicadas.

Ordem de dedução

A menos que regras de cobrança personalizadas estejam configuradas, os créditos são deduzidos na seguinte ordem:

Para contas com termos comerciais personalizados, a ordem de dedução, regras de expiração, uso incluído e preços podem ser diferentes. As regras específicas da conta são mostradas no console ou fornecidas através do acordo comercial.

Preços personalizados

Os preços podem ser personalizados para cada usuário ou conta. Clientes corporativos, contas de revendedor, contas de distribuidor e clientes de alto volume podem ser elegíveis para preços personalizados. Entre em contato com as vendas para uma cotação.

Os preços personalizados podem ser configurados por conta, modelo, provedor, modalidade, região, volume de uso ou acordo comercial. Quando os preços personalizados são ativados, o console e as APIs de cobrança refletem os preços e regras de dedução específicos da conta quando disponíveis.

Unidades de preço

Different model modalities use different measurement units. BasicRouter converts these units into credits according to the model’s pricing rules.

As unidades de preço podem variar por modelo. Sempre consulte a página de detalhes do modelo ou os metadados de preço antes de ativar um modelo em produção.

Atribuição de uso

O uso do BasicRouter pode ser revisado por conta, chave API, modelo, modalidade ou intervalo de tempo. Isso permite que as equipes atribuam custos a aplicações, ambientes, clientes ou unidades de negócio internas.

Saldo de créditos

Verifique quantos créditos estão disponíveis em sua conta. O saldo é dividido em três carteiras que são deduzidas em ordem: a allowances do plano mensal, pacotes de recursos comprados e a carteira pré-paga. Um total combinado de recursos (plano mensal + pacotes de recursos, excluindo o pré-pago) também está disponível para rastrear o uso incluído separadamente dos gastos de recarga.

Para recuperar isso programaticamente, consulte GET /v1/billing/balance na Referência da API.

Detalhes de uso

Revise uma lista paginada e cronológica de registros de uso individuais para relatórios, monitoramento e alocação interna de custos. Cada registro mostra o modelo, tipo de modelo (texto, imagem ou vídeo), os créditos deduzidos e um detalhamento de qual carteira cada dedução foi retirada. Os resultados podem ser filtrados por um intervalo de tempo específico.

Para recuperar isso programaticamente, consulte GET /v1/usage na Referência da API.

Histórico de transações

Use o histórico de transações para revisar movimentações de créditos, incluindo recargas, alocações de plano, concessões de pacotes de recursos, deduções de uso, ajustes e correções administrativas.

Para recuperar isso programaticamente, consulte GET /v1/billing/transactions na Referência da API.

Solicitações com falha e reembolsos

Erros de validação, erros de autenticação e erros de permissão geralmente não são cobrados porque nenhuma execução de modelo ocorre. Solicitações que alcançam um modelo upstream ou geram saída parcial podem consumir créditos dependendo do modelo, provedor e estado da resposta.

Para tarefas assíncronas de imagem e vídeo, o comportamento de cobrança depende se a tarefa foi aceita, iniciada, concluída, falhou ou foi cancelada. A resposta de detalhes da tarefa inclui informações de uso quando os créditos foram consumidos.

Recargas, planos mensais, pacotes de recursos e créditos consumidos não são reembolsáveis, a menos que especificado de outra forma no acordo comercial aplicável ou exigido por lei.

Referência da API

Convenções comuns

URL base

Todos os endpoints são servidos sob o prefixo /v1.

Autenticação

Chamadas para endpoints /v1/* usam autenticação por Chave API (não JWT). A Chave API é passada pelo seguinte cabeçalho:

Chaves ausentes ou inválidas retornam 401.

Pré-verificação de saldo

Todos os endpoints de chamada de modelo executam uma pré-verificação de saldo antes da execução:

• Insufficient balance returns Insufficient credit, mapped to:
  • Protocolo OpenAI: HTTP 400, code = insufficient_quota
  • Protocolo Anthropic: HTTP 402, type = billing_error
• Alguns endpoints também estimam um custo mínimo por modelo para uma segunda pré-verificação.

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

Endpoint compatível com OpenAI Chat Completions. Suporta streaming e não streaming, chamadas de ferramentas, modo JSON e 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 resposta (não streaming):

Exemplo de resposta em 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 compatível com OpenAI Responses. Usa input em vez de messages, instructions em vez de uma mensagem de sistema, e um bloco text em vez 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 resposta (não streaming):

O streaming segue os eventos da API Responses:

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

Endpoint compatível com Anthropic Messages. Aceita cabeçalhos x-api-key e anthropic-version: 2023-06-01. Os blocos de conteúdo suportam text, image, tool_use, tool_result, thinking e redacted_thinking.

Exemplos de bloco de imagem:

{ "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 resposta (não streaming):

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

Retorna todos os modelos de API online e ativados.

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}

Retorna um único modelo com o mesmo formato de uma entrada de lista. Retorna HTTP 404 quando o modelo não existe.

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

Resposta de sucesso: um objeto de modelo único com os mesmos campos de uma entrada de lista /v1/models.

Quando o modelo não existe, retorna 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

Consulte as resoluções, proporções e contagens máximas suportadas por um modelo de imagem antes de chamar /v1/image-generations. Não requer autenticação.

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

Consulte os valores de videoType suportados, intervalo de duração, resoluções e proporções para um modelo de vídeo antes de chamar /v1/video-generations. Não requer autenticação.

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

Envie assincronamente uma tarefa de geração de imagem. Retorna um taskId imediatamente; recupere o resultado fazendo polling de GET /v1/image-generations/{taskId} ou via webhook callbackUrl.

O model, os valores de resolution / ratio suportados, o limite máximo de count e o limite de upload de imagens de referência (fileMax) devem ser obtidos primeiro em GET /v1/image-models. Apenas os valores divulgados na especificação do modelo são aceitos.

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

Respostas de erro:

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

Faça polling de uma tarefa de geração de imagem. status é pending / success / failed. images é um array em string JSON de URLs de imagem; text contém qualquer descrição de texto anexada pelo modelo (ex. saída multimodal do Gemini), null caso contrário.

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 data da resposta:

Tarefa não encontrada:

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

Se callbackUrl foi fornecido no envio, o servidor envia o resultado final success / failed via webhook com o mesmo formato de data.

Exemplo completo (envio + polling)

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

Envie assincronamente uma tarefa de geração de vídeo. Retorna um taskId imediatamente; recupere o resultado fazendo polling de GET /v1/video-generations/{taskId} ou via webhook callbackUrl.

O model, os valores de videoType permitidos, o intervalo de duração (videoDurationMin/Max), resolution / ratio suportados e o limite de upload de ativos de referência (fileMax) devem ser obtidos primeiro em GET /v1/video-models. Apenas códigos de videoType listados em allowedVideoTypes do modelo são aceitos.

Exemplos para cada videoType:

1. Texto para vídeo (videoType=1)

Gere um vídeo apenas a partir de um prompt de texto; não são necessários ativos de referência.

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. Imagem para vídeo - primeiro quadro (videoType=2)

Forneça um único quadro inicial em imageUrls; o modelo gera um vídeo a partir desse quadro.

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. Imagem para vídeo - primeiro e último quadro (videoType=3)

Forneça o primeiro e o último quadro em imageUrls (ordem: [primeiro, último]); o modelo gera um vídeo de transição entre os dois quadros.

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. Imagem para vídeo - referência (videoType=4)

Forneça uma ou mais imagens de referência em imageUrls; o modelo usa o estilo/conteúdo delas como referência (não como um primeiro/último quadro forçado) para gerar o vídeo.

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. Todas as referências (videoType=5)

Referências mistas de imagem / vídeo / áudio. Faça referência aos ativos por posição no prompt: a 1ª entrada em imageUrls é @图片 1, a 1ª em videoUrls é @视频 1, a 1ª em audioUrls é @音频 1. videoUrls também aceita strings 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
  }'

Resposta de envio (todos os cinco tipos):

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

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

Faça polling de uma tarefa de geração de vídeo. status é pending / success / failed; videoUrl é a URL do vídeo gerado e lastFrameUrl é a URL do último quadro (cenários de imagem-para-vídeo).

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 data da resposta:

Se callbackUrl foi fornecido no envio, o servidor envia o resultado final via webhook com o mesmo formato de data.

Exemplo completo (envio + polling)

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

Retorna o saldo da conta dividido em três carteiras: plano mensal, pacotes de recursos e crédito pré-pago.

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 resposta:

Campos de WalletDetailVO:

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

Detalhes de cobrança paginados de chamadas de modelo, com snapshot por preço (priceSnapshotId), ordenados por tempo de criação do pedido em ordem decrescente. Apenas registros de cobrança normal (reason = model usage) são retornados.

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"

Wrapper de resposta:

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

Campos de UsageDetailVO:

Campos de CreditDetailItem:

Convenção de valor nulo: apenas os campos relevantes para cada modelType são preenchidos; o restante é null. text preenche os campos de token; image preenche imageCount/imageResolution/imageRatio; video preenche videoResolution/videoRatio/videoDurationSec.

Exemplo de resposta:

{
  "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 das transações de recarga pagas (status=2) do usuário atual, ordenadas por created_at em ordem decrescente.

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"

Wrapper de resposta:

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

Operacional

Erros

O BasicRouter retorna códigos de erro estáveis para que as aplicações possam lidar com repetições, fallbacks, problemas de cobrança e depuração de forma consistente.

Endpoints compatíveis com provedores tentam preservar o formato de erro da família de API original quando possível. Endpoints nativos do BasicRouter usam o objeto de erro do BasicRouter.

Mapeamento de status HTTP e códigos de erro

Códigos de erro comuns