DeepSeek API: chave, preços e quando passar para local

#DeepSeek API: o essencial antes de começar

DeepSeek oferece duas portas de entrada que não devem ser confundidas. O site de chat, gratuito, é usado em um navegador. A API, por sua vez, é voltada para desenvolvedores: seu programa envia uma requisição, os servidores do DeepSeek retornam uma resposta e cada troca é descontada do seu saldo. É essa segunda porta que este guia aborda.

O que é

Um serviço pago por uso, hospedado pela DeepSeek. Você não baixa nada: o modelo roda na infraestrutura do fornecedor.

O formato

Compatível com a API da OpenAI. As bibliotecas e ferramentas que sabem se comunicar com a OpenAI funcionam ao alterar duas configurações: o endereço de base e a chave.

Faturamento

Por token, com cobrança sobre um saldo pré-pago. A tabela de preços diferencia os tokens enviados, conforme já estejam em cache ou não, e os tokens gerados.

Seus dados

Cada requisição sai da sua infraestrutura e é processada nos servidores do fornecedor. Esse é o ponto a verificar em primeiro lugar se você manipula dados pessoais ou confidenciais.

L'alternative

DeepSeek também publica os pesos de seus modelos. Uma versão adaptada ao seu hardware pode rodar em sua máquina, sem cobrança por token nem envio de dados.

#Pré-requisitos

Uma conta de desenvolvedor

É criado na plataforma da DeepSeek, no endereço platform.deepseek.com. Esse não é o mesmo endereço do site de chat.

Um meio de pagamento

O serviço funciona com um saldo que você carrega antecipadamente. Sem saldo disponível, as chamadas são recusadas.

Uma ferramenta para chamar a API

curl é suficiente para um primeiro teste. Para um projeto de verdade, use Python 3 com a biblioteca openai ou seu equivalente para Node.js.

Um lugar seguro para a chave

Uma variável de ambiente no seu computador, um gerenciador de segredos em produção. Nunca no código-fonte.

#Criar uma chave da API DeepSeek

1. 01
   Abrir uma conta na plataforma

   Acesse platform.deepseek.com digitando o endereço manualmente e faça o cadastro. Para uso profissional, use um endereço compartilhado da equipe em vez de um endereço pessoal: a conta guarda o saldo e as chaves e deve continuar existindo após a saída de um colega.
2. 02
   Creditar o saldo

   A seção de recarga da plataforma permite adicionar crédito. Comece com um valor pequeno: é mais do que suficiente para testes e limita automaticamente o gasto caso um loop mal escrito fique fora de controle.
3. 03
   Gerar a chave

   Na seção de chaves de API, crie uma nova chave e dê a ela um nome que indique seu propósito (« essais-poste-clara », « prod-support »). Copie-a imediatamente: como na maioria das plataformas, ela só é exibida inteira no momento da criação.
4. 04
   Colocar a chave fora do código

   Coloque-a em uma variável de ambiente. Seu programa a lerá ao iniciar, e ela não aparecerá em nenhum repositório Git nem em capturas de tela.

https://platform.deepseek.com/api_keys

export DEEPSEEK_API_KEY="collez-votre-cle-ici"

$env:DEEPSEEK_API_KEY = "collez-votre-cle-ici"

#Primeira chamada: formato compatível com a OpenAI

A URL base da API é https://api.deepseek.com. A chave é enviada no cabeçalho Authorization, precedida pela palavra Bearer. Antes de enviar uma pergunta, comece pedindo a lista dos modelos que sua chave pode chamar: os identificadores mudam de geração para geração, e essa é a única lista que se mantém atualizada pela própria forma como é gerada.

curl https://api.deepseek.com/models \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY"

A resposta é um objeto JSON em que cada entrada contém um campo id. É esse identificador, copiado exatamente como aparece, que você deve colocar nas suas requisições. Muitos tutoriais usam os nomes históricos deepseek-chat e deepseek-reasoner: antes de reutilizá-los, verifique se eles estão realmente na lista retornada e consulte a página de preços para saber a qual modelo cada nome corresponde hoje.

curl https://api.deepseek.com/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -d '{
    "model": "IDENTIFIANT_DU_MODELE",
    "messages": [
      {"role": "system", "content": "Tu réponds en français, en trois phrases maximum."},
      {"role": "user", "content": "Explique la notion de token pour un modèle de langage."}
    ],
    "stream": false
  }'

Em Python, a biblioteca oficial da OpenAI dá conta do trabalho. Apenas dois parâmetros diferem de uma chamada à OpenAI: a chave e o endereço base.

pip install openai

import os
from openai import OpenAI

MODELE = "IDENTIFIANT_DU_MODELE"  # un id renvoyé par /models

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

reponse = client.chat.completions.create(
    model=MODELE,
    messages=[
        {"role": "system", "content": "Tu réponds en français, en trois phrases maximum."},
        {"role": "user", "content": "Explique la notion de token pour un modèle de langage."},
    ],
)

print(reponse.choices[0].message.content)
print(reponse.usage)  # le décompte qui sert à la facturation

A última linha é a mais útil para o que vem a seguir. O objeto usage indica quantos tokens você enviou (prompt_tokens) e quantos o modelo gerou (completion_tokens). A documentação do cache de contexto descreve dois campos adicionais, prompt_cache_hit_tokens e prompt_cache_miss_tokens, que separam os tokens de entrada já presentes no cache daqueles que não estavam. Exiba o objeto retornado pela sua própria chamada: é esse resultado que vale, não um exemplo.

#Preços da API da DeepSeek: ler a tabela oficial

Todos os preços estão em uma única página da documentação. Abra essa página ao lado deste guia: os parágrafos seguintes explicam o que significa cada linha, não o valor dela.

https://api-docs.deepseek.com/quick_start/pricing/

A grade se apresenta como uma tabela, com uma coluna por modelo. Os preços são expressos por milhão de tokens. Para um texto comum em francês, um token representa um pouco menos que uma palavra, mas a relação varia conforme o modelo e o conteúdo: para fazer a contagem, baseie-se no objeto usage das suas respostas, em vez de usar uma regra de conversão.

Entrada, falha no cache (cache miss)

O preço normal dos tokens que você envia: instrução de sistema, histórico da conversa, documentos anexados, pergunta.

Entrada, acerto no cache (cache hit)

Um preço reduzido aplicado à parte da sua requisição que o serviço já tratou recentemente e que está em cache.

Saída (output)

O preço dos tokens gerados pelo modelo. Compare essa linha com a de entrada: nas APIs desse tipo, ela geralmente apresenta o valor mais alto.

Tokens de raciocínio

Um modelo em modo de raciocínio elabora uma reflexão antes de responder. Verifique na página como esses tokens são contados: se forem cobrados como saída, uma resposta de três linhas pode custar o preço de uma página.

Contexto e saída máxima

O mesmo quadro mostra o comprimento do contexto e o tamanho máximo de uma resposta. Esses não são preços, mas definem o limite do que uma requisição pode custar.

Moeda

Anote a moeda exibida. Se a tabela de preços não estiver em euros, acrescente a taxa de câmbio e as eventuais tarifas do seu banco sobre as recargas.

#O cache de contexto, primeira fonte de diferença

O cache funciona por prefixo: se o início de uma requisição for igual ao início de uma requisição recente, essa parte comum é cobrada pela tarifa reduzida. Você não precisa ativar nada. Contudo, a ordem em que você constrói a requisição determina quanto você paga.

Conteúdo estável primeiro

Coloque no início o que não muda de uma chamada para outra: instrução do sistema, exemplos, documento de referência.

Variável no final

A pergunta do usuário, a data e um identificador de sessão vão no final. Uma data inserida na primeira linha é suficiente para tornar cada requisição única, assim perdendo o benefício do cache.

Medir em vez de supor

O cache não é uma garantia. A proporção efetivamente obtida pode ser consultada nos campos de cache do objeto usage. Se ela permanecer próxima de zero, mesmo com requisições semelhantes, é preciso revisar a forma como você constrói as requisições.

#Horas de baixa demanda e descontos temporários

Uma tabela de preços de API pode prever uma tarifa reduzida em uma faixa de horário ou durante um período de lançamento. Três verificações devem ser feitas antes de considerar essa tarifa em um orçamento.

O desconto aparece na página hoje?

Se a página oficial não mencionar nenhuma faixa de horário nem desconto, considere que não há nenhum dos dois. Não planeje um orçamento com base em um desconto mencionado em um artigo antigo.

Em qual fuso horário?

Os intervalos de horário geralmente são informados em UTC. Na França metropolitana, some uma hora no inverno e duas no verão.

Sua carga de trabalho pode ser transferida para outro horário?

Um horário fora de pico beneficia apenas os processos que podem esperar: resumos noturnos, classificação de documentos, geração em lote. Um assistente que atende clientes durante o dia não verá essa vantagem.

#O cálculo, com seus números

O custo de uma chamada é a soma de três produtos: tokens de entrada fora do cache, tokens de entrada em cache e tokens de saída, cada quantidade multiplicada pelo seu preço e depois dividida por um milhão. A função abaixo aplica essa fórmula ao objeto usage de uma resposta. Os três preços foram deixados em zero: copie-os você mesmo da página oficial, para o modelo que está chamando.

# Prix par million de tokens, à recopier depuis la page officielle
# Relevé le : (notez la date ici)
PRIX_ENTREE_CACHE_MANQUE = 0.0
PRIX_ENTREE_CACHE_ATTEINT = 0.0
PRIX_SORTIE = 0.0

def cout_appel(usage):
    en_cache = getattr(usage, "prompt_cache_hit_tokens", 0) or 0
    hors_cache = usage.prompt_tokens - en_cache
    total = (
        hors_cache * PRIX_ENTREE_CACHE_MANQUE
        + en_cache * PRIX_ENTREE_CACHE_ATTEINT
        + usage.completion_tokens * PRIX_SORTIE
    )
    return total / 1_000_000

# Exemple : print(cout_appel(reponse.usage))

#Acompanhar seu consumo

Você pode consultar o saldo restante na plataforma, e a API disponibiliza um endpoint que o retorna em JSON. Isso é útil para disparar um alerta antes de o saldo acabar, em vez de depois.

curl https://api.deepseek.com/user/balance \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY"

Registrar cada chamada

Registre a data, o modelo e os contadores do objeto usage. Duas semanas de registros em condições reais valem mais do que qualquer estimativa: essa é a base para decidir entre API e execução local.

Limitar a saída

O parâmetro max_tokens limita o comprimento de uma resposta, portanto seu custo máximo. Ajuste-o de acordo com a tarefa, em vez de deixar o valor padrão.

Monitorar o histórico

Em uma conversa, todo o histórico é reenviado a cada turno. Uma conversa com cinquenta trocas reenvia seu início cinquenta vezes, mesmo que o cache reduza o custo. Resuma ou trunque o histórico quando ele ultrapassar uma certa extensão.

Crédito gratuito e crédito recarregado

Se a sua conta tiver crédito gratuito além do crédito de recarga, a página de preços especifica em que ordem eles são consumidos. Verifique também se o crédito gratuito tem uma data de validade.

#API ou modelo local: como decidir

Não existe um limiar universal a partir do qual a execução local se torna mais barata, e este guia não inventa nenhum. O resultado depende de três números que só você conhece: seu volume real de tokens, a tabela de preços do dia e o preço do equipamento que você compraria. Os critérios abaixo muitas vezes permitem decidir antes mesmo de pegar a calculadora.

Privacidade

Dados pessoais, contratos, código proprietário, arquivos de clientes: com a API, esses conteúdos são enviados para um terceiro estabelecido fora da União Europeia, o que está sujeito ao RGPD e precisa ser validado com seu encarregado de proteção de dados. Na execução local, essa questão não se coloca. Muitas vezes, esse critério, por si só, determina a decisão.

Volume e regularidade

Uso baixo ou irregular favorece a API: você não paga quando não a utiliza. Uso sustentado e previsível favorece o local: a máquina custa o mesmo valor, independentemente de processar dez requisições ou dez mil.

Qualidade necessária

A API disponibiliza os grandes modelos do fornecedor. Em uma placa com 12 a 24 GB de VRAM, você poderá rodar modelos consideravelmente menores: conte com cerca de 9 GB para um 14B e 19 GB para um 32B em Q4_K_M. Se a sua tarefa exigir o grande modelo, executá-lo localmente exige hardware de outra categoria.

Disponibilidade

A API depende da carga do provedor e da sua conexão. A execução local depende da sua máquina, que você precisa monitorar e cujos problemas precisa resolver por conta própria.

Previsibilidade do orçamento

A fatura da API varia conforme o uso e pode surpreender. Rodar localmente tem um custo fixo, conhecido de antemão: compra ou aluguel, energia elétrica, tempo de manutenção.

Tempo humano

A API se conecta rapidamente: uma chave, algumas linhas de código. Um servidor local exige instalação, atualizações e uma pessoa que saiba o que fazer quando ele não responder. Esse tempo tem custo, deve ser incluído na comparação.

#A comparação em quatro etapas

1. 01
   Medir

   Execute seu caso de uso na API por duas semanas, registrando o objeto usage. Você obtém um volume mensal real, dividido entre entrada sem cache, entrada em cache e saída.
2. 02
   Calcular o custo da API

   Aplique a esse volume a tabela oficial de preços vigente no dia. Esse é o seu custo mensal de API, com a data do levantamento.
3. 03
   Calcular o custo da execução local

   Considere o preço da máquina capaz de rodar o modelo desejado, distribua esse valor pelo período de uso que você escolher e acrescente a eletricidade e o tempo de manutenção. O guia sobre o custo de um servidor GPU detalha esse cálculo.
4. 04
   Verificar a qualidade antes do preço

   Envie vinte requisições reais para o modelo local que seu hardware pode acomodar e compare as respostas com as da API. Se o resultado não for satisfatório, a comparação de custo perde sentido: você não está comparando o mesmo serviço.

#O mesmo código para os dois

Mudar de um para o outro não exige que você reescreva sua aplicação. O Ollama, que escuta por padrão em http://localhost:11434, também oferece uma interface compatível com a OpenAI no caminho /v1. O código abaixo alterna entre a API DeepSeek e um modelo local com base em uma variável de ambiente.

ollama pull deepseek-r1:14b

import os
from openai import OpenAI

LOCAL = os.environ.get("LLM_LOCAL") == "1"

if LOCAL:
    client = OpenAI(api_key="ollama", base_url="http://localhost:11434/v1")
    modele = "deepseek-r1:14b"
else:
    client = OpenAI(
        api_key=os.environ["DEEPSEEK_API_KEY"],
        base_url="https://api.deepseek.com",
    )
    modele = "IDENTIFIANT_DU_MODELE"  # un id renvoyé par /models

reponse = client.chat.completions.create(
    model=modele,
    messages=[{"role": "user", "content": "Résume ce texte en deux phrases : ..."}],
)
print(reponse.choices[0].message.content)

O modelo deepseek-r1:14b é uma versão destilada que cabe em uma placa de 12 GB como uma RTX 3060. Esse não é o modelo disponibilizado pela API: espere respostas menos precisas em tarefas difíceis. Essa configuração serve justamente para constatar isso em suas próprias requisições, na etapa quatro do método.

#Solução de problemas: erros comuns

A documentação de DeepSeek contém uma página com códigos de erro. Os casos abaixo são os encontrados no início; em caso de dúvida, a página oficial prevalece sobre este resumo.

401, autenticação recusada

A chave está ausente, truncada ou revogada. Verifique se a variável de ambiente está definida corretamente no terminal que inicia o programa e se nenhum espaço foi inserido ao copiar e colar.

402, saldo insuficiente

A conta não tem mais crédito. Recarregue pela plataforma. Um alerta no endpoint de saldo evita que isso aconteça em produção.

400 ou 422, solicitação inválida

O corpo JSON está mal formatado ou um parâmetro não é aceito. A causa mais comum é um identificador de modelo copiado de um tutorial antigo: volte para a lista /models.

429, excesso de requisições

Você envia mais rápido do que o serviço aceita. Espace as chamadas e tente novamente após intervalos cada vez maiores.

500 ou 503, erro ou sobrecarga do servidor

O problema está no servidor do fornecedor. Aguarde um pouco e tente novamente, e preveja na sua aplicação uma mensagem clara ou um modelo alternativo.

Resposta muito lenta

Em períodos de alta carga, uma requisição pode esperar muito antes de começar a responder. Defina um tempo máximo de espera do lado do cliente e ative o modo stream para exibir a resposta à medida que ela é gerada.

Fatura mais alta do que previsto

Três suspeitos comuns: tokens de raciocínio contabilizados como saída, poucas ocorrências de acerto no cache e um histórico de conversa reenviado na íntegra a cada turno. O log do objeto usage permite distinguir essas causas.

#Fontes oficiais

Os preços, a lista de modelos e as regras de cobrança mudam. Essas páginas do fornecedor são a referência e devem ser consultadas antes de qualquer decisão baseada em números.

https://api-docs.deepseek.com/quick_start/pricing/

https://api-docs.deepseek.com/

https://huggingface.co/deepseek-ai

#Para se aprofundar

Este guia se limita à chave, à interpretação da tabela de preços e ao método de decisão. Para fazer estimativas e instalar, estes guias do site dão continuidade ao assunto:

Quanto custa um servidor GPU para LLM?

Compra, aluguel ou API: os custos a somar na terceira etapa da comparação. https://quelllm.fr/guide/cout-serveur-gpu-llm

APIs de LLM gratuitas: o verdadeiro comparativo

As ofertas gratuitas, suas cotas e o que acontece com seus dados, se sua necessidade couber em uma faixa gratuita. https://quelllm.fr/guide/api-llm-gratuites-vs-local

DeepSeek V4 Pro local

O hardware exigido pelo grande modelo da família quando se deseja executá-lo localmente. https://quelllm.fr/guide/guide-deepseek-v4-pro

IA local vs ChatGPT

A mesma pergunta — na nuvem ou local — aplicada ao uso em conversas, em vez do uso via API. https://quelllm.fr/guide/ia-locale-vs-chatgpt