Como usar a API DeepSeek V4 Flash (com código real)

O que você está realmente chamando

deepseek-v4-flash é o menor dos dois modelos na tabela de preços da DeepSeek: um LLM Mixture-of-Experts de 284B total / 13B ativos, com pesos abertos sob licença MIT, e sucessor da geração que cobri em DeepSeek V3.2.

O alias é um alvo móvel, não um snapshot fixo. A nota de changelog da DeepSeek diz que o modelo "foi atualizado para DeepSeek-V4-Flash-0731. O método de chamada permanece inalterado", então você sempre recebe a build mais recente, e não há uma forma publicada de fixar uma versão mais antiga.

Tudo o que você precisa configurar vive em uma única página, e vale a pena dar uma olhada antes de escrever uma linha de código sequer, porque as duas base URLs e os dois preços estão na mesma tabela.

Duas coisas nessa captura de tela decidem a maior parte da sua arquitetura. A tabela de preços lista 1M de contexto e 384K de output máximo para ambos os modelos, então a diferença de preço entre Flash e Pro não é um tradeoff de janela de contexto. E o modo thinking está listado ali como compatível com os dois modos, com thinking como padrão, o que, em termos de custo, é o padrão mais caro de toda a API.

Aqui está essa mesma tabela em números, já que você vai fazer contas com eles em breve:

O Flash fica em cerca de um terço das tarifas de entrada com cache miss e de saída do Pro, ambas cotadas por milhão de tokens. Se você quer a parte constrangedora dessa história, o nível mais barato atualmente supera o mais caro nas próprias linhas agentic da DeepSeek, algo que investiguei separadamente em Flash vs V4 Pro.

Para ver como ele se sai contra o resto do campo, há Flash vs Kimi K3 e Flash vs GPT-5.6. A colisão de nome com Qwen 3.7 Flash é infeliz e não é culpa minha.

Antes de começar

Quatro pré-requisitos, e só um deles é incomum.

1. Uma conta e uma chave. As chaves são criadas em platform.deepseek.com/api_keys. Leia-a a partir de uma variável de ambiente, e não em linha, que é também como os próprios exemplos da DeepSeek fazem.
2. O SDK padrão da OpenAI. pip3 install openai ou npm install openai. Não existe pacote da DeepSeek para instalar em lugar nenhum, o que é todo o sentido da camada de compatibilidade.
3. Dinheiro na conta, com antecedência. A DeepSeek é pré-paga, e esse é o pré-requisito que morde. Um 402 - Insufficient Balance não chega no momento da configuração, quando você realmente notaria. A autenticação funciona, as primeiras chamadas funcionam, e então a falha aparece assim que o saldo chega a zero, o que, em um loop em lote, significa uma conclusão parcial com um erro de pagamento sentado em um índice de linha arbitrário.
4. Saber qual string de modelo você quer. Todo exemplo de código na documentação da DeepSeek tem deepseek-v4-pro fixo. Copie um esperando o preço do Flash, e você será cobrado 3,11x mais em entrada e saída.

Existem três hosts, não um, e a documentação os espalha por páginas diferentes:

Não existe uma variante /v1 na documentação atual. Se você viu esse sufixo em algum tutorial antigo, ele simplesmente não está na tabela de configuração como ela está hoje.

Passo 1: sua primeira chamada

Aqui está o Python, com a string do modelo trocada para Flash e o thinking deixado no padrão da DeepSeek, para que você veja o que esse padrão realmente faz com você:

# pip3 install openai
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get('DEEPSEEK_API_KEY'),
    base_url="https://api.deepseek.com")

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "system", "content": "You are a helpful assistant"},
        {"role": "user", "content": "Hello"},
    ],
    stream=False,
)

print(response.choices[0].message.content)
print(response.usage)

A mesma coisa em curl, caso você prefira ver o formato de rede:

curl https://api.deepseek.com/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  -d '{
        "model": "deepseek-v4-flash",
        "messages": [
          {"role": "system", "content": "You are a helpful assistant."},
          {"role": "user", "content": "Hello!"}
        ],
        "stream": false
      }'

Imprima response.usage nessa primeira chamada, não só o conteúdo. É a única forma de ver o que estou prestes a descrever.

Passo 2: desligue o thinking, ou saiba que está pagando por ele

thinking.type aceita enabled ou disabled, e a referência da API dá enabled como padrão. reasoning_effort aceita low, high e max, e a mesma página diz que "o esforço padrão é high". Ninguém configura isso numa primeira chamada, o que significa que seu hello-world rodou com esforço de raciocínio alto e você foi cobrado pela chain of thought na tarifa de output.

Desligá-lo é um único argumento, e vai dentro de extra_body, porque o SDK da OpenAI não tem um campo thinking nativo próprio:

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "Summarise this ticket in one line: ..."}],
    extra_body={"thinking": {"type": "disabled"}},
)

Diminuí-lo em vez de desligá-lo é onde o Flash tem uma vantagem real sobre seu irmão. O mapeamento de esforço publicado remapeia o que você pede por modelo:

Leia a primeira linha duas vezes. low é um low de verdade no Flash e é silenciosamente promovido para high no Pro, então não existe atualmente nenhuma execução barata do Pro. O Flash tem sua própria peculiaridade na terceira linha, onde xhigh colapsa para high, então pedir mais que high e menos que max simplesmente te dá high de qualquer forma. A DeepSeek observa em nota de rodapé que "vai atualizar o esforço mapeado real do deepseek-v4-pro no início de agosto de 2026", que é agora, então verifique de novo a coluna do Pro se isso te importa.

Dois efeitos colaterais de deixar o thinking ligado que pegam as pessoas. Primeiro, segundo o guia do modo thinking, o modo thinking não suporta temperature, top_p, presence_penalty nem frequency_penalty, e a DeepSeek é explícita ao dizer que "definir esses parâmetros não vai disparar um erro, mas também não vai ter nenhum efeito". Segundo, a chain of thought volta em um campo separado, reasoning_content, então um script que só imprime .message.content te mostra a resposta e nenhum dos tokens que você pagou.

Há partes móveis suficientes para que adivinhar a fatura seja uma má ideia. Insira seus próprios números:

Passo 3: faça streaming, e mantenha a contagem de tokens

Streaming é um único argumento. Tirar dados de uso de um stream é um segundo que as pessoas esquecem, e depois ficam se perguntando por que todo chunk reporta usage: null:

stream = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "Draft a refund reply."}],
    stream=True,
    stream_options={"include_usage": True},
    extra_body={"thinking": {"type": "disabled"}},
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
    if chunk.usage:
        print("\n", chunk.usage)

Com include_usage ativado, um chunk extra chega antes de data: [DONE], trazendo as contagens de tokens da requisição inteira com um array choices vazio. A referência da API diz para só configurá-lo quando stream for true.

Se você está escrevendo seu próprio parser de SSE em vez de usar o SDK, há mais uma coisa que vale a pena sinalizar. Enquanto uma requisição espera por capacidade, a conexão recebe padding. Segundo a página de limites de taxa, requisições sem streaming "retornam continuamente linhas vazias" e requisições com streaming retornam comentários SSE : keep-alive. Um leitor feito à mão que trata uma linha em branco como fim do corpo, ou que não pula linhas que começam com :, quebra exatamente aqui. Além disso, se a inferência não começou depois de dez minutos, o servidor simplesmente fecha a conexão.

Passo 4: multi-turno, porque a API não lembra de nada

A DeepSeek é bem direta nesse ponto. O guia multi-round chama /chat/completions de API "stateless", "o que significa que o servidor não registra o contexto das requisições do usuário. Portanto, o usuário deve concatenar todo o histórico de conversa anterior e passá-lo para a API de chat a cada requisição."

Então o histórico é seu, e só seu, para gerenciar:

messages = [{"role": "user", "content": "What's the highest mountain in the world?"}]
response = client.chat.completions.create(model="deepseek-v4-flash", messages=messages)

messages.append(response.choices[0].message)          # round 1 answer
messages.append({"role": "user", "content": "What is the second?"})
response = client.chat.completions.create(model="deepseek-v4-flash", messages=messages)

Reenviar todo o histórico a cada turno soa ruinoso, e seria, exceto que é exatamente aqui que o preço fica interessante. O cache de contexto em disco vem ativado por padrão para todos os usuários, sem precisar mudar código, e a tarifa de entrada com cache hit é $0.0028 contra $0.14 em um miss. Nos mesmos tokens, isso é uma diferença de 50x.

O cache é automático, o que significa que não há botão para girar, e a estrutura do seu prompt é o botão. Alguns mecanismos decidem qual tarifa você acaba pagando:

• Uma requisição só é cobrada na tarifa de hit se ela corresponder completamente a uma unidade de prefixo de cache persistida. Sobreposição parcial de uma unidade não conta, algo que a DeepSeek atribui ao seu mecanismo de Sliding Window Attention.
• Unidades são persistidas, segundo o guia de cache, nos limites das requisições, na detecção de prefixos comuns entre requisições, e em intervalos fixos de tokens para entradas longas.
• Você pode auditar a divisão por chamada: usage traz prompt_cache_hit_tokens e prompt_cache_miss_tokens.
• O cache é best-effort, sem taxa de acerto garantida, e entradas não usadas são limpas "geralmente em algumas horas a alguns dias".

Na prática: mantenha o system prompt idêntico byte a byte, adicione ao histórico em vez de reescrevê-lo, e tudo que varia por requisição vai para o final. Injetar um timestamp ou um trecho embaralhado de base de conhecimento no início do prompt é como equipes acabam pagando 50x mais por acidente, o que torna o comportamento do cache uma questão real de engenharia de prompt, e não uma nota de rodapé na fatura.

Isso morde mais forte em RAG, onde os trechos recuperados mudam a cada chamada por design. Se é isso que você está construindo, então nosso passo a passo pelo pipeline de RAG para suporte e a comparação RAG vs LLM puro são os dois que eu leria em seguida.

Passo 5: tool calls, e o 400 que vai te confundir

O formato de tools é o padrão da OpenAI, limitado a 128 funções, com nomes de função limitados a 64 caracteres:

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_order_status",
            "description": "Look up an order's shipping status by order ID.",
            "parameters": {
                "type": "object",
                "properties": {
                    "order_id": {"type": "string", "description": "The order ID, e.g. A-10293"}
                },
                "required": ["order_id"]
            },
        }
    },
]

tool_calls volta como um array na mensagem do assistant, arguments chega como uma string JSON e não como um dict, e o sinal de fim de loop no exemplo de agent loop da DeepSeek é que tool_calls é None quando o modelo termina. O guia de tool calls também se preocupa em deixar claro algo óbvio que as pessoas ainda erram: "O próprio modelo não executa funções específicas."

Agora a parte que vale a pena tatuar em algum lugar. A regra normal do modo thinking é que o reasoning_content intermediário "não precisa participar da concatenação de contexto", e é ignorado se você o passar mesmo assim. Adicione tools, e isso se inverte:

Please note that for requests carrying the tools parameter, the reasoning_content must be fully passed back to the API in all subsequent requests. If your code does not correctly pass back reasoning_content, the API will return a 400 error.

Thinking Mode, DeepSeek docs

Essa é a armadilha porque está documentada em uma página diferente do guia de tool calls onde a maioria das pessoas chega, e porque a coisa natural a escrever é um serializador que mantém role, content e tool_calls, e descarta o campo que não reconhece. Em vez disso, adicione de volta o objeto de mensagem inteiro:

messages.append(response.choices[0].message)   # keeps reasoning_content intact
for tool in response.choices[0].message.tool_calls:
    result = TOOL_MAP[tool.function.name](**json.loads(tool.function.arguments))
    messages.append({"role": "tool", "tool_call_id": tool.id, "content": result})

Mais uma coisa aqui: a DeepSeek nunca usa a frase "parallel tool calls", e não existe um parâmetro parallel_tool_calls na superfície do Chat Completions, embora o loop oficial de fato itere sobre o array em vez de pegar [0]. Então escreva o loop, não pressuponha a garantia. Esse é o mecanismo por trás de qualquer coisa que você chamaria de agente de IA, então vale a pena acertar isso antes de empilhar comportamento agentic em cima.

Se você precisa de imposição de schema, o modo strict existe, mas vive no host beta. Três requisitos: base_url="https://api.deepseek.com/beta", "strict": true dentro de cada function, e additionalProperties: false em todo objeto, com todas as propriedades marcadas como required. minLength, maxLength, minItems e maxItems não são suportados. Vale a pena saber que o próprio exemplo da DeepSeek usa "$def" (singular) como contêiner de definições em vez do $defs do JSON Schema, então copie a grafia deles.

Passo 6: saída em JSON

response_format={'type': 'json_object'}, e não há nenhuma variante json_schema aqui. O aviso de quatro pontos da DeepSeek é curto e cada ponto importa: definir o parâmetro, incluir a palavra "json" em um prompt de system ou user e fornecer um exemplo do formato desejado, definir max_tokens com sensatez "para evitar que a string JSON seja truncada no meio", e saber que "a API pode ocasionalmente retornar conteúdo vazio".

Esse último ponto é um bug aberto reconhecido, em negrito na própria página da DeepSeek, e mudanças de prompt são a única mitigação que eles oferecem. Então faça o parse de forma defensiva:

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "system", "content": 'Extract intent and urgency as json. Example: {"intent": "refund", "urgency": "high"}'},
        {"role": "user", "content": ticket_body},
    ],
    response_format={'type': 'json_object'},
    max_tokens=400,
    extra_body={"thinking": {"type": "disabled"}},
)

raw = response.choices[0].message.content
parsed = json.loads(raw) if raw and raw.strip() else None

Note que o próprio exemplo de JSON da DeepSeek não define max_tokens de forma alguma, apesar de seu próprio requisito nº 3 dizer para fazê-lo. Defina-o.

A Responses API, e o que ela não faz

O Flash é o único modelo que a Responses API suporta por enquanto. O próprio aviso da DeepSeek diz que ela "atualmente só suporta o modelo deepseek-v4-flash", com suporte ao Pro previsto para o início de agosto de 2026. Ela existe principalmente por um motivo, que a DeepSeek diz sem rodeios: "Para atender à demanda do Codex."

response = client.responses.create(
    model="deepseek-v4-flash",
    instructions="You are a helpful assistant.",
    input="Hi, how are you?",
)
print(response.output_text)

É aqui que as expectativas quebram. Se você conhece a Responses API de outro lugar, você a conhece pela statefulness. A implementação da DeepSeek é stateless. previous_response_id e conversation são "Não suportado (API stateless)", store é "Não suportado. A resposta sempre traz store: false", e background, metadata, include, prompt e stream_options também não são suportados.

E eles não dão erro. A própria linha da DeepSeek na tabela de compatibilidade, textualmente: "Parâmetros não suportados são ignorados silenciosamente e não causam erros, então clientes existentes da Responses API podem se conectar sem modificação". Passe store: true, receba um 200, e nada é armazenado.

O que ela realmente adiciona sobre o Chat Completions vale a pena conhecer: eventos SSE semânticos tipados, incluindo um canal dedicado response.reasoning_text.delta para a chain of thought, uma ferramenta embutida web_search do lado do servidor, e top_logprobs. A prateleira de ferramentas embutidas, porém, tem exatamente dois itens, web_search e apply_patch; file_search, code_interpreter, computer_use e MCP estão todos listados como ignorados.

Duas pegadinhas de migração: não há sentinela data: [DONE], então termine em response.completed / response.incomplete / response.failed; e partes input_image não dão erro, são "substituídas por um texto de placeholder", o que é consistente com o Flash sendo só de texto, e não multimodal.

Lidando com os erros que você realmente vai encontrar

Sete códigos são documentados, e nenhum outro. Não há cabeçalho Retry-After, nem um cronograma de backoff publicado em lugar nenhum, então quem decide é o seu próprio wrapper.

A separação entre 400 e 422 é real e útil. 400 é um corpo malformado; 422 é um corpo bem formado com valores de parâmetro ruins. Dois caminhos de depuração diferentes, e a mensagem de erro é o que te diz qual é qual.

O 429 merece uma nota, porque a solução documentada pela própria DeepSeek é incomumente sincera: "Por favor, module suas requisições de forma razoável. Também aconselhamos os usuários a mudar temporariamente para as APIs de provedores alternativos de LLM, como a OpenAI." Um fornecedor recomendar um concorrente dentro da própria documentação de erros é um sinal real sobre a capacidade em pico de carga, e vale a pena projetar um caminho de fallback em vez de tratar isso como piada.

Sobre os limites em si: a DeepSeek não publica nenhum número de RPM ou TPM. O único teto é a concorrência, e a página de limites de taxa a conta por conta, e não por chave, então criar chaves extras não compra nada. "Uma requisição conta como uma conexão simultânea desde o momento em que é enviada até que a resposta do modelo seja concluída", o que significa que uma chamada longa de raciocínio ocupa um slot pela sua duração inteira. O Flash tem 2.500 slots contra os 500 do Pro, e a expansão é gratuita, mas passa por um formulário manual do Feishu.

Se você está rodando tráfego multi-tenant, defina user_id (nota: não o user da OpenAI), passado como extra_body={"user_id": "..."}. Ele conduz a revisão de segurança de conteúdo, o isolamento de agendamento por usuário, e o isolamento de cache KV para privacidade. O formato é [a-zA-Z0-9\-_], no máximo 512 caracteres, e a DeepSeek avisa para não colocar informações de privacidade do usuário ali. Também é sua única alavanca contra o raio de alcance de injeção de prompt entre inquilinos, o que importa mais do que parece assim que usuários reais começam a digitar nisso.

As cinco coisas que falham em silêncio

Toda armadilha nessa API retorna HTTP 200. Esse é o fio condutor aqui, e vale a pena ter uma única lista para comparar um diff.

1. frequency_penalty e presence_penalty estão obsoletos. Ambos trazem a mesma linha na referência da API: "Este parâmetro não é mais suportado. Não terá efeito se você o passar para a API." Remova-os ao portar uma chamada da OpenAI.
2. temperature e top_p são inertes no modo thinking, que é o padrão. Se você ajustou um prompt em temperature=0.2 e o portou, você está rodando com o que quer que o modo thinking faça.
3. Campos não suportados da Responses API são ignorados silenciosamente. store, previous_response_id, conversation, background. 200 toda vez.
4. Um nome de modelo não reconhecido no endpoint Anthropic vira Flash. Segundo o guia da API Anthropic, qualquer nome de modelo não suportado "será automaticamente mapeado para o modelo deepseek-v4-flash". claude-opus* mapeia para Pro, claude-sonnet* e claude-haiku* mapeiam para Flash. A DeepSeek vende isso como um recurso para apontar clientes Claude para sua API, e é, até um erro de digitação mudar silenciosamente contra qual modelo seus evals rodaram.
5. cache_control é ignorado no endpoint Anthropic. Em todo lugar onde aparece: em tools, blocos de texto, tool_use, tool_result. O próprio cache em disco da DeepSeek roda no lugar, então não há nada a declarar, mas código portado da Anthropic perde seus breakpoints de cache explícitos sem nenhum aviso.

Eu adicionaria um sexto que realmente não é culpa da DeepSeek. finish_reason traz um valor que não é da OpenAI, insufficient_system_resource, retornado quando a requisição é interrompida pela capacidade do sistema de inferência. Um handler que só conhece stop / length / tool_calls vai tratar uma resposta truncada como se estivesse completa.

Isso deveria responder tickets de clientes?

Essa é a pergunta que eu realmente recebo, e a resposta honesta é que a API é a parte fácil disso tudo. Fazer um modelo responder é trabalho de um fim de semana. Conseguir um agente de suporte de IA que você deixaria chegar perto de uma fila real não é.

Aqui está o que eu vi dar errado dentro do nosso próprio produto, o que é mais instrutivo do que qualquer benchmark. O pior modo de falha que a eesel observou em produção não é um modelo se recusando, ou dando timeout. É um agente fabricando sucesso: narrando "executando buscas no Zendesk" por uns dez turnos sem nunca tocar a API, reportando arquivos salvos que não existem, inventando métricas. Só pegamos isso porque estávamos procurando. Nada mata um colega de equipe mais rápido do que mentir sobre o que fez, e note a forma dessa falha, ela também parecia um 200.

O que é a mesma lição de todo este artigo. Uma chamada de modelo crua ter sucesso não te diz quase nada sobre se a resposta estava realmente certa. Testes independentes colocam a taxa de alucinação do Flash em 84%, 12 pontos abaixo do seu antecessor, mas ainda muito longe de "aponte para os clientes e vá embora". Sua pontuação também oscila de 29 sem raciocínio até 50 no esforço máximo, dependendo de uma configuração que você talvez nem tenha definido de propósito.

O que significa que as camadas acima do modelo são as que fazem o trabalho de verdade: grounding em fontes verificadas, uma pontuação de confiança para que ele recuse em vez de chutar, caminhos de escalonamento limpos, e um humano revisando qualquer coisa consequente.

Se você quiser as versões longas de tudo isso, escrevemos separadamente sobre prevenir alucinações e também sobre testes adversariais.

Depois tem a questão dos dados, e eu quero ser preciso aqui em vez de alarmista. Os Termos de Serviço da Open Platform da DeepSeek regem a API paga e ficam em silêncio sobre o uso para treinamento das suas entradas, o que é diferente de permissivo e também diferente de seguro. Os Termos de Uso para consumidores trazem uma cláusula explícita no §4.3 com um botão de opt-out; o documento específico da API simplesmente para antes dessa cláusula. Não há DPA publicado nem opção de retenção zero em nenhum dos dois sentidos, e os próprios dados ficam sob a lei chinesa.

Se você viveu a clarificação de política do Slack, então sabe como isso soa para um revisor de segurança. Vale a pena combinar isso com nosso guia de SOC 2 e GDPR antes de dados de clientes chegarem perto, e pensar sobre quais dados você estaria enviando, para começar.

Se nada disso for aceitável, os pesos MIT são uma saída real. Você pode autoalojar, fine-tuning incluído, e a licença permite uso comercial.

Se você deveria fazer isso é a pergunta de construir versus comprar, e minha leitura honesta, depois de ter lançado os dois, é que a restrição de uma equipe de suporte quase nunca é o acesso ao modelo. É a profundidade de integração e a qualidade do escalonamento que decidem se algo disso funciona.

Experimente a eesel

Se você chegou até aqui porque está integrando o Flash a um helpdesk, então a API é cerca de 5% desse projeto. Os outros 95% são o que acontece quando o modelo erra, e essa é a parte que eu prefereria que você não construísse duas vezes.

A eesel é esses 95%, transformados em produto. Ela fundamenta cada resposta no seu conhecimento verificado, ou seja, artigos da central de ajuda, tickets passados, macros e documentos conectados, e então faz o que mais importa antes de ir ao ar: simulações contra seus próprios tickets históricos, para que você veja a precisão real na sua fila de verdade em vez de um número de benchmark. Você lança quando isso ultrapassa sua própria régua, não quando algum ranking diz. O preço é 40 centavos por ticket atendido, sem taxas por assento, e você nunca é cobrado por tickets que seus humanos atendem, então se você roteia 200 dos seus 1.000 tickets mensais para a IA, você paga por 200. Há $50 de uso grátis, sem cartão de crédito, e toda integração está disponível no plano gratuito.

Esse painel de "uso de aprovação / rejeição por ferramenta" é a resposta direta ao problema do sucesso fabricado de antes. Toda ação de ferramenta que o agente realiza é contável e revisável, então um agente que afirma ter buscado no seu helpdesk vira uma linha que você pode conferir, em vez de uma frase na qual você precisa confiar.

Dito de outra forma: uma API crua é infraestrutura. O que um gestor de suporte realmente precisa é de um funcionário.

Se você quiser conferir primeiro a matemática de tokens contra a matemática por resultado, comece com o custo do atendimento ao cliente com IA, e depois com o custo por resolução para a unidade que realmente aparece em um orçamento.

Existe uma versão de automação de suporte que reduz custos sem destruir seu CSAT. Ela começa pelo custo por ticket, e não pelo custo por milhão de tokens.