Como usar o deepseek-v4-flash-vision-exp pela API do hiapi: curl, Python e uma requisição que funciona

O deepseek-v4-flash-vision-exp é um modelo de texto e visão com capacidade de raciocínio no hiapi, acessível pelo endpoint padrão compatível com OpenAI: POST /v1/chat/completions. Ele lê imagens e texto ao mesmo tempo, oferece suporte a modo JSON e chamadas de função/ferramenta, e permite saída em streaming — tudo isso com a mesma estrutura de requisição de qualquer outro modelo de chat do hiapi. Este guia percorre uma requisição funcional, um comportamento que costuma pegar as pessoas de surpresa (o modelo raciocina antes de responder, e esse raciocínio consome seu orçamento de tokens) e práticas de produção que vale a pena conhecer antes de ir ao ar.

O que você vai construir

Um script que envia um prompt para deepseek-v4-flash-vision-exp — opcionalmente com uma imagem anexada — e lê a resposta real, não apenas seu rastro interno de raciocínio.

Pré-requisitos: uma chave de API do hiapi. Obtenha-a no console — cada requisição abaixo precisa dela no cabeçalho Authorization.

Exemplo mínimo funcional

curl

curl -s -X POST "https://api.hiapi.ai/v1/chat/completions" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash-vision-exp",
    "messages": [
      { "role": "user", "content": "Say OK and nothing else." }
    ],
    "max_tokens": 200
  }'

A resposta resumida fica assim:

{
  "choices": [
    {
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "OK",
        "reasoning_content": "We need to respond exactly \"OK\" and nothing else. ..."
      }
    }
  ],
  "usage": {
    "completion_tokens": 37,
    "completion_tokens_details": { "reasoning_tokens": 34 },
    "prompt_tokens": 89,
    "total_tokens": 126
  }
}

Dois campos importam aqui: message.content é a resposta real, enquanto message.reasoning_content é a cadeia de pensamento interna do modelo antes de definir essa resposta. usage.completion_tokens_details.reasoning_tokens informa quantos max_tokens do orçamento o processo de raciocínio consumiu — neste exemplo simples, 34 dos 37 tokens de completion foram usados no raciocínio antes de o modelo escrever "OK".

Aqui está a armadilha: definindo max_tokens baixo demais, o modelo pode gastar todo o orçamento raciocinando, fazendo com que content seja null e finish_reason seja "length". A mesma requisição com max_tokens: 10 retorna content: null — o modelo ainda estava pensando quando atingiu o limite. Dê espaço de sobra a este modelo: pelo menos 150–300 tokens para respostas curtas, e mais para conteúdo que exija real profundidade de raciocínio.

Python

import requests

resp = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={
        "Authorization": "Bearer sk-your-api-key",
        "Content-Type": "application/json",
    },
    json={
        "model": "deepseek-v4-flash-vision-exp",
        "messages": [
            {"role": "user", "content": "Say OK and nothing else."},
        ],
        "max_tokens": 200,
    },
    timeout=60,
)
resp.raise_for_status()
message = resp.json()["choices"][0]["message"]
print(message["content"])

Entrada visual

Você pode passar imagens junto com texto definindo content como um array de segmentos tipados — image_url aceita qualquer URL de imagem acessível publicamente:

curl -s -X POST "https://api.hiapi.ai/v1/chat/completions" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash-vision-exp",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "What color is the dominant background color of this image? One word." },
          { "type": "image_url", "image_url": { "url": "https://example.com/photo.jpg" } }
        ]
      }
    ],
    "max_tokens": 200
  }'

Com uma imagem de teste real, o modelo retornou "Beige", e o reasoning_content mostrou que ele passou por uma descrição visual antes de dar a resposta de uma palavra — o mesmo padrão de raciocinar primeiro e responder depois das requisições puramente textuais, só que fundamentado na imagem.

Modo JSON e chamadas de ferramenta

Saída JSON estruturada — adicione response_format: {"type": "json_object"} e mencione JSON no prompt:

{
  "model": "deepseek-v4-flash-vision-exp",
  "messages": [
    { "role": "user", "content": "Return a JSON object with keys name and age for a fictional person." }
  ],
  "response_format": { "type": "json_object" },
  "max_tokens": 300
}

message.content retorna como uma string JSON analisável ({"name": "Alex Doe", "age": 30}), enquanto reasoning_content ainda carrega o rascunho do modelo — analise apenas content, nunca reasoning_content.

Chamadas de função/ferramenta — passe um array tools padrão no estilo OpenAI:

{
  "model": "deepseek-v4-flash-vision-exp",
  "messages": [
    { "role": "user", "content": "What is the weather in Tokyo right now? Use the get_weather tool." }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
          "type": "object",
          "properties": { "city": { "type": "string" } },
          "required": ["city"]
        }
      }
    }
  ],
  "max_tokens": 300
}

O modelo responde com finish_reason: "tool_calls" e um array tool_calls (contendo function.name, function.arguments como string JSON, e o call_id que você devolve nos turnos seguintes) — o ciclo padrão de chamada de função da OpenAI funciona sem modificações.

Considerações de produção

• Reserve orçamento de max_tokens para o raciocínio, não só para a resposta. Este é um modelo de raciocínio — cada resposta inclui um processo de reasoning_content antes do content final, e ambos consomem do mesmo pool de max_tokens. Verifique usage.completion_tokens_details.reasoning_tokens nos testes iniciais para calibrar um teto seguro para seus prompts, e sempre confira finish_reason — "length" com content null significa que você foi cortado no meio do raciocínio, em vez de receber uma resposta real.
• O streaming funciona via stream: true. Diferentemente de alguns modelos de raciocínio no hiapi que forçam streaming, este modelo suporta os dois modos. No modo streaming, reasoning_content e content chegam como campos delta separados no mesmo fluxo de chunks — se você quiser exibir "pensamento" e "resposta" como estados de UI diferentes, armazene-os em buffers separados.
• Falhas de autenticação retornam claramente. Uma chave incorreta ou revogada retorna HTTP 401, com "code": "permission_denied" no corpo do erro, além de um request_id. Ramifique pelo campo code em vez de comparar strings de mensagem, e inclua o request_id ao contatar o suporte.
• Não exiba reasoning_content ao usuário final como se fosse a resposta. É conteúdo de rascunho não estruturado, não a resposta final — especialmente no modo JSON ou em chamadas de ferramenta, apenas content (ou tool_calls) se destina ao consumo por máquina.
• A entrada visual aceita URLs públicas, não base64 inline. image_url.url precisa ser buscável pelos servidores do hiapi; antes de enviar a requisição, hospede a imagem você mesmo ou use uma URL que você controle.

Leitura relacionada

• Página do modelo deepseek-v4-flash-vision-exp — referência completa de parâmetros e preços em tempo real
• Documentação da API do hiapi — autenticação, outras famílias de modelos e a lista completa de endpoints
• Preços do hiapi — tarifas por token do deepseek-v4-flash-vision-exp e de todos os outros modelos
• Guia da API do gpt-6-astra — o segundo modelo de raciocínio no hiapi, com um formato de integração diferente (somente streaming, API Responses) que vale a pena comparar

Perguntas frequentes

O deepseek-v4-flash-vision-exp suporta entrada visual? Sim. Envie um content em formato de array contendo um segmento text e um ou mais segmentos image_url, cada um apontando para uma URL de imagem acessível publicamente. O modelo raciocina sobre a imagem antes de responder, do mesmo jeito que faz com texto.

Por que message.content é null na minha resposta? Seu max_tokens está baixo demais, e o processo de raciocínio do modelo esgotou todo o orçamento antes de escrever a resposta. Verifique finish_reason — "length" com content: null é exatamente esse caso; aumente max_tokens e tente novamente.

Ele suporta modo JSON? Sim, via response_format: {"type": "json_object"}. O JSON chega como string em message.content, e você mesmo faz o parse; reasoning_content não faz parte da saída estruturada e deve ser ignorado nesse cenário.

Ele suporta chamadas de função/ferramenta? Sim, usando o formato padrão de array tools da OpenAI. Respostas que acionam ferramentas retornam finish_reason: "tool_calls" e um array tool_calls contendo o nome da função e os argumentos.

Posso receber a resposta em streaming? Sim — defina "stream": true e consuma os eventos chat.completion.chunk. Tanto content quanto reasoning_content são transmitidos como campos delta separados dentro do mesmo chunk.

Como são os erros de autenticação? HTTP 401, com um corpo JSON contendo "type": "hiapi_error", "code": "permission_denied", uma message legível por humanos e um request_id que pode ser repassado ao suporte (se o problema persistir).