Como usar o deepseek-v4.1-flash pela API hiapi: curl, Python e exemplos de requisição funcionais

deepseek-v4.1-flash é um modelo de raciocínio rápido e de baixo custo, acessível pela API unificada da hiapi. Atualmente está marcado como Preview na página do modelo, o que significa que a build subjacente pode ser trocada, enquanto o ID público do modelo (deepseek-v4.1-flash) permanece estável — você não precisa alterar nenhum código quando a rotação acontecer. Este guia mostra uma requisição que realmente funciona: o endpoint correto, os campos corretos, o cabeçalho de autenticação correto.

Pré-requisitos

• Uma chave de API da hiapi (sk-...). Obtenha-a no seu console hiapi e então exporte:

export HIAPI_API_KEY="sk-your-key-here"

• Qualquer cliente HTTP serve. Os exemplos abaixo usam curl e requests do Python, com notas sobre o uso do SDK oficial da OpenAI.

Exemplo mínimo funcional

A hiapi oferece dois endpoints de texto. /v1/responses é o endpoint canônico e recomendado (formato da OpenAI Responses API, eventos SSE semânticos). /v1/chat/completions é o endpoint legado (formato OpenAI Chat Completions) — use-o apenas ao portar uma integração existente de Chat Completions. Este guia usa /v1/responses.

curl

curl https://api.hiapi.ai/v1/responses \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4.1-flash",
    "input": [
      {"role": "user", "content": "Explain what a hash map is in two sentences."}
    ]
  }'

Uma resposta bem-sucedida retorna um array output contendo a resposta do modelo, além de um bloco usage:

{
  "id": "resp_...",
  "model": "deepseek-v4.1-flash-expires-on-0910",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {"type": "output_text", "text": "A hash map stores key-value pairs..."}
      ]
    }
  ],
  "usage": {
    "input_tokens": 14,
    "output_tokens": 42,
    "total_tokens": 56,
    "output_tokens_details": {"reasoning_tokens": 0}
  }
}

Observe que o campo model na resposta aparece como deepseek-v4.1-flash-expires-on-0910 — essa é a build interna fixa que atualmente atende esse modelo de preview. Esse é o comportamento esperado dos modelos de preview na hiapi, e não um sinal de que o modelo será descontinuado; continue requisitando o ID simples deepseek-v4.1-flash e a hiapi roteará automaticamente para a build atual.

Python

import os
import requests

resp = requests.post(
    "https://api.hiapi.ai/v1/responses",
    headers={
        "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "deepseek-v4.1-flash",
        "input": [
            {"role": "user", "content": "Explain what a hash map is in two sentences."}
        ],
    },
    timeout=60,
)
resp.raise_for_status()
data = resp.json()
print(data["output"][0]["content"][0]["text"])
print(data["usage"])

Usando o SDK da OpenAI

Os endpoints /v1/responses e /v1/chat/completions da hiapi são compatíveis com o SDK oficial da OpenAI — basta apontar o base URL para a hiapi e manter o ID do modelo sem sufixo:

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["HIAPI_API_KEY"],
    base_url="https://api.hiapi.ai/v1",
)
resp = client.responses.create(
    model="deepseek-v4.1-flash",
    input=[{"role": "user", "content": "Explain what a hash map is in two sentences."}],
)
print(resp.output[0].content[0].text)

Práticas para produção

As requisições são sem estado — é preciso reenviar a conversa inteira

A hiapi não mantém estado de conversa no servidor para esse modelo. Toda requisição precisa incluir o histórico completo de mensagens em input. Não envie store, previous_response_id, conversation, background ou context_management — nada disso é suportado e será ignorado ou rejeitado. Para conversas com múltiplos turnos, acrescente você mesmo cada nova mensagem de user/assistant ao array input e envie o array inteiro em cada requisição.

history = [{"role": "user", "content": "What's a hash map?"}]
# ... call, get a reply, then append it and the next question ...
history.append({"role": "assistant", "content": "<model's previous reply>"})
history.append({"role": "user", "content": "How is that different from a hash set?"})

Intensidade de raciocínio

deepseek-v4.1-flash aceita um objeto reasoning que controla quanto raciocínio interno o modelo faz antes de responder. A enumeração de effort desse modelo é none | high | max — note que este não é o conjunto low/medium/high usado por alguns outros modelos de raciocínio na hiapi, então não presuma que dá para reutilizar a mesma configuração.

{
  "model": "deepseek-v4.1-flash",
  "input": [{"role": "user", "content": "Prove that the square root of 2 is irrational."}],
  "reasoning": {"effort": "high"}
}

Os tokens de raciocínio são cobrados como tokens de saída e reportados separadamente em usage.output_tokens_details.reasoning_tokens, portanto requisições com esforço high/max podem custar bem mais que none, mesmo quando a resposta visível tem o mesmo tamanho. Antes de definir o esforço padrão para o tráfego de produção, confira as tarifas atuais por token na página de preços.

Streaming

Passe "stream": true para receber Server-Sent Events em vez de um único bloco JSON. O /v1/responses transmite eventos semânticos, e não deltas de texto bruto embrulhados em marcadores [DONE] ao estilo Chat-Completions. A sequência de eventos de uma conclusão bem-sucedida é:

response.created
response.in_progress
response.output_item.added
response.content_part.added
response.output_text.delta   (repeated, one per chunk of text)
response.output_text.done
response.content_part.done
response.output_item.done
response.completed

Trate response.completed como o evento de término bem-sucedido. Trate também response.incomplete (por exemplo, ao atingir limites de token/comprimento) e response.failed (erro no servidor) como estados de término — não presuma que todo stream termina com response.completed.

import json
import requests

with requests.post(
    "https://api.hiapi.ai/v1/responses",
    headers={
        "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "deepseek-v4.1-flash",
        "input": [{"role": "user", "content": "Count to 5."}],
        "stream": True,
    },
    stream=True,
    timeout=60,
) as r:
    for line in r.iter_lines():
        if not line or not line.startswith(b"data: "):
            continue
        event = json.loads(line[len(b"data: "):])
        if event.get("type") == "response.output_text.delta":
            print(event["delta"], end="", flush=True)
        elif event.get("type") in ("response.completed", "response.incomplete", "response.failed"):
            break

Tratamento de erros

Uma chave de API inválida ou ausente retorna HTTP 401, com um corpo de erro estruturado:

{"error": {"code": "permission_denied", "message": "..."}}

Verifique resp.status_code e tome decisões com base em error.code, em vez de analisar a string da mensagem, porque o texto da mensagem pode mudar de redação sem aviso.

Documentação relacionada

• Página do modelo deepseek-v4.1-flash
• Referência de /v1/responses
• Referência de /v1/chat/completions
• Autenticação
• Preços

Perguntas frequentes

O deepseek-v4.1-flash é para produção ou apenas para testes? Ele está marcado como preview, o que na hiapi significa que o modelo está no ar e pode ser chamado normalmente, mas a build subjacente pode ser trocada conforme a hiapi decidir. O ID público do modelo não muda na rotação — seu código continua funcionando sem alterações. Se você precisa de um compromisso formal fora do preview, veja as variantes do DeepSeek v4 que não são preview na lista de modelos.

Por que a resposta mostra um nome de modelo diferente do que eu pedi? Você verá no campo model da resposta um valor como deepseek-v4.1-flash-expires-on-0910. Essa é a build fixa específica que atualmente atende sua requisição sob o ID deepseek-v4.1-flash — esse é o comportamento esperado de um modelo de preview, não um erro.

Posso usar /v1/chat/completions em vez de /v1/responses? Sim, a hiapi suporta ambos para esse modelo. O /v1/chat/completions usa o formato de requisição/resposta do OpenAI Chat Completions (array messages, choices[0].message.content), e não o formato input/output de /v1/responses. Escolha o que combina com sua integração atual; integrações novas devem usar /v1/responses por padrão.

A hiapi armazena meu histórico de conversa para eu enviar só a mensagem mais recente? Não. Esse modelo não tem previous_response_id nem estado de conversa no servidor — envie o histórico completo de mensagens em input a cada requisição.

O que reasoning.effort: "none" realmente ignora? Ele ignora completamente o processo de raciocínio interno do modelo e responde diretamente. Para tarefas que se beneficiam de raciocínio em várias etapas (matemática, lógica com múltiplas restrições), use "high" ou "max"; quanto maior o esforço, maior o consumo de tokens de saída e maior a latência.

Requisições com streaming e sem streaming precisam de chaves de API separadas? Não — a mesma chave Authorization: Bearer sk-... vale para as duas. O streaming é controlado inteiramente pelo campo "stream": true no corpo da requisição.