Blogue

Tutorial

Como chamar o kimi-k3.1-pro-highspeed pela API do HiAPI: exemplos em curl e Python

Nov 12, 2026
Imagem de capa do blog HiAPI: sobre um fundo marrom-escuro, faixas largas de tecido entrelaçam-se no ritmo de uma trama de cesto, com detalhes em bege e cor de latão, formando uma composição plana.
Nesta página

O que é o kimi-k3.1-pro-highspeed e quando escolhê-lo

O kimi-k3.1-pro-highspeed é um dos modelos de chat oferecidos pelo HiAPI. A forma de chamá-lo é idêntica à de qualquer outro modelo de chat da plataforma: envie uma lista de mensagens e receba uma conclusão. O "high-speed" no nome indica o compromisso pretendido — escolha-o quando priorizar latência em vez de profundidade de raciocínio bruta, ou seja, quando quiser tempos de resposta previsíveis em vez da resposta mais lenta e mais exaustiva.

Por isso ele se adequa bem a alguns tipos concretos de carga de trabalho:

  • Interfaces interativas — UIs de chat, autocompletar e assistentes inline, em que o usuário está esperando uma resposta.
  • Pipelines de alta vazão — tarefas de classificação, extração, resumo e reescrita em que você precisa de vazão e cada requisição individual produz resultados curtos.
  • Laços de agentes com múltiplos saltos — fluxos de várias etapas em que cada chamada é pequena e a latência total depende principalmente do número de idas e voltas, não de qualquer chamada individual.

Ele não é a escolha óbvia quando a tarefa exige raciocínio longo e cuidadoso sobre um contexto extenso, ou quando o conteúdo que você gera segue a lógica de "uma passada lenta mas de alta qualidade vale mais que várias passadas rápidas". Nesses casos, faça primeiro um benchmark da qualidade da saída e só depois otimize para velocidade — uma resposta rápida mas errada custa mais caro que uma resposta lenta mas correta.

Como o modelo é oferecido pela interface unificada do HiAPI, migrar depois para outro modelo — ou voltar dele — é apenas uma questão de alterar o payload da requisição, não de reescrever o código. Coloque o nome do modelo na configuração em vez de deixá-lo codificado no ponto de chamada, e você poderá fazer testes A/B com outros modelos sem tocar no código que monta a requisição.

O que "estilo chat" significa na prática

Cada requisição tem esta estrutura: um identificador de modelo, uma lista ordenada de mensagens (cada mensagem com role e content) e parâmetros opcionais como stream, temperature e max_tokens. O prompt de sistema é passado como uma mensagem com role: "system". Esse é todo o modelo mental — o restante deste guia é apenas o encanamento em torno dessa forma.

Pré-requisitos: credenciais, endpoint e nome do modelo

Antes de escrever qualquer código, confirme que você tem os quatro itens a seguir. A maioria das falhas na primeira chamada vem de algo faltando nesta lista, não de um bug no corpo da requisição.

1. Uma chave de API

Gere a chave no painel da sua conta HiAPI. Trate-a como segredo: carregue-a de uma variável de ambiente, nunca a envie para um repositório e faça rotação assim que ela aparecer em logs ou em um notebook compartilhado.

export HIAPI_API_KEY="your-key-here"

2. A URL base

O endpoint é formado pela URL base do HiAPI mais o caminho de chat completions. Mantenha a URL base na configuração, para que mudanças não exijam alteração de código:

export HIAPI_BASE_URL="https://api.hiapi.ai/v1"

3. O identificador do modelo

A string de modelo a enviar é exatamente:

kimi-k3.1-pro-highspeed

Copie caractere por caractere. O nome do modelo é correspondido literalmente — um espaço a mais, diferença de maiúsculas/minúsculas ou erro de digitação retorna um erro do tipo modelo não encontrado, e não um erro de validação de outro campo, o que pode fazer você investigar no lugar errado.

4. Um cliente capaz de enviar HTTPS

Para o exemplo curl abaixo, você só precisa de um shell com curl instalado, o que é padrão no macOS e na maioria das imagens Linux. Para a parte em Python, você precisa de Python 3.8+ e do pacote requests:

pip install requests

Se você preferir um cliente no estilo SDK, o mesmo endpoint, chave e nome de modelo se aplicam — o que importa é o formato na rede, e este guia usa HTTP bruto para que nada fique escondido atrás de uma abstração.

Verificação de sanidade

Antes de montar a requisição completa, faça uma verificação rápida para confirmar que a chave e a URL base resolvem — uma chamada deliberadamente mínima, com um prompt de uma única palavra. Se ela funcionar, qualquer falha posterior diz respeito ao seu payload, não às credenciais.

Uma requisição curl funcional

Abaixo está uma requisição completa, pronta para copiar e colar. Ela usa uma mensagem de sistema para definir o comportamento, uma mensagem de usuário como pedido real e fixa max_tokens para que a resposta permaneça curta durante os testes.

curl -s "$HIAPI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3.1-pro-highspeed",
    "messages": [
      {"role": "system", "content": "Você é um assistente técnico conciso. Responda em duas frases ou menos."},
      {"role": "user", "content": "Explique o que é uma chave de idempotência e por que ela é importante para repetições."}
    ],
    "temperature": 0.3,
    "max_tokens": 200,
    "stream": false
  }'

Explicação campo a campo

  • model — o identificador de modelo da seção anterior. Obrigatório.
  • messages — um array ordenado. system define persona e restrições; user carrega a tarefa. A ordem importa: mensagens mais ao final têm prioridade maior na orientação do comportamento. Para fluxos de múltiplos turnos, continue acrescentando turnos de user e assistant ao mesmo array, em vez de concatenar tudo em uma única mensagem de usuário gigante.
  • temperature — aleatoriedade da amostragem. Valores baixos produzem saídas mais reproduzíveis, que é o que extração e classificação exigem. Só aumente quando você realmente quiser variação.
  • max_tokens — limite superior da resposta gerada. Defini-lo explicitamente protege você de gerações descontroladas e torna a latência previsível.
  • stream — aqui é false, o que significa que você recebe um objeto JSON quando a geração termina. As seções seguintes abordam true.

O que é retornado

A resposta é um objeto JSON contendo um array choices. O texto que você quer fica em choices[0].message.content. Há também um bloco usage descrevendo o consumo de tokens — registre-o, porque, quando a cobrança é por token, é o seu único sinal de custo por requisição.

Se estiver depurando, passe a saída por um formatador para torná-la legível:

curl -s "$HIAPI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json | python -m json.tool

Coloque o corpo da requisição em payload.json e use -d @payload.json; assim que o payload passar de alguns campos, isso evita problemas de aspas no shell.

Portar a requisição para Python

O objetivo aqui não é um script de demonstração, mas uma função importável. Mantenha o payload idêntico ao da versão curl — mesmos campos, mesmos nomes, mesma string de modelo — para que o comportamento não mude ao trocar de ferramenta.

import os
import requests

BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai/v1")
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "kimi-k3.1-pro-highspeed"


def chat(
    user_message: str,
    system_message: str = "Você é um assistente técnico conciso.",
    temperature: float = 0.3,
    max_tokens: int = 400,
    timeout: float = 30.0,
) -> str:
    payload = {
        "model": MODEL,
        "messages": [
            {"role": "system", "content": system_message},
            {"role": "user", "content": user_message},
        ],
        "temperature": temperature,
        "max_tokens": max_tokens,
        "stream": False,
    }
    response = requests.post(
        f"{BASE_URL}/chat/completions",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=timeout,
    )
    response.raise_for_status()
    data = response.json()
    return data["choices"][0]["message"]["content"]

Depois:

print(chat("Resuma a diferença entre PUT e PATCH em uma frase."))

Por que escrever assim

  • Use json=payload em vez de JSON escrito à mão — o requests serializa corretamente e define o tipo de conteúdo, eliminando toda uma classe de bugs de aspas.
  • timeout explícito — sem ele, uma conexão travada pode pendurar seu processo de trabalho indefinidamente. Para conclusões curtas, trinta segundos é folgado; para caminhos interativos, reduza.
  • raise_for_status() cedo — você quer que a falha na camada HTTP apareça como exceção no limite da chamada, e não três linhas depois como um KeyError em choices.
  • Configuração no nível do módulo — chave, URL base e modelo ficam concentrados em um só lugar. Para fazer testes A/B com outros modelos depois, basta mudar uma constante.

Conversa com múltiplos turnos

Para conversas reais, aceite uma lista de mensagens como parâmetro em vez de montar duas mensagens fixas:

def chat_with_history(messages: list, **kwargs) -> dict:
    payload = {"model": MODEL, "messages": messages, "stream": False, **kwargs}
    r = requests.post(
        f"{BASE_URL}/chat/completions",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json=payload,
        timeout=30.0,
    )
    r.raise_for_status()
    body = r.json()
    return {
        "content": body["choices"][0]["message"]["content"],
        "usage": body.get("usage"),
    }

Acrescente a resposta do assistente de volta a messages com role: "assistant" para continuar a conversa, e poda os turnos antigos quando o histórico crescer — o contexto é cobrado, então um histórico de conversa ilimitado encarece silenciosamente cada requisição.

Habilitar e consumir respostas em streaming

Defina "stream": true e o servidor enviará a resposta de forma incremental como eventos enviados pelo servidor, em vez de enviar um único objeto no final. Para qualquer conteúdo que um usuário esteja acompanhando, vale o trabalho extra no cliente: mesmo que o tempo total de geração não mude, o tempo até o primeiro token cai bastante.

Do ponto de vista do curl

curl -N -s "$HIAPI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3.1-pro-highspeed",
    "messages": [{"role": "user", "content": "Escreva um haicai sobre repetição."}],
    "stream": true
  }'

-N desativa o buffer de saída do curl, para que você realmente veja os eventos chegando conforme são enviados. Você recebe uma série de linhas, cada uma começando com data: e contendo um fragmento JSON. O último evento é data: [DONE]. Trate esse sentinela como marcador de fim do stream, não como JSON analisável.

Cliente Python

import json
import requests


def stream_chat(user_message: str, timeout: float = 60.0) -> str:
    payload = {
        "model": MODEL,
        "messages": [{"role": "user", "content": user_message}],
        "stream": True,
    }
    pieces = []
    with requests.post(
        f"{BASE_URL}/chat/completions",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json=payload,
        stream=True,
        timeout=timeout,
    ) as r:
        r.raise_for_status()
        for raw in r.iter_lines(decode_unicode=True):
            if not raw or not raw.startswith("data: "):
                continue
            data = raw[len("data: "):].strip()
            if data == "[DONE]":
                break
            chunk = json.loads(data)
            delta = chunk["choices"][0].get("delta", {})
            text = delta.get("content")
            if text:
                pieces.append(text)
                print(text, end="", flush=True)
    return "".join(pieces)

Regras para manter o streaming correto

  • Concatene, não substitua. Cada bloco carrega apenas o novo fragmento. Acumule em uma lista e faça o join uma única vez ao final; anexar a uma string a cada iteração é complexidade quadrática em saídas longas.
  • Proteja-se contra conteúdo ausente. Alguns blocos carregam apenas metadados, então delta pode não ter a chave content. Use .get() e ignore valores vazios.
  • Trate linhas incompletas. Os limites de quadro podem dividir uma linha. O iter_lines cuida disso, mas, se você analisar o fluxo de bytes bruto por conta própria, faça buffer até ver um caractere de nova linha.
  • Defina um timeout adequado ao streaming. Um stream total pode legitimamente exceder um timeout curto de requisição. Use um timeout de leitura mais longo ou um prazo de leitura por bloco, em vez de desabilitar o timeout por completo.
  • Mantenha o caminho não-streaming. Quando você só precisa do texto final de uma tarefa em segundo plano, stream: false é mais simples e tem custo de raciocínio menor. Reserve o streaming para caminhos interativos.

Interpretar respostas de erro e projetar repetições

Repetir só ajuda quando a falha é temporária. Repetir cegamente uma requisição malformada só amplifica o erro. A distinção útil é: erros que você corrige no código versus erros que a rede ou o servidor resolverá por conta própria.

Classificação por código de status

Não repita — corrija a requisição:

  • 400 Bad Request — JSON malformado, campo obrigatório ausente ou valor de parâmetro inválido. Leia a mensagem de erro, corrija o payload e adicione um teste para evitar que volte a ocorrer.
  • 401 Unauthorized — chave ausente, malformada ou revogada. Verifique o formato do cabeçalho Authorization e se a variável de ambiente está realmente definida no processo em execução, não apenas no seu shell.
  • 403 Forbidden — a chave é válida, mas não tem permissão para executar esta ação ou usar este modelo. Um laço de repetição aqui é puro ruído.
  • 404 Not Found — geralmente caminho errado ou identificador de modelo desconhecido. Confirme a URL base e a string exata do modelo.
  • Erros de validação do tipo 422 — o tipo do parâmetro está correto, mas o valor não é aceitável (por exemplo, temperature fora do intervalo). Restrinja o valor no código.

Repita com backoff:

  • 429 Too Many Requests — você excedeu o limite de taxa. Faça backoff e, se a resposta incluir uma dica de retry-after, siga-a em vez de adivinhar.
  • 500 / 502 / 503 / 504 — falha no servidor ou no gateway. É exatamente aqui que o backoff exponencial se aplica.
  • Erros de conexão e timeouts — o socket falhou antes da resposta ser concluída. Repita, mas somente se a operação puder ser repetida com segurança.

Um laço de repetição bem comportado

import random
import time
import requests

RETRYABLE_STATUS = {429, 500, 502, 503, 504}


def post_with_retries(url, headers, payload, max_attempts=4, base_delay=1.0):
    for attempt in range(1, max_attempts + 1):
        try:
            r = requests.post(url, headers=headers, json=payload, timeout=30.0)
        except (requests.ConnectionError, requests.Timeout):
            if attempt == max_attempts:
                raise
        else:
            if r.status_code < 400:
                return r.json()
            if r.status_code not in RETRYABLE_STATUS:
                raise RuntimeError(f"não repetível {r.status_code}: {r.text[:200]}")
            if attempt == max_attempts:
                raise RuntimeError(f"repetições esgotadas, última {r.status_code}")
        delay = base_delay * (2 ** (attempt - 1))
        time.sleep(delay + random.uniform(0, 0.5))
    raise RuntimeError("unreachable")

Dois detalhes importantes em produção

  • Jitter não é opcional. Sem ele, um grupo de processos de trabalho que atingirem o limite de taxa ao mesmo tempo repetirá em uníssono, recriando o pico. O termo aleatório acima os espalha.
  • Limite o tempo total, não só o número de tentativas. Quatro tentativas com backoff exponencial podem ultrapassar o prazo da sua requisição. Limite o número de tentativas para que o pior caso caiba no orçamento do chamador e repasse o tempo restante como timeout da próxima tentativa.

Não repita requisições em streaming após uma falha parcial, a menos que você decida o que fazer com o texto já enviado ao usuário. O padrão comum é repetir apenas se nada tiver sido exibido ainda; caso contrário, exponha o truncamento.

Checklist antes de entrar em produção

Antes de este código se tornar carga crítica, percorra uma lista curta.

  • Timeouts em todo lugar. Cada requisição tem timeout explícito de conexão/leitura, e o valor vem do seu orçamento de latência, não copiado do exemplo.
  • Segredos fora do repositório. A chave de API vem do ambiente ou de um gerenciador de segredos e nunca é gravada em logs. Remova os cabeçalhos de qualquer logger de requisições.
  • Nome do modelo em um único lugar. kimi-k3.1-pro-highspeed aparece como uma única constante, para que você possa substituí-lo ou fazer testes A/B sem busca e substituição.
  • Erros classificados, não engolidos. Os caminhos repetível e não repetível são distintos no código, o backoff inclui jitter e o número de tentativas tem limite.
  • Registre o uso. Grave o uso de tokens retornado em cada resposta junto com latência e status. Quando a cobrança é por token, esse é o alerta antecipado de que os prompts estão ficando silenciosamente grandes demais.
  • O caminho de streaming foi testado de verdade. Verifique que a saída concatenada é igual à saída não-streaming para o mesmo prompt e que uma queda no meio do stream não deixa sua UI em estado quebrado.
  • Custo controlado por design. Sempre defina max_tokens, pode o histórico da conversa e resuma documentos longos antes de inseri-los no contexto — essas três alavancas mantêm o gasto proporcional ao valor.

Feito isso, passar da prova de conceito em curl para um chamador em produção é principalmente trabalho de configuração. Comece pela função não-streaming, adicione streaming quando o caminho interativo existir e deixe o wrapper de repetição absorver as falhas que você não consegue prevenir.

Artigos relacionados

Ver todos os artigos →

Comece a criar com artefactos de IA persistentes

Obtenha a sua chave de API e chame modelos de imagem, vídeo e áudio através de uma única API baseada em tasks.

Ler a documentação da API