A integração da DeepSeek API não é complexa em si; o que costuma travar são três coisas: a qual plataforma a chave pertence, se a Base URL está completa e se o nome do modelo é a versão atual. Muitos casos de "não consigo chamar" não têm relação com capacidade do modelo, mas com credencial e endereço que não correspondem.
Este artigo começa no cadastro, recarga e criação da chave, segue para a primeira chamada com curl e Python e depois explica streaming, modo thinking, max_tokens e erros comuns. Seguindo a sequência, é possível deixar o caminho de integração funcionando.
Nota: DeepSeek é marca de seu titular; este artigo não tem vínculo com a DeepSeek oficial. Nomes de modelo, parâmetros e limites podem mudar entre versões. O texto usa como exemplo o formato comum da documentação oficial em outubro de 2026; em última instância, valem a documentação oficial e a página de preços do site.
1. Antes de integrar, separe quatro objetos
A maioria das falhas de integração não é problema de capacidade do modelo, mas de quatro objetos que não estão alinhados:
| Objeto | Função | Erro mais comum |
|---|---|---|
| Conta | Define saldo, fatura e propriedade da chave | Usar chave da plataforma A com endereço da plataforma B |
| API Key | Credencial de identidade | Copiar com espaço, quebra de linha ou aspas |
| Base URL | Para qual entrada a requisição vai | Omitir /v1 ou misturar endereço oficial e endereço do gateway |
| Nome do modelo | Campo model da requisição |
Reutilizar nome expirado de artigo antigo |
A regra de memorização é simples: chave e Base URL andam em par. Chave oficial só com entrada oficial; chave de gateway só com entrada de gateway. Misturar normalmente retorna 401.
2. Cadastro, recarga e criação da chave
No exemplo da plataforma aberta oficial, a ordem é:
- Abra a plataforma aberta da DeepSeek, registre-se e entre.
- Conclua as verificações necessárias indicadas na página e acesse a página de recarga.
- Na primeira vez, recarregue um valor pequeno, confirme o crédito e só depois rode tarefas em lote.
- Acesse a página API Keys, crie uma chave e nomeie conforme o uso, por exemplo
deepseek-testoudeepseek-prod. - Copie a chave e salve imediatamente em um gerenciador de senhas ou variável de ambiente do servidor; após fechar a página, o valor completo normalmente não é exibido de novo.
- Crie chaves separadas para teste e produção e configure alertas de orçamento ou consumo.
Se usar o ZSQH AI Gateway, o fluxo é parecido: crie a conta na página de cadastro, entre no console para criar a chave e recarregar, e depois chame no modo compatível com OpenAI descrito adiante. Não compartilhe a mesma chave entre os dois lados; se houver problema, fica difícil saber se é saldo, limite de taxa ou erro de configuração.
3. Base URL e nome do modelo: confirme antes de escrever código
A documentação oficial atual informa a entrada compatível com OpenAI como https://api.deepseek.com, com caminho de chat completions /chat/completions. Alguns tutoriais antigos usam https://api.deepseek.com/v1; a validade depende da documentação atual. Em caso de dúvida, use primeiro o endereço do exemplo oficial até funcionar.
| Item | Acesso oficial | ZSQH AI Gateway |
|---|---|---|
| Base URL | https://api.deepseek.com |
https://ai.zhongshangqihang.com/v1 |
| Caminho de chat | /chat/completions |
/v1/chat/completions |
| Origem da chave | Plataforma aberta oficial | Console do gateway |
| Nome do modelo | Conforme documentação oficial | Conforme a página de preços |
| Indicado para | Uso exclusivo da DeepSeek com acesso e pagamento oficiais funcionando | Entrada unificada, multimodelo ou fatura em moeda local |
Até outubro de 2026, a documentação oficial lista os modelos deepseek-flash e deepseek-v4-pro; nomes antigos como deepseek-chat e deepseek-reasoner não necessariamente continuam disponíveis. Não preencha o modelo de memória: confira a documentação oficial ou a página de preços do site antes de chamar.
4. Primeiro curl: faça a requisição mínima funcionar
Desligue primeiro o thinking para reduzir variáveis. Exemplo com a entrada oficial:
export DEEPSEEK_API_KEY="sk-sua-chave"
curl "https://api.deepseek.com/chat/completions" \
-H "Authorization: Bearer $DEEPSEEK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-flash",
"messages": [{"role": "user", "content": "Responda apenas OK"}],
"thinking": {"type": "disabled"},
"max_tokens": 32
}'
Se retornar 200 e choices[0].message.content tiver conteúdo, os três itens — chave, Base URL e nome do modelo — estão corretos. Para usar o gateway, troque apenas a URL por https://ai.zhongshangqihang.com/v1/chat/completions e use a chave do gateway.
Atenção: thinking é um parâmetro estendido da DeepSeek e não é suportado por todo serviço compatível com OpenAI. Se o gateway não suportar, remova o campo ou use o parâmetro correspondente indicado na documentação do gateway.
5. Primeira chamada em Python com o SDK da OpenAI
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["DEEPSEEK_API_KEY"],
base_url="https://api.deepseek.com", # no gateway, use https://ai.zhongshangqihang.com/v1
)
resp = client.chat.completions.create(
model="deepseek-flash",
messages=[
{"role": "system", "content": "Você é um assistente técnico. Responda de forma concisa."},
{"role": "user", "content": "Explique em três frases o que é um banco de dados vetorial."},
],
max_tokens=512,
extra_body={"thinking": {"type": "disabled"}},
)
print(resp.choices[0].message.content)
print(resp.usage)
O SDK da OpenAI não reconhece o campo thinking, por isso ele é enviado via extra_body. Depois de funcionar, observe primeiro o usage: quantos tokens de entrada e saída, se o acerto de cache é retornado e se o conteúdo de raciocínio é contado separadamente. Esses dados orientam melhor o custo e os timeouts do que a sensação de "parece rápido".
6. Streaming e reasoning_content
O thinking vem ativado por padrão, com intensidade padrão high. Quando ativado, a resposta traz reasoning_content, no mesmo nível do texto final content; no streaming, ele chega em blocos em delta.reasoning_content.
stream = client.chat.completions.create(
model="deepseek-flash",
messages=[{"role": "user", "content": "Escreva um exemplo em Python para ler um CSV"}],
stream=True,
max_tokens=4096,
reasoning_effort="high",
extra_body={"thinking": {"type": "enabled"}},
)
reasoning, answer = [], []
for chunk in stream:
if not chunk.choices:
continue
delta = chunk.choices[0].delta
if getattr(delta, "reasoning_content", None):
reasoning.append(delta.reasoning_content)
if delta.content:
answer.append(delta.content)
print("Raciocínio:", "".join(reasoning))
print("Resposta final:", "".join(answer))
Em conversas de vários turnos, se a requisição tiver tools, o reasoning_content do turno anterior deve ser reenviado integralmente, caso contrário pode retornar 400; sem tools, pode ser omitido, e o servidor o ignora. Para usuários finais, recomenda-se exibir o raciocínio recolhido, não totalmente aberto por padrão.
7. Como configurar max_tokens, temperature e thinking
| Tarefa | thinking | Ponto de partida sugerido | Observação |
|---|---|---|---|
| Teste de conectividade | Desligado | max_tokens 32–128 | Basta uma resposta curta |
| Classificação e extração | Desligado | 256–1024 | Saída estruturada reduz custo de raciocínio |
| Atendimento e redação | Ligado | 1024–4096 | Ajuste o effort conforme o resultado |
| Código e raciocínio complexo | Ligado | 4096 ou mais | Reserve orçamento para o raciocínio |
A documentação oficial atual indica contexto de 1M tokens e faixa de max_tokens de 1 a 384K; sem configuração, o padrão é 8K sem thinking e 64K com thinking, chegando a 128K quando reasoning_effort é max. Esses valores podem mudar; vale a documentação oficial.
No modo thinking, temperature, presence_penalty e frequency_penalty não têm efeito: ajustá-los não gera erro, mas também não altera o resultado. max_tokens não pode ser baixo demais: o raciocínio consome o orçamento de saída e, se faltar espaço, a resposta pode ser truncada antes do texto final.
8. Como diagnosticar 401, 402, 429 e timeout
| Sintoma | Causa comum | Tratamento |
|---|---|---|
| 401 | Chave errada, Bearer ausente, chave e Base URL de plataformas diferentes | Copie a chave de novo, verifique o cabeçalho e confirme a correspondência de entrada |
| 402 | Saldo insuficiente | Recarregue e tente de novo; confira o saldo antes de alterar código |
| 429 | Requisições rápidas demais, concorrência ou QPS acima do limite | Reduza concorrência, use backoff exponencial e separe chaves por projeto |
| 400/422 | Parâmetro, nome de modelo ou contexto inválido | Leia a mensagem, confira nome do modelo e max_tokens |
| Timeout | Rede, saída longa, tempo do thinking | Configure timeouts de conexão e leitura separados e limite a saída |
| 500/503 | Erro ou sobrecarga do upstream | Aguarde brevemente e retente com backoff |
O limite de concorrência do 429 é por conta, não dividido igualmente entre chaves. Várias chaves na mesma conta compartilham a cota; portanto, "criar mais chaves" não contorna o limite de concorrência. A documentação oficial também informa que, se a inferência não começar em 10 minutos, a conexão é encerrada; o cliente precisa reconhecer essa situação e tentar novamente.
9. Segurança da chave: cinco medidas antes do lançamento
- Manter a chave apenas em variável de ambiente do servidor ou gerenciador de segredos, nunca no front-end, repositório ou log.
- Usar uma chave para cada ambiente — teste, pré-produção e produção — para localizar e desativar rapidamente em caso de problema.
- Configurar alerta de saldo ou teto de gasto para conter chamadas anômalas.
- Registrar nos logs apenas o prefixo ou a impressão digital da chave, nunca o valor completo.
- Rotacionar imediatamente em caso de mudança de pessoal ou suspeita de vazamento e revisar o consumo recente.
10. Migrar do oficial para o gateway: mudar dois pontos
Na migração, altere primeiro base_url e api_key, confirme os nomes de modelo na página de preços do gateway e mantenha o restante do corpo da requisição o mais intacto possível. Compare saída, tempo e usage com o mesmo lote de prompts reais, observe de 3 a 7 dias e só então mude produção. Mantenha o acesso oficial como canal reserva para rollback rápido.
Se precisar de entrada unificada ou fatura multimodelo, crie uma chave de teste no ZSQH AI Gateway; preços e modelos disponíveis estão na página de preços.
Leituras relacionadas:
- Preços e cobrança da DeepSeek API
- DeepSeek API via relay e proxy: preços, estabilidade e migração
- Modelos e preços
Perguntas frequentes
A Base URL deve ou não incluir /v1?
Vale o exemplo atual da documentação oficial. A entrada oficial compatível com OpenAI é escrita como https://api.deepseek.com, com caminho de chat /chat/completions; gateways normalmente usam o prefixo /v1. Não adivinhe por tutoriais antigos: teste primeiro o endereço completo com curl.
O 401 é chave errada ou saldo insuficiente?
401 é falha de autenticação: verifique se a chave está correta, se o Bearer foi incluído e se chave e Base URL pertencem à mesma plataforma. Saldo insuficiente normalmente retorna 402; não confunda os dois.
A primeira chamada deve ativar thinking?
Recomenda-se desligar primeiro e confirmar o caminho com a requisição mais curta. Depois de validar chave, endereço e nome do modelo, ative conforme a tarefa e comece com um reasoning_effort mais baixo.
Qual valor de max_tokens é adequado?
Comece com um valor suficiente para a tarefa e aperte depois de funcionar. Classificação e extração podem começar em algumas centenas; textos longos e código pedem alguns milhares. No modo thinking, reserve orçamento para o raciocínio, pois valor baixo demais trunca o texto final.
Uma chave oficial pode ser usada com o endereço do gateway?
Não. Chave oficial corresponde apenas à entrada oficial; chave de gateway corresponde apenas à entrada do gateway. Misturar normalmente retorna 401. Ao trocar de entrada, troque chave e Base URL em conjunto.
