Como usar kimi-k3 via API hiapi: curl, Python e exemplos de requisição executáveis

O que você vai construir

kimi-k3 é um modelo de chat com capacidade de raciocínio, disponível no hiapi através do endpoint padrão compatível com OpenAI /v1/chat/completions — sem necessidade de polling de tarefas assíncronas nem de upload de imagens. Este guia leva você do zero até uma chamada executável com curl e Python, e depois explica duas coisas que costumam causar problemas em produção: os tokens de raciocínio que consomem seu orçamento de max_tokens e a saída em streaming.

Pré-requisitos: uma chave de API hiapi. Se ainda não tiver uma, obtenha-a no console — cada requisição abaixo é autenticada via Authorization: Bearer sk-<your-key>.

Exemplo mínimo executável

kimi-k3 é um modelo de texto, portanto não passa pela fila de tarefas /v1/tasks que o hiapi usa para modelos de imagem/vídeo — é uma chamada direta e síncrona de completion de chat.

curl

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [
      {"role": "user", "content": "Explain what an API rate limit is in two sentences."}
    ],
    "max_tokens": 300
  }'

Python

import requests

resp = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={
        "Authorization": "Bearer sk-<your-key>",
        "Content-Type": "application/json",
    },
    json={
        "model": "kimi-k3",
        "messages": [
            {"role": "user", "content": "Explain what an API rate limit is in two sentences."}
        ],
        "max_tokens": 300,
    },
    timeout=60,
)
resp.raise_for_status()
data = resp.json()
print(data["choices"][0]["message"]["content"])

Uma resposta bem-sucedida é assim:

{
  "id": "chatcmpl-fb762e7481bd4442abb1d8ed3892b4f5",
  "model": "FW-Kimi-K3",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "OK",
        "reasoning_content": "We need answer user: \"Reply with exactly the word OK.\" ..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 95,
    "completion_tokens": 52,
    "total_tokens": 147,
    "completion_tokens_details": {"reasoning_tokens": 38}
  }
}

A resposta final fica em choices[0].message.content. O ID de modelo na requisição é o ID puro kimi-k3 — o hiapi faz o mapeamento internamente (o campo model do corpo da resposta ecoa o rótulo subjacente, por exemplo FW-Kimi-K3; isso é o comportamento esperado).

A única pegadinha: tokens de raciocínio e max_tokens

kimi-k3 é um modelo de raciocínio — ele primeiro grava a cadeia de pensamento em message.reasoning_content antes de gerar o content final, e ambos compartilham o mesmo orçamento de max_tokens. Se max_tokens for definido muito baixo, o modelo pode consumir todo o orçamento em raciocínio e retornar finish_reason: "length" com o campo content vazio:

{
  "choices": [{
    "message": {"content": "", "reasoning_content": "The user is asking me to say \"OK\""},
    "finish_reason": "length"
  }]
}

Isso não é um bug — é apenas o processo de raciocínio esgotando o espaço antes de chegar à resposta final. Há duas formas de lidar com isso:

• Deixe folga suficiente. Para respostas curtas e factuais, um max_tokens de 200–300 normalmente cobre raciocínio e resposta. Para gerações mais longas, aumente o orçamento proporcionalmente.
• Verifique o finish_reason. Se vier "length" e content estiver vazio, aumente max_tokens e tente novamente; não trate a string vazia como resposta final.

Saída em streaming

Defina "stream": true para receber Server-Sent Events (SSE) sem esperar pela resposta completa. Os chunks carregam primeiro deltas de delta.reasoning_content e, depois que o modelo começa a escrever a resposta final, deltas de delta.content:

import requests

with requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={
        "Authorization": "Bearer sk-<your-key>",
        "Content-Type": "application/json",
    },
    json={
        "model": "kimi-k3",
        "messages": [{"role": "user", "content": "Count to 3."}],
        "max_tokens": 200,
        "stream": True,
    },
    stream=True,
    timeout=60,
) as resp:
    for line in resp.iter_lines():
        if line and line.startswith(b"data: ") and line != b"data: [DONE]":
            print(line.decode("utf-8"))

Se você estiver construindo uma interface de chat, renderize em streaming apenas delta.content — a maioria dos aplicativos esconde delta.reasoning_content atrás de um botão "pensando" ou o exibe recolhido, em vez de mostrá-lo inline.

Considerações para produção

• Tratamento de erros. Uma chave inválida ou ausente retorna HTTP 401 com um corpo de resposta estruturado:

  {"error": {"code": "permission_denied", "message": "This API key is invalid...", "request_id": "...", "type": "hiapi_error"}}
  

  Registre o request_id — a equipe de suporte precisará dele se você abrir um ticket.
• Retentativas. Completions de chat são síncronos, portanto não há ID de tarefa para consultar nem callback para registrar (esse padrão se aplica aos modelos assíncronos de imagem/vídeo do hiapi, não a texto). Em caso de timeout ou 5xx, basta repetir a requisição; como o servidor não enfileira nenhuma tarefa, trate isso como uma retentativa comum, idempotente, semelhante a um GET.
• Cobrança. kimi-k3 é cobrado por token como os demais modelos de texto da plataforma — consulte as tarifas atuais na página de preços antes de estimar custos em escala, pois os tokens de raciocínio contam como tokens de completion.

Perguntas frequentes

kimi-k3 suporta saída em streaming? Sim — passe "stream": true e leia a resposta text/event-stream conforme mostrado acima.

Por que o content da minha resposta está vazio? O finish_reason quase certamente é "length" — o modelo gastou todo o orçamento de max_tokens em reasoning_content antes de chegar à resposta final. Aumente max_tokens e tente novamente.

kimi-k3 precisa do endpoint /v1/tasks do hiapi? Não. O /v1/tasks é usado por modelos assíncronos de geração de imagem, vídeo e música. kimi-k3 é um modelo de texto síncrono, servido pelo endpoint padrão /v1/chat/completions.

Posso usar o SDK Python da OpenAI em vez de requests nativo? Sim — aponte o base_url do SDK para https://api.hiapi.ai/v1 e passe sua chave hiapi como chave de API; a estrutura de requisição/resposta é compatível com OpenAI.

Qual ID de modelo devo passar na requisição? O ID puro kimi-k3. Você verá o rótulo interno, como FW-Kimi-K3, ecoado no campo model do corpo da resposta — isso é o comportamento esperado e não afeta cobrança nem comportamento.