Como usar o DeepSeek V4 Flash via API hiapi: curl, Python e exemplos de requisição executáveis

O DeepSeek V4 Flash é um modelo de chat com raciocínio e, no hiapi, sua integração funciona de forma diferente da maioria dos modelos da plataforma: ele não usa a fila assíncrona POST /v1/tasks utilizada para geração de imagens e vídeos, mas sim um endpoint de chat completions compatível com OpenAI — POST /v1/chat/completions, com suporte a modo síncrono ou streaming e sem necessidade de polling. Este tutorial mostrará como enviar uma requisição executável com curl e Python e, em seguida, abordará dois problemas que realmente costumam surgir em ambientes de produção.

O que você vai construir

Um script mínimo que envia um prompt ao deepseek-v4-flash através do hiapi e imprime a resposta do modelo — além dos padrões de que você precisará quando esse script se tornar uma integração real: lidar com o orçamento de tokens de raciocínio do modelo, streaming, retentativas e a estrutura de erros descrita na documentação.

Pré-requisitos: uma chave de API do hiapi. Obtenha-a no painel do hiapi — cada requisição abaixo é autenticada via Authorization: Bearer sk-<your-key>.

Exemplo mínimo executável

curl

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [{"role": "user", "content": "Explain what a hash table is in two sentences."}],
    "max_tokens": 500
  }'

Uma chamada bem-sucedida retorna o objeto padrão de chat completion:

{
  "id": "gen-...",
  "object": "chat.completion",
  "model": "deepseek/deepseek-v4-flash",
  "provider": "DeepInfra",
  "choices": [{
    "index": 0,
    "finish_reason": "stop",
    "message": {"role": "assistant", "content": "A hash table is ...", "reasoning": "..."}
  }],
  "usage": {
    "prompt_tokens": 14, "completion_tokens": 187, "total_tokens": 201,
    "completion_tokens_details": {"reasoning_tokens": 96}
  }
}

Dois pontos merecem atenção: na requisição, use o ID de modelo puro deepseek-v4-flash — o hiapi o resolve internamente para o provedor upstream, enquanto o campo model na resposta ecoa um ID qualificado pelo provedor (deepseek/deepseek-v4-flash), que você deve tratar como informação de referência, e não como parâmetro de requisição a ser reenviado. Além disso, a mensagem traz o campo reasoning além de content — trata-se de um modelo de raciocínio, e usage.completion_tokens_details.reasoning_tokens informa quantos dos completion_tokens consumidos foram gastos nessa cadeia de pensamento e quantos foram usados na resposta visível.

Python

import os
import requests

resp = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"},
    json={
        "model": "deepseek-v4-flash",
        "messages": [{"role": "user", "content": "Explain what a hash table is in two sentences."}],
        "max_tokens": 500,
    },
    timeout=60,
)
resp.raise_for_status()
data = resp.json()
print(data["choices"][0]["message"]["content"])

Como esse endpoint é compatível com OpenAI, o código também funciona sem alterações com o SDK oficial do openai para Python — basta apontar base_url para https://api.hiapi.ai/v1 e passar a chave do hiapi como api_key.

Padrões de uso em produção

A armadilha do orçamento de raciocínio: não defina max_tokens muito baixo

max_tokens limita o custo total de raciocínio mais resposta, e não apenas a resposta visível. Se o modelo ainda estiver raciocinando ao atingir o limite, você receberá uma resposta com finish_reason: "length" e content: null — tokens consumidos e cobrados, mas sem nenhum conteúdo apresentável. Para qualquer prompt que não seja trivial, deixe uma margem real na requisição (pelo menos algumas centenas de tokens), em vez de reduzir max_tokens ao valor que você acha que a resposta precisa.

Desativar o raciocínio para tarefas simples e determinísticas

Se a tarefa não precisa de cadeia de pensamento — classificação, consultas curtas, conversão de formato — você pode suprimir totalmente o raciocínio:

{
  "model": "deepseek-v4-flash",
  "messages": [{"role": "user", "content": "Say OK and nothing else."}],
  "max_tokens": 50,
  "reasoning": {"enabled": false}
}

Com reasoning.enabled: false, o message.reasoning na resposta retorna null e completion_tokens_details.reasoning_tokens fica 0 — você paga apenas pela saída visível e a latência diminui na mesma proporção. Mantenha o comportamento padrão (raciocínio ativado) apenas para tarefas em que o pensamento extra realmente melhore a resposta.

Streaming

Defina "stream": true para receber eventos enviados pelo servidor no estilo padrão da OpenAI, sem esperar pela resposta completa:

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"Count to 5."}],"stream":true}'

Cada bloco de dados é uma linha data: {...} carregando o choices[0].delta.content incremental; o último bloco contém usage, e o fluxo termina com a linha literal data: [DONE]. Faça o parsing à medida que os blocos chegam, em vez de bufferizar a resposta inteira no cliente — é justamente esse o propósito do streaming em uma interface de chat.

Idempotência e retentativas

O chat completions aqui é uma chamada HTTP sem estado, não uma tarefa enfileirada — não há ID de tarefa para consultar por polling, nem risco de reenviar conteúdo acidentalmente para uma fila. As retentativas tratam de problemas HTTP comuns: em erros de transporte ou 5xx, retente com backoff; em 429, respeite o cabeçalho Retry-After antes de retentar (consulte a documentação de limites de taxa). Para erros 4xx que indicam requisição inválida (como messages malformado), não retente — corrija o corpo da requisição.

Tratamento de erros

Uma chave inválida ou ausente retorna HTTP 401:

{
  "error": {
    "code": "permission_denied",
    "message": "...",
    "request_id": "...",
    "type": "hiapi_error"
  }
}

No manipulador de erros, verifique error.code em vez de fazer correspondência de padrões na string da mensagem — permission_denied é o identificador estável. Se você receber esse erro usando uma chave que considera válida, consulte a documentação de autenticação.

Leituras relacionadas

• Documentação de autenticação do hiapi — como o cabeçalho Authorization e o escopo das chaves funcionam em toda a plataforma.
• Documentação de limites de taxa do hiapi — comportamento do 429 e Retry-After.
• Página do modelo deepseek-v4-flash — preços atuais e descrição das capacidades.

FAQ

Preciso fazer polling dos resultados como nos modelos de imagem/vídeo do hiapi? Não. A geração de imagens e vídeos no hiapi usa a fila assíncrona /v1/tasks (criar → consultar por polling ou callback → baixar output[0].url). Modelos de chat como o deepseek-v4-flash são apenas chamadas HTTP síncronas (ou em streaming) para /v1/chat/completions — você recebe a resposta diretamente.

Por que usage.completion_tokens parece maior do que a resposta visível deveria custar? Porque ele inclui os tokens de raciocínio. Verifique usage.completion_tokens_details.reasoning_tokens para ver a divisão e use "reasoning": {"enabled": false} quando não precisar que o modelo exiba o processo de pensamento.

Minha resposta veio com "finish_reason": "length" e content vazio — o que aconteceu? O modelo esgotou max_tokens ainda na fase de raciocínio e nunca escreveu a resposta visível. Aumente max_tokens ou desative o raciocínio para prompts mais simples.

Posso usar o SDK oficial da OpenAI em vez de chamadas HTTP brutas? Sim — defina o base_url do SDK como https://api.hiapi.ai/v1 e o api_key como sua chave do hiapi; a estrutura de requisição/resposta é a mesma.

Onde encontro os preços atuais do modelo? Na página do modelo ou na página de preços em tempo real — o custo por token pode variar ligeiramente conforme o roteamento para o provedor upstream, então consulte lá em vez de confiar nos números deste artigo.