API do DeepSeek V4 para Programação: Roteamento do deepseek-v4-pro e deepseek-v4-flash

Enviar cada etapa de uma sessão de programação para um único modelo é a política de roteamento mais fácil e, geralmente, a mais cara. Este tutorial mostra como usar a API DeepSeek V4 para programação no TokenLab, dividindo o trabalho entre deepseek-v4-pro e deepseek-v4-flash. Lemos ambos os registros de modelo da API ao vivo em 03/10/2026, e tudo abaixo provém desses registros e da documentação do TokenLab. Você encontrará uma tabela comparativa, uma estimativa de custo detalhada, uma solicitação de tool-calling, código de retry e fallback, e uma verificação de preflight.

Principais pontos

• Ambos os modelos listam um limite de entrada de 1.000.000 de tokens, um limite de saída de 384.000 tokens e os mesmos três formatos de solicitação. O preço é a principal diferença entre eles.
• Nos preços de tabela, o deepseek-v4-pro custa 4,4 vezes mais que o deepseek-v4-flash por token de entrada e 3,3 vezes mais por token de saída.
• Em nosso exemplo de 20 chamadas, rotear 4 chamadas para o pro e 16 para o flash custa cerca de $0,18 fora do horário de pico. Enviar todas as 20 para o pro custa cerca de $0,46.
• Faça retry de 429 após Retry-After. Faça retry de 500–504 apenas quando retryable for true. Nunca faça retry de 400, 401, 402, 403, 404 ou 413 sem alterações.
• O catálogo lista o deepseek-v4.1-flash como ativo. Nem deepseek-v4-pro nem deepseek-v4-flash nomeiam um modelo de substituição.
• Leia limites, formatos e preços de GET /v1/models/:model antes de rotear. Não faça hard-code de uma tabela copiada.

A API DeepSeek V4 para Programação: O que diz o catálogo

Buscamos ambos os registros em 03/10/2026. A tabela abaixo os compara lado a lado. Os preços estão em USD por 1 milhão de tokens, e a precificação do catálogo foi atualizada pela última vez em 02/10/2026T16:53:30.068Z.

Item	deepseek-v4-pro	deepseek-v4-flash	Fonte, observado em 03/10/2026
Limite de contexto (máx. tokens de entrada)	1.000.000	1.000.000	pro, flash
Limite de saída (máx. tokens de saída)	384.000	384.000	pro, flash
Formatos de solicitação aceitos	anthropic_messages, openai_chat_completions, openai_responses	anthropic_messages, openai_chat_completions, openai_responses	pro, flash
Capacidades	json-mode, prompt-cache, tool-use	json-mode, prompt-cache, tool-use	pro, flash
Entrada fora do pico	$0,66	$0,15	pro, flash
Saída fora do pico	$1,98	$0,60	pro, flash
Leitura de cache fora do pico	$0,022	$0,003	pro, flash
Escrita de cache fora do pico	$0,66	não listado	pro, flash
Entrada no pico	$1,32	$0,30	pro, flash
Saída no pico	$3,96	$1,20	pro, flash
Leitura de cache no pico	$0,044	$0,006	pro, flash
Estágio do ciclo de vida	ativo, lançado em 24/04/2026	ativo, lançado em 24/04/2026	pro, flash

O bloco de preço padrão em cada registro corresponde à entrada fora do pico. O horário de pico difere por registro. Para o deepseek-v4-pro, os preços de pico aplicam-se das 09:00 às 12:00 e das 14:00 às 18:00 no horário de Pequim. Para o deepseek-v4-flash, o registro diz que as janelas de pico aplicam-se em dias úteis, excluindo feriados públicos da China. Diz que fora do pico inclui fins de semana e feriados, mas não fornece horários. Verifique o endpoint de precificação antes de orçar em torno da janela do flash.

Ciclo de vida e modelos DeepSeek mais recentes

Ambos os registros mostram lifecycle stage active, com replacement model, deprecated_at e retired_at todos vazios. Portanto, o catálogo não agenda nenhum dos modelos para remoção e não nomeia nenhum sucessor para eles.

O catálogo também lista o deepseek-v4.1-flash. Seu registro, observado em 03/10/2026, está ativo, sem data de lançamento e sem substituto. Ele possui os mesmos limites, formatos e preços de tabela que o deepseek-v4-flash. Ele adiciona reasoning e vision à lista de capacidades e mostra um preço de escrita de cache de $0,15 fora do pico.

Esse é um ID de modelo separado, então este artigo mantém seu assunto. Recomendamos testar o deepseek-v4.1-flash em suas próprias tarefas antes de trocá-lo. O catálogo também lista o deepseek-v4-flash-vision-exp, mas não lemos seu registro. Verifique-o na página de Modelos se precisar.

Roteamento de deepseek-v4-pro e deepseek-v4-flash por tarefa

Imagine uma sessão de agente que planeja uma mudança em cinco módulos, escreve as edições e, em seguida, gera uma dúzia de stubs de teste. A primeira etapa precisa de mais contexto e cuidado. A última é repetitiva e barata de refazer. O catálogo não pode dizer onde a linha de qualidade se situa. O guia do TokenLab sobre modelos de agente de codificação, observado em 03/10/2026, diz que os resultados dos leaderboards não preveem como um modelo segue suas próprias instruções e ferramentas.

Nossa heurística inicial assume que o modelo mais caro compensa seu custo em trabalhos entre arquivos. Trate isso como uma hipótese a ser testada, não como uma descoberta:

+-------------------------------------------------------------+
|                      Tarefa Recebida                        |
+-------------------------------------------------------------+
                               |
         [A tarefa envolve contexto de vários arquivos,
          compatibilidade retroativa ou revisão de segurança?]
                               |
               +---------------+---------------+
               |                               |
             [Sim]                            [Não]
               |                               |
               v                               v
       deepseek-v4-pro                 deepseek-v4-flash

Critérios que levam uma etapa para o deepseek-v4-pro:

• Modificar lógica em vários arquivos importados.
• Avaliações de segurança ou vulnerabilidade.
• Compatibilidade retroativa rigorosa em interfaces públicas.
• Trabalho de múltiplos turnos onde a precisão importa mais que o tempo de resposta.

Estruturas de teste independentes, formatação de esquema, docstrings e conclusão de sintaxe vão para o deepseek-v4-flash.

Para testar a heurística, siga o mesmo guia. Dê a cada modelo o mesmo estado de repositório, instruções, ferramentas e limite de tempo. Em seguida, compare a correção, testes aprovados, mudanças desnecessárias, total de tokens, custo final e com que frequência uma pessoa precisou intervir. Mantenha os resultados por tipo de tarefa, porque um modelo pode revisar bem e implementar mal.

Estimando o custo de um loop de agente de codificação

Agentes reenviam instruções, histórico, código e resultados de ferramentas a cada chamada. O guia de custos, observado em 03/10/2026, observa que sessões longas podem custar muito mais do que uma única solicitação de chat. Calculamos a aritmética abaixo a partir dos preços de tabela. O resultado é uma estimativa, não uma fatura medida.

Suposições (nossas, não medidas): um loop de 20 chamadas de modelo, cada uma com 30.000 tokens de entrada e 1.500 tokens de saída. Isso resulta em 600.000 tokens de entrada e 30.000 tokens de saída no total.

A fórmula é input_tokens / 1M × preço de entrada + output_tokens / 1M × preço de saída. Os preços vêm da tabela acima.

Todas as 20 chamadas para deepseek-v4-pro:

• Fora do pico: 0,6 × $0,66 = $0,396 de entrada, mais 0,03 × $1,98 = $0,0594 de saída, totalizando $0,4554.
• Pico: 0,6 × $1,32 = $0,792, mais 0,03 × $3,96 = $0,1188, totalizando $0,9108.

Todas as 20 chamadas para deepseek-v4-flash:

• Fora do pico: 0,6 × $0,15 = $0,09, mais 0,03 × $0,60 = $0,018, totalizando $0,108.
• Pico: 0,6 × $0,30 = $0,18, mais 0,03 × $1,20 = $0,036, totalizando $0,216.

Misto: 4 chamadas para pro, 16 para flash. O pro carrega 120.000 de entrada e 6.000 de saída. O flash carrega 480.000 de entrada e 24.000 de saída.

• Fora do pico: pro é 0,12 × $0,66 + 0,006 × $1,98 = $0,0792 + $0,01188 = $0,09108. Flash é 0,48 × $0,15 + 0,024 × $0,60 = $0,072 + $0,0144 = $0,0864. O total é $0,17748.
• Pico: pro é 0,12 × $1,32 + 0,006 × $3,96 = $0,1584 + $0,02376 = $0,18216. Flash é 0,48 × $0,30 + 0,024 × $1,20 = $0,144 + $0,0288 = $0,1728. O total é $0,35496.

Cenário	Estimativa fora do pico	Estimativa no pico
20 chamadas no deepseek-v4-pro	$0,4554	$0,9108
20 chamadas no deepseek-v4-flash	$0,1080	$0,2160
4 pro + 16 flash	$0,1775	$0,3550

Estimativas baseadas em preços de tabela observados em 03/10/2026 (pro, flash).

Variante de cache (fora do pico, suposição: 80% dos tokens de entrada são leituras de cache). Isso significa 480.000 tokens de leitura de cache e 120.000 tokens não armazenados em cache por loop.

• Pro: 0,48 × $0,022 = $0,01056, mais 0,12 × $0,66 = $0,0792, mais $0,0594 de saída, totalizando $0,14916.
• Flash: 0,48 × $0,003 = $0,00144, mais 0,12 × $0,15 = $0,018, mais $0,018 de saída, totalizando $0,03744.

Esta variante cobra tokens não armazenados em cache pelo preço de entrada simples e ignora cobranças de escrita de cache no flash, que o registro não lista. Confirme as contagens de tokens armazenados em cache na resposta ou em Uso antes de contar com esse desconto. O guia de faturamento também alerta que o menor preço por token nem sempre é o menor custo por tarefa concluída, porque retries aumentam o valor.

Uma solicitação de Tool-Calling para um agente de codificação

Ambos os registros listam tool-use e ambos aceitam openai_chat_completions. A solicitação abaixo usa apenas campos do guia de tool-calling (observado em 03/10/2026): model, messages e tools com type: "function". Adicionamos max_tokens, que o guia de faturamento lista como uma maneira de limitar o tamanho da resposta. Deixamos de fora o tool_choice, porque esse guia o documenta apenas para o formato Responses.

curl https://api.tokenlab.sh/v1/chat/completions \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "max_tokens": 2000,
    "messages": [
      {"role": "system", "content": "You are a software engineering assistant."},
      {"role": "user", "content": "The pagination test in tests/test_api.py fails. Find the cause."}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "read_file",
          "description": "Read a file from the repository",
          "parameters": {
            "type": "object",
            "properties": {"path": {"type": "string"}},
            "required": ["path"]
          }
        }
      },
      {
        "type": "function",
        "function": {
          "name": "run_tests",
          "description": "Run the test suite for one path",
          "parameters": {
            "type": "object",
            "properties": {"path": {"type": "string"}},
            "required": ["path"]
          }
        }
      }
    ]
  }'

O modelo retorna um nome de função e argumentos em tool_calls. Seu backend executa a ferramenta. O loop então é executado em cinco etapas:

1. Envie mensagens mais definições de ferramentas.
2. Leia a resposta para tool_calls.
3. Execute a ferramenta em seu próprio backend.
4. Anexe o resultado da ferramenta no mesmo formato de API.
5. Continue até que o modelo retorne uma resposta final.

O guia não mostra a forma da mensagem de resultado da ferramenta inline. Obtenha-a da referência Create Chat Completion (/api-reference/chat/create-completion) em vez de adivinhar.

Antes de executar qualquer chamada, valide os argumentos e aplique suas próprias verificações de permissão. Torne a execução idempotente, porque um retry do cliente pode repetir a mesma chamada de ferramenta. Mantenha um formato de API para toda a troca, já que os formatos representam o estado da ferramenta de forma diferente.

Retries, Backoff e Fallback entre os dois modelos

O guia de erros e o guia de limites de taxa, ambos observados em 03/10/2026, definem a política. Ramifique com base no status HTTP e no code, nunca na message.

Status	Repetir a mesma solicitação?	Ação
400, 401, 402, 403, 404, 413	Não	Corrija a solicitação, chave, saldo, permissões ou entrada
429	Sim	Aguarde o Retry-After; se ausente, use backoff exponencial com jitter
500–504	Apenas se retryable for true	Respeite o retry_after e limite as tentativas
Conexão fechada antes de uma resposta	Às vezes	Tente novamente com cuidado se uma chamada de ferramenta puder repetir um efeito colateral
Stream interrompido após a chegada da saída	Não	Trate como incompleto; uma repetição pode produzir saída diferente ou uma segunda cobrança

Dois casos precisam de cuidado extra. Um 503 all_channels_failed ou 503 delivery_tier_unavailable nem sempre é temporário. Quando retryable é false e retry_after está ausente, não repita a solicitação. Verifique GET /v1/models antes de escolher outro modelo. Além disso, context_length_exceeded não será corrigido alternando entre esses dois modelos, já que ambos listam o mesmo limite de entrada de 1.000.000 de tokens.

O código abaixo aplica essa política. Ele define max_retries=0 para que o SDK não tente novamente sem seu conhecimento. Cada modelo recebe quatro tentativas, e o fallback é executado apenas após o primeiro modelo esgotar os erros retryable.

import os
import random
import time
from openai import OpenAI, APIStatusError, APIConnectionError

client = OpenAI(
    api_key=os.environ["TOKENLAB_API_KEY"],
    base_url="https://api.tokenlab.sh/v1",
    timeout=30.0,
    max_retries=0,
)

FALLBACK = {
    "deepseek-v4-pro": "deepseek-v4-flash",
    "deepseek-v4-flash": "deepseek-v4-pro",
}

def error_fields(exc):
    body = getattr(exc, "body", None)
    if isinstance(body, dict):
        return body.get("error", body)
    return {}

def backoff(attempt):
    return min(30, 2 ** attempt + random.random())

def retry_delay(exc, attempt):
    """Segundos para aguardar, ou None quando a solicitação não deve ser repetida."""
    if isinstance(exc, APIConnectionError):
        return backoff(attempt)
    fields = error_fields(exc)
    header = exc.response.headers.get("Retry-After")
    if exc.status_code == 429:
        return float(header) if header else backoff(attempt)
    if exc.status_code >= 500 and fields.get("retryable") is True:
        wait = fields.get("retry_after") or header
        return float(wait) if wait else backoff(attempt)
    return None

def chat_with_fallback(model, messages, tools=None, attempts=4):
    last_exc = None
    for candidate in (model, FALLBACK[model]):
        kwargs = {"model": candidate, "messages": messages}
        if tools:
            kwargs["tools"] = tools
        for attempt in range(attempts):
            try:
                return candidate, client.chat.completions.create(**kwargs)
            except (APIStatusError, APIConnectionError) as exc:
                delay = retry_delay(exc, attempt)
                if delay is None:
                    raise  # 4xx ou 5xx não retryable: não repetir ou fazer fallback
                last_exc = exc
                if attempt < attempts - 1:
                    time.sleep(delay)
        print(f"{candidate} esgotou as tentativas, tentando {FALLBACK[candidate]}")
    raise last_exc

def pick_model(is_complex):
    return "deepseek-v4-pro" if is_complex else "deepseek-v4-flash"

used, response = chat_with_fallback(
    pick_model(is_complex=False),
    [{"role": "user", "content": "Write a pytest case: an empty list returns 0 for sum_items()."}],
)
print(used, response.choices[0].message.content)

Sempre registre qual modelo respondeu. O guia de agente de codificação alerta que um fallback pode alterar preço, limite de contexto, formato de ferramenta ou estilo de saída, então avise o usuário quando o modelo mudar. Fazer fallback do flash para o pro quadruplica aproximadamente o custo de entrada nos preços de tabela, então emita um alerta. Salve o ID da solicitação dos cabeçalhos de resposta com cada chamada para que o suporte possa rastrear uma falha.

Leia limites, formatos e preço antes de rotear

A referência Get a Model, observada em 03/10/2026, descreve GET /v1/models/:model. A resposta carrega um objeto tokenlab com capabilities, pricing, max_input_tokens, max_output_tokens, accepted_request_formats e lifecycle. Um modelo desconhecido retorna 404 model_not_found. O guia de faturamento também aponta para GET /v1/models/:model/pricing para o preço atual.

import json
import urllib.request

def read_model(model_id):
    url = f"https://api.tokenlab.sh/v1/models/{model_id}"
    with urllib.request.urlopen(url, timeout=10) as resp:
        meta = json.load(resp)["tokenlab"]
    return {
        "max_input_tokens": meta.get("max_input_tokens"),
        "max_output_tokens": meta.get("max_output_tokens"),
        "formats": meta.get("accepted_request_formats"),
        "capabilities": meta.get("capabilities"),
        "lifecycle": meta.get("lifecycle"),
        "pricing": meta.get("pricing"),
    }

def preflight(model_id, input_tokens):
    info = read_model(model_id)
    problems = []
    if "openai_chat_completions" not in (info["formats"] or []):
        problems.append("chat completions not accepted")
    if "tool-use" not in (info["capabilities"] or []):
        problems.append("no tool-use capability")
    if info["max_input_tokens"] and input_tokens > info["max_input_tokens"]:
        problems.append("input exceeds max_input_tokens")
    return info, problems

for model_id in ("deepseek-v4-pro", "deepseek-v4-flash"):
    info, problems = preflight(model_id, input_tokens=30_000)
    print(model_id, json.dumps(info, indent=2), problems)

Imprimimos lifecycle e pricing brutos porque as evidências deste artigo não mostram seu layout JSON exato dentro dessa resposta. Inspecione a saída uma vez e, em seguida, analise os campos de que você precisa. A documentação desaconselha o hard-code de tabelas de preços copiadas, então execute a verificação na inicialização ou em um cronograma. Endpoints de descoberta pública, como GET /v1/models, têm seus próprios limites de taxa, portanto, armazene o resultado em cache em vez de chamá-lo por solicitação.

Para limites de taxa, o nível de usuário padrão permite 1.000 solicitações por minuto por chave de API, conforme observado em 03/10/2026. O guia diz que a configuração ativa pode diferir. Em um 429, confie nos valores retornados X-RateLimit-Limit e Retry-After em vez de qualquer número copiado.

FAQ

Posso chamar o deepseek-v4-pro através do formato Anthropic Messages?

Sim. Ambos os registros listam anthropic_messages entre os formatos aceitos, observado em 03/10/2026. O guia de agente de codificação fornece a URL base do Anthropic Messages como https://api.tokenlab.sh, sem o sufixo /v1 que o Chat Completions usa. Os esquemas de ferramentas diferem por formato, então mantenha um formato para toda a conversa.

Devo tentar novamente um 503 do deepseek-v4-pro ou deepseek-v4-flash?

Apenas se o corpo do erro disser que retryable é true, e então aguarde o retry_after. Um 503 all_channels_failed com retryable: false significa que a solicitação não tem suprimento no nível de entrega selecionado. Repeti-la não ajudará. Verifique GET /v1/models antes de escolher outro modelo, conforme o guia de erros descreve.

O deepseek-v4.1-flash substitui o deepseek-v4-flash?

O catálogo não diz isso. Em 03/10/2026, o registro do deepseek-v4-flash não mostrava nenhum modelo de substituição, e o deepseek-v4.1-flash mostrava status ativo. Os dois compartilham limites e preços de tabela, e o mais novo adiciona capacidades de reasoning e vision. Teste-o em suas tarefas e alterne deliberadamente pelo ID do modelo.

Tokens armazenados em cache tornam o deepseek-v4-flash mais barato em um loop de agente?

Eles podem. O registro lista um preço de leitura de cache fora do pico de $0,003 por 1 milhão de tokens, contra $0,15 para entrada simples. O guia de custos diz para confirmar o uso de tokens armazenados em cache na resposta ou em Uso antes de contar com um desconto. O comportamento e os preços do cache diferem por modelo.

Roteamento para o deepseek-v4-flash aumentará meu limite de taxa?

Não. O guia de limites de taxa diz que um modelo mais rápido não aumenta o limite de solicitação da sua conta. A velocidade do modelo, os limites de token e os limites de taxa da conta são restrições separadas, e os limites aplicam-se por chave de API.

Verifique as entradas atuais de deepseek-v4-pro e deepseek-v4-flash na página de modelos do TokenLab antes de configurar seu roteador.