Modelos e roteamento

UberLLM envia cada requisição para um provedor terceirizado disponível para o modelo que você solicitou. Se o provedor falhar antes de começar a responder, a requisição é tentada novamente, e uma requisição que ainda falha não é cobrada. Cada requisição é cobrada pelo que o provedor cobrou, sem taxa UberLLM adicionada, e é listada com seu custo em Dashboard → Activity. Você escolhe um modelo, não um provedor.

IDs de modelo

Use o ID do modelo do catálogo, por exemplo deepseek/deepseek-v4-flash, anthropic/claude-sonnet-5 ou z-ai/glm-5.3. Liste o que você pode chamar agora:

GET https://api.uberllm.dev/v1/models: os modelos de chat para os quais uma requisição pode ser enviada agora, assim, uma ferramenta que preenche seu menu de modelos a partir desta lista (SillyTavern, LibreChat, n8n, Cline) mostra apenas modelos com os quais ela pode conversar. Adicione ?type=video (ou image, music, speech, transcription, audio para ambos, chat, vários unidos por vírgulas) para outros tipos, ou ?type=all para todos os modelos, chat primeiro, depois imagem, vídeo, música, fala e transcrição. Cada entrada tem type (chat, image, video, music, speech, transcription), endpoints (os caminhos que o servem) e pricing.
Cada modelo de chat também diz o que ele pode fazer: context_length, max_output_tokens, input_modalities (image = ele lê imagens), supports_tools, supports_reasoning, supports_vision e supported_parameters (os campos de requisição que ele aceita). Os mesmos fatos estão sob os nomes do OpenRouter também (architecture.input_modalities, top_provider.context_length, top_provider.max_completion_tokens, e pricing.prompt / pricing.completion em dólares por token), então ferramentas construídas para a lista do OpenRouter leem a nossa como está.
GET https://api.uberllm.dev/v1/models/<model id>: um modelo, com seu preço, seu contexto (chat) e, para um modelo de mídia, parameters: um JSON Schema do corpo da requisição (veja Criar um vídeo ou imagem).
Cada entrada, em ambas as respostas, também tem:
- available: true quando uma requisição para ele pode ser atendida agora. false significa que ninguém o está servindo no momento, então uma requisição seria recusada com no_available_provider. Escolha outro modelo ou tente novamente mais tarde.
- input_modalities: o que o modelo aceita. Um modelo que precisa de uma imagem (imagem para vídeo, referência para vídeo, edição de imagem) lista "image" ao lado de "text"; um que aceita um vídeo (upscaling) lista "video".
- nsfw: true para um modelo feito para conteúdo adulto ou não filtrado (Lustify, os modelos "sem censura" e similares). Pule estes se seu produto deve permanecer seguro para o trabalho.
Público, sem chave: GET https://api.uberllm.dev/api/v1/public/models (com preços, e os mesmos campos available, input_modalities e nsfw)
Web: uberllm.dev/#models, e uma página por modelo em uberllm.dev/models/<model id>

O que acontece em cada requisição

UberLLM verifica se o modelo existe, se o seu prompt se encaixa na janela de contexto dele e se ele suporta ferramentas caso sua requisição as utilize.
Ele reserva o custo estimado do seu saldo e encaminha a requisição.
A requisição é enviada para um provedor disponível para aquele modelo. O provedor é escolhido novamente para cada chamada: o mais barato que começa a responder rápido o suficiente para o tamanho do seu prompt (dentro de 2x do mais rápido medido, ou em menos de 1 segundo). Um prompt longo em streaming também vai para um segundo provedor rápido quando o primeiro demora para começar; você recebe e paga por uma resposta. Nomear provedores em provider.only, ignore ou order, ou definir sort, substitui esta escolha. Como funciona: roteamento inteligente.
Quando a resposta termina, UberLLM liquida o preço que o marketplace reporta para aquela chamada e libera o restante da reserva.

Tentativas automáticas

Se uma chamada falhar antes que qualquer conteúdo chegue até você, o UberLLM a tenta novamente para você. O marketplace encontra um novo vendedor a cada tentativa, e não cobra nada por uma chamada que falhou antes de ser roteada, então uma nova tentativa custa apenas seu tempo.

Com tentativa: nenhum vendedor para o modelo no momento (no_sellers_for_model, no_healthy_sellers), o marketplace ficou sem tempo para rotear (route_deadline_exceeded), um 429 pedindo para esperar 5 segundos ou menos, qualquer 5xx, um erro de conexão, um vendedor cuja própria chave ou conta de provedor falhou, ou nenhum primeiro byte a tempo.
Sem tentativa: o modelo não existe, a requisição é inválida, ou um problema de faturamento ou autenticação. Esses retornam imediatamente.
Agendamento: até 4 tentativas, esperando 0.3 s, 0.9 s, depois 2.7 s entre elas (ou o Retry-After que o marketplace enviou, se for 5 segundos ou menos). Quando ninguém está vendendo o modelo, a resposta retorna em poucos segundos.
Esperando pelo primeiro byte: um stream recebe 10 segundos (mais para um prompt longo, e mais para um modelo que geralmente é lento); uma resposta sem "stream": true recebe 85 segundos, porque nada chega até que esteja completa. Uma tentativa que esgota os 85 segundos completos não é esperada uma segunda vez. Nenhuma nova tentativa começa após 150 segundos.

Uma vez que o streaming tenha começado, nada é tentado novamente: uma falha no meio do stream encerra o stream e você é cobrado apenas pelo que foi produzido.

Se todas as tentativas falharem, você recebe um erro em vez de uma resposta, e a reserva é totalmente liberada. Os mais comuns:

HTTP	`code`	Quando
503	`no_available_provider`	Ninguém conseguiu servir esse modelo no momento, mesmo após as tentativas: nenhum vendedor, todos os vendedores falhando ou muito lentos para iniciar, ou suas opções `provider` não deixaram nada para rotear. A mensagem nomeia o modelo. Tente novamente em breve ou escolha outro modelo.
503	`service_unavailable`	Um problema temporário do lado do UberLLM. Tente novamente em alguns minutos.
404	`model_not_found`	O ID do modelo não está disponível.

Veja Erros para a lista completa.

Modelos de fallback

Envie models com uma lista de outros IDs de modelo para tentar, em ordem, quando o primeiro não puder ser atendido:

{ "model": "deepseek/deepseek-v4-flash",
  "models": ["z-ai/glm-5.3", "qwen/qwen3.6-plus"],
  "messages": [{ "role": "user", "content": "hi" }] }

O próximo modelo é tentado apenas quando ninguém puder atender o anterior agora (no_available_provider), ou ninguém o vender dentro do seu provider.max_price. Um erro de requisição (um body inválido, um ID de modelo desconhecido em qualquer um dos campos) e uma recusa de pagamento (saldo, limites da chave) são respondidos imediatamente e nunca passados para a lista. No máximo 5 modelos em model e models juntos. O campo model da resposta e a linha de Atividade nomeiam o modelo que respondeu. models funciona em /v1/chat/completions e em requisições de imagem, vídeo, música e fala; /v1/messages e /v1/audio/transcriptions não o leem.

Aliases de modelo

Em vez de um ID de modelo, você pode nomear o que precisa, e o UberLLM escolhe o modelo em cada requisição:

best-price:<job>: o modelo disponível com o menor preço para uma requisição comum. Um modelo de chat é comparado pelo seu preço por milhão de tokens com a saída contada três vezes; um modelo de imagem por uma imagem (uma imagem de 1024×1024 quando precificado por megapixel); um modelo de vídeo pelo seu clipe mais curto; um modelo de música por uma faixa; um modelo de fala por 1K caracteres; um modelo de transcrição por um minuto.
fastest:<job>: o modelo com o menor tempo mediano em suas requisições bem-sucedidas no UberLLM nos últimos 7 dias (tempo até o primeiro token para chat, tempo até o arquivo finalizado para mídia), contando apenas modelos com pelo menos 5 dessas requisições. Quando nenhum modelo tem o suficiente, a requisição é recusada com 503 no_timing_data, e best-price: ainda funciona.

Ambos escolhem apenas entre os modelos que estão disponíveis agora: o mercado ao vivo mostra um vendedor saudável para ele, e a última requisição do UberLLM para ele nos últimos 10 minutos não encontrou todos os vendedores ocupados ou inativos (a mesma regra que available em /v1/models). Em uma rota de mídia, quando o modelo que um alias escolheu responde que ninguém pode atender à requisição afinal, a mesma requisição passa para o próximo modelo que o alias representa (até 3 modelos), e o model da resposta nomeia aquele que respondeu. Quando nenhum modelo para o trabalho está disponível, a resposta é 503 no_available_provider e nada é cobrado.

<job> é um de chat, image, image-edit, text-to-video, image-to-video, music, speech, transcription. Envie um alias de chat para /v1/chat/completions ou /v1/messages, e um de mídia para sua rota de mídia. O campo model da resposta nomeia o modelo para o qual foi resolvido. GET /v1/models/aliases lista cada alias que se resolve agora e seu modelo; GET /v1/models/best-price:chat descreve o modelo que ele representa, com alias definido.

Opções de roteamento

O objeto provider é lido em /v1/chat/completions. Uma opção que o UberLLM não pode aplicar é recusada com 400 unsupported_routing_option e nada é cobrado, então uma requisição nunca é executada com uma configuração silenciosamente ignorada.

Opção	O que faz
`only` / `allow`	Apenas estas rotas ou provedores. `uberllm` (a rota de marketplace do UberLLM) e `seller` (ofertas próprias dos vendedores) escolhem entre nossas rotas. Qualquer outro nome, como `openai` ou `api.venice.ai`, é um provedor no marketplace: a requisição então passa pela rota `uberllm`, que usa apenas ofertas desses provedores.
`ignore` / `deny`	Nunca estes. Nomes de rotas como acima. Nomes de provedores (no máximo 32) são recusados no marketplace, e a requisição então passa pela rota `uberllm`.
`order`	Ordem preferida. Nomes de rotas ordenam nossas rotas; nomes de provedores definem a ordem de tentativa do marketplace. Nunca torna um provedor elegível ou inelegível.
`sort`	`price` (o padrão), `latency` (o mais rápido observado primeiro, dentro de uma faixa de preço) ou `uptime` (o mais confiável primeiro, dentro da mesma faixa). `throughput` ordena apenas nossas próprias rotas.
`max_price`	O máximo que você paga por milhão de tokens, em dólares americanos: `{ "prompt": 1.0, "completion": 3.0 }`. Rotas com preço acima são ignoradas; a rota do marketplace é mantida para vendedores pelo menos tão abaixo do preço de tabela do modelo quanto seu teto exige. Se nada restar, a requisição é recusada com `400 max_price_exceeded` e nada é cobrado. Quando você define `prompt` e `completion`, uma requisição nunca é cobrada acima deles pelos tokens que usou.
`allow_fallbacks`	`false` desativa as tentativas automáticas acima; a primeira falha é retornada a você.
`data_collection`	Apenas `"allow"` (o padrão) é aceito.
`zdr`, `require_parameters`	Apenas `false` é aceito.

Os sufixos de modelo :floor e :nitro são aceitos e removidos do ID do modelo; :floor ordena por preço e :nitro por throughput.

Para imagem, vídeo, música e fala, cada requisição é enviada a um provedor terceirizado disponível para o modelo. provider.max_price é o máximo que uma unidade (imagem, segundo, megapixel, minuto, 1K caracteres ou requisição) pode custar, como um número: { "max_price": 0.05 }; também limita a cobrança. Qualquer outra opção provider é recusada para mídia.