Primeiros passos

Da chave de API à primeira resposta do modelo, com o código pronto em três linguagens.

Atualizado em 09 de ago. de 2026

Da chave até a primeira resposta de um modelo. Se você já usa a API da OpenAI, são duas linhas de mudança; se está começando do zero, dá para terminar em cinco minutos.

O que você precisa

Uma conta em platform.hinow.ai e uma chave de API
Node.js 18+, Python 3.9+, PHP 8+ ou qualquer cliente HTTP
Nada mais: não há SDK próprio para instalar

Prepare seu acesso

Gere uma chave de API ou entre na plataforma para criar sua conta.

Criar chave de API Criar conta

A única mudança que importa

A API do HiNow fala o mesmo protocolo da API da OpenAI. Os SDKs oficiais dela funcionam sem adaptação — você só troca o endereço base e a chave:

	Valor
Endereço base	`https://api.hinow.ai/v1`
Cabeçalho	`Authorization: Bearer hi_...`
Endpoint de conversa	`POST https://api.hinow.ai/v1/chat/completions`
Nome do modelo	`hinow/himax`, `hinow/hinova` ou `hinow/higenesis`

O prefixo hinow/ faz parte do nome

Mandar higenesis em vez de hinow/higenesis devolve 404 model_not_found. É o erro mais comum de quem está começando, e a mensagem não deixa óbvio o que faltou.

Instale o cliente

terminalbash

# Nada a instalar: o fetch já vem no Node 18+.
mkdir meu-app && cd meu-app
echo '{ "type": "module" }' > package.json

# Se preferir o SDK da OpenAI, ele também funciona:
# npm install openai

terminalbash

mkdir meu-app && cd meu-app
python3 -m venv .venv && source .venv/bin/activate

# O SDK oficial da OpenAI: você só aponta o base_url para a HiNow.
pip install openai

terminalbash

mkdir meu-app && cd meu-app

# Nada a instalar: usamos a extensão cURL, habilitada por padrão.
php -m | grep curl

Faça a primeira chamada

Exporte a chave e rode o arquivo. Ele é completo — não falta nada além da sua chave.

terminalbash

export HINOW_API_KEY="hi_sua_chave_aqui"

primeira-chamada.jsjavascript

const API = 'https://api.hinow.ai/v1/chat/completions';
const KEY = process.env.HINOW_API_KEY;

async function call(body) {
  const response = await fetch(API, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${KEY}` },
    body: JSON.stringify(body),
  });

  // Always read the status before touching the payload. Without this, a 401
  // shows up later as "cannot read properties of undefined".
  if (!response.ok) {
    throw new Error(`HiNow ${response.status}: ${await response.text()}`);
  }
  return response.json();
}

const data = await call({
  model: 'hinow/higenesis',
  messages: [{ role: 'user', content: 'Say hello in one short sentence.' }],
});

console.log(data.choices[0].message.content);

primeira-chamada.pypython

import os
from openai import OpenAI

# The HiNow API speaks the OpenAI protocol, so the official SDK works as is.
# The only change is base_url.
client = OpenAI(
    api_key=os.environ["HINOW_API_KEY"],
    base_url="https://api.hinow.ai/v1",
)

response = client.chat.completions.create(
    model="hinow/higenesis",
    messages=[{"role": "user", "content": "Say hello in one short sentence."}],
)

print(response.choices[0].message.content)

primeira-chamada.phpphp

<?php
$API = 'https://api.hinow.ai/v1/chat/completions';
$KEY = getenv('HINOW_API_KEY');

function call(array $body): array {
    global $API, $KEY;
    $ch = curl_init($API);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST => true,
        CURLOPT_HTTPHEADER => ['Content-Type: application/json', "Authorization: Bearer $KEY"],
        CURLOPT_POSTFIELDS => json_encode($body),
        CURLOPT_TIMEOUT => 180,
    ]);
    $raw = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    // Check the status before decoding. Without this, a 401 shows up later as
    // "trying to access array offset on null".
    if ($status !== 200) {
        throw new RuntimeException("HiNow $status: $raw");
    }
    return json_decode($raw, true);
}

$data = call([
    'model' => 'hinow/higenesis',
    'messages' => [['role' => 'user', 'content' => 'Say hello in one short sentence.']],
]);

echo $data['choices'][0]['message']['content'], PHP_EOL;

Se deu certo, sai uma frase curta como esta:

saída

Hello! How can I help you today?

Não funcionou? Comece por aqui

Os erros que a API devolve, o que cada um quer dizer e o que fazer.

Código	O que a API responde	O que resolve
`401`	`AUTH_MISSING`	Faltou o cabeçalho `Authorization` na requisição
`401`	`AUTH_INVALID_FORMAT`	O cabeçalho existe mas está vazio ou malformado. Use `Bearer` seguido da chave
`401`	`AUTH_TOKEN_INVALID`	A chave não existe ou foi revogada. Gere outra no painel
`404`	`model_not_found`	Confira o prefixo: é `hinow/higenesis`, não `higenesis`
`400`	`messages is required`	O corpo foi enviado sem o array `messages`, ou ele veio vazio
`429`	limite de uso	Reduza a frequência das chamadas ou espere alguns segundos e tente de novo

Confira o status antes de ler a resposta

Se o seu código pular direto para choices[0], um erro 401 aparece como "cannot read properties of undefined" e você vai procurar o problema no lugar errado. Os exemplos acima já checam o status primeiro — mantenha isso.

Mostrando a resposta enquanto ela chega

Numa tela de conversa, esperar a resposta inteira parece lento mesmo quando não é. Com stream: true as primeiras palavras aparecem em uma fração do tempo total, e a percepção muda completamente.

A resposta vem em linhas data: com um pedaço do texto em cada uma, até um data: [DONE] final.

streaming.jsjavascript

const response = await fetch('https://api.hinow.ai/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${process.env.HINOW_API_KEY}`,
  },
  body: JSON.stringify({
    model: 'hinow/hinova',
    messages: [{ role: 'user', content: 'List three uses for an LLM, one line each.' }],
    stream: true,
  }),
});

if (!response.ok) throw new Error(`HiNow ${response.status}: ${await response.text()}`);

const reader = response.body.getReader();
const decoder = new TextDecoder();
let buffer = '';

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  buffer += decoder.decode(value, { stream: true });
  const lines = buffer.split('\n');
  buffer = lines.pop();          // the last piece may be an incomplete line

  for (const line of lines) {
    if (!line.startsWith('data: ')) continue;
    const payload = line.slice(6).trim();
    if (payload === '[DONE]') continue;

    const chunk = JSON.parse(payload);
    const piece = chunk.choices[0]?.delta?.content;
    if (piece) process.stdout.write(piece);
  }
}
console.log();

streaming.pypython

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["HINOW_API_KEY"], base_url="https://api.hinow.ai/v1")

stream = client.chat.completions.create(
    model="hinow/hinova",
    messages=[{"role": "user", "content": "List three uses for an LLM, one line each."}],
    stream=True,
)

for chunk in stream:
    piece = chunk.choices[0].delta.content
    if piece:
        print(piece, end="", flush=True)
print()

streaming.phpphp

<?php
$ch = curl_init('https://api.hinow.ai/v1/chat/completions');
$buffer = '';

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Authorization: Bearer ' . getenv('HINOW_API_KEY'),
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'model' => 'hinow/hinova',
        'messages' => [['role' => 'user', 'content' => 'List three uses for an LLM, one line each.']],
        'stream' => true,
    ]),
    // cURL hands you whatever arrived, which may cut a line in half — so keep
    // the leftover in a buffer and only parse complete lines.
    CURLOPT_WRITEFUNCTION => function ($ch, $data) use (&$buffer) {
        $buffer .= $data;
        while (($pos = strpos($buffer, "\n")) !== false) {
            $line = trim(substr($buffer, 0, $pos));
            $buffer = substr($buffer, $pos + 1);
            if (!str_starts_with($line, 'data: ')) continue;
            $payload = trim(substr($line, 6));
            if ($payload === '[DONE]') continue;
            $chunk = json_decode($payload, true);
            echo $chunk['choices'][0]['delta']['content'] ?? '';
        }
        return strlen($data);
    },
]);

curl_exec($ch);
curl_close($ch);
echo PHP_EOL;

Cuidado com a linha cortada ao meio

Cada pedaço que chega da rede pode terminar no meio de uma linha. Os exemplos em Node e PHP guardam a sobra num buffer e só processam linhas completas — sem isso, o JSON.parse quebra de forma intermitente, e é o tipo de bug que só aparece em produção.

Próximos passos

AutenticaçãoOnde criar a chave, como guardar e o que fazer se vazar.Ver Escolher o modeloO que cada um faz bem e onde aplicar.Ver Construir um agenteFerramentas, laço e o código pronto em três linguagens.Ver

Esta página foi útil?