Modelos e roteamento
MartLLM 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 MartLLM 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.martllm.com/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(ouimage,music,speech,transcription,audiopara ambos,chat, vários unidos por vírgulas) para outros tipos, ou?type=allpara todos os modelos, chat primeiro, depois imagem, vídeo, música, fala e transcrição. Cada entrada temtype(chat,image,video,music,speech,transcription),endpoints(os caminhos que o servem) epricing.- 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_visionesupported_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, epricing.prompt/pricing.completionem dólares por token), então ferramentas construídas para a lista do OpenRouter leem a nossa como está. GET https://api.martllm.com/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:truequando uma requisição para ele pode ser atendida agora.falsesignifica que ninguém o está servindo no momento, então uma requisição seria recusada comno_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:truepara 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.martllm.com/api/v1/public/models(com preços, e os mesmos camposavailable,input_modalitiesensfw) - Web: martllm.com/#models, e uma página por modelo em
martllm.com/models/<model id>
O que acontece em cada requisição
- O MartLLM verifica se o modelo existe, se o seu prompt se encaixa na janela de contexto 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 a um provedor disponível para aquele modelo. Com o roteamento padrão Balanceado, 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 6x do mais rápido medido, ou em menos de 1 segundo). Esse provedor pode ter um preço acima do preço listado, e a chamada então custa o que ele cobrou. Um prompt longo em streaming também vai para um segundo provedor rápido quando o primeiro demora para começar, e uma chamada que não começou após 5 segundos pode ser movida para um provedor mais rápido; você recebe e paga por uma única resposta. A configuração de roteamento da sua chave (abaixo) ou
sortna requisição muda isso. Como funciona: roteamento inteligente. - Quando a resposta termina, o MartLLM 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 MartLLM 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), um429pedindo para esperar 5 segundos ou menos, qualquer5xx, 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-Afterque 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": truerecebe 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 MartLLM. 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.7-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 MartLLM 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 MartLLM 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 com503 no_timing_data, ebest-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 MartLLM 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.
Configuração de roteamento da sua chave
Cada chave de API tem uma configuração de roteamento, em Painel → Chaves de API (crie uma chave ou edite uma):
| Configuração | O que faz |
|---|---|
| Balanceado (padrão) | Rápido e barato: o provedor mais barato que começa rápido o suficiente, conforme descrito acima. Um provedor mais rápido e com preço acima do preço listado pode responder, e a chamada custa o que ele cobrou. |
| Preço mais baixo | Sempre o provedor com o preço mais baixo para a solicitação. Nenhum provedor mais rápido e mais caro é escolhido, nenhum segundo provedor é disputado, e uma chamada lenta não é movida. Pode ser mais lento. |
| Mais rápido | O provedor que começa a responder primeiro, custe o que custar (o mesmo que "sort": "latency"). |
| Nunca cobrar mais do que o preço listado | Ligado ou desligado, com qualquer um dos três. Uma solicitação é enviada apenas para provedores com preço igual ou inferior ao preço listado do modelo quando a solicitação chegou, e nunca é cobrada acima do custo de seus tokens a esse preço. Se nenhum provedor vender a esse preço agora, a solicitação é recusada com 400 max_price_exceeded e não custa nada. |
| Desconto mínimo | 0–99%, com qualquer um dos acima (vazio ou 0 = sem mínimo). Uma solicitação de chat é enviada apenas para provedores que vendem pelo menos essa porcentagem abaixo do preço oficial do modelo, entrada e saída cada, e nunca é cobrada acima dessa % de desconto do custo de seus tokens ao preço oficial (o mesmo preço oficial que a "% de desconto" da Atividade usa). Se nenhum provedor for tão barato agora, a solicitação é recusada com 400 max_price_exceeded e não custa nada. Um modelo sem preço oficial é recusado da mesma forma, porque o desconto não pode ser medido. |
Imagens e vídeo também seguem a configuração da chave (desde 19 de novembro de 2026). Muitos modelos de imagem e vídeo têm mais de um vendedor, e um vendedor pode ter mais de uma forma de criar um modelo (um mais barato e lento, e um mais caro e rápido). Medimos o tempo que cada um leva e contamos a frequência com que cada um falha. O mercado de vendedores é classificado na mesma lista que os vendedores diretos, com seu próprio preço e velocidade.
- O padrão (
auto, toda chave que não escolheu outra): o vendedor mais barato que faz exatamente o que você pediu. Ele só ignora um vendedor que continua falhando, ou um que é mais de duas vezes mais lento que o mais rápido que cronometramos. Assim, uma chave que nunca mudou sua configuração não paga mais por um pequeno ganho de velocidade. - Balanceado (
balanced): o vendedor mais barato que é no máximo 20% mais lento que o mais rápido que cronometramos. Um vendedor que ainda não cronometramos é considerado rápido o suficiente. Escolha esta opção quando um resultado mais rápido vale um preço mais alto. - Preço mais baixo (
cheapest): sempre o vendedor mais barato que faz exatamente o que você pediu, por mais lento que seja. - Mais rápido (
fastest): o vendedor que cronometramos como o mais rápido. Pode custar mais do que o vendedor mais barato, mas nunca mais do que o preço listado do modelo para sua solicitação.
Um vendedor é cronometrado depois de ter concluído pelo menos 3 trabalhos para o modelo nos últimos 7 dias; enquanto nenhum é cronometrado, cada configuração escolhe o mais barato. Um vendedor que fez menos de 7 em 10 de seus trabalhos recentes (10 ou mais tentativas) vem depois dos saudáveis em todas as configurações, e o tempo que comparamos é o tempo que se espera que um trabalho leve: um vendedor que perde um trabalho em cinco é considerado 25% mais lento. O preço em uma cotação ("validate": true) e o estimated_cost_usd de um trabalho são o preço do vendedor que a configuração da sua chave escolhe, e é isso que o trabalho é cobrado quando o vendedor cobra o que lista. Se esse vendedor não puder aceitar o trabalho, o próximo na mesma ordem o faz.
A configuração se aplica quando uma solicitação não especifica. O próprio provider.sort, :floor / :nitro, ou provider.max_price de uma solicitação prevalece sobre ela. provider.only: ["uberllm"] não é uma ordenação, então a configuração da chave ainda se aplica. O desconto mínimo é a exceção: ele sempre se aplica, e junto com o próprio provider.max_price de uma solicitação, o preço mais rigoroso prevalece.
Através da API do painel: routing (auto, balanced, cheapest ou fastest; para texto, balanced é o mesmo que auto) e price_cap_listed (verdadeiro/falso) e min_discount_pct (número inteiro 0–99) em POST /api/v1/keys e PATCH /api/v1/keys/{id}; todos são retornados por GET /api/v1/keys.
Opções de roteamento
O objeto provider é lido em /v1/chat/completions. Uma opção que o MartLLM
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 MartLLM) 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.
Tags
Envie metadata, um objeto de até 16 valores de texto (chaves de até 64 caracteres sem dois pontos, valores de até 512), em qualquer requisição:
{ "model": "deepseek/deepseek-v4-flash", "messages": [...],
"metadata": { "project": "spring-ads", "run": "42" } }
As tags são armazenadas com a requisição e nunca enviadas a um provedor. Elas aparecem na requisição em Dashboard → Atividade, no status de um trabalho de vídeo ou música, e na exportação CSV (coluna metadata). Filtre a Atividade por uma tag com GET /api/v1/usage/activity?tag=project:spring-ads (repita tag para exigir várias); o link CSV aplica o mesmo filtro. Em /v1/messages, o próprio metadata ({"user_id": "…"}) da Anthropic é armazenado da mesma forma.