Início Rápido
Faça sua primeira chamada à API HINOW e avance para streaming, JSON, ferramentas, imagens, arquivos, embeddings e mídia.
Atualizado em 09 de ago. de 2026
- 1
Crie uma chave
Gere uma chave em platform.hinow.ai e guarde-a como segredo no servidor.
- 2
Envie uma mensagem
Faça um POST para https://api.hinow.ai/v1/chat/completions com um modelo HINOW.
- 3
Leia a resposta
O texto fica em choices[0].message.content; tokens consumidos ficam em usage.
Prepare seu acesso
Entre na plataforma para gerar uma chave de API. Se ainda não possui acesso, crie sua conta primeiro.
A chave pertence ao servidor
Não exponha a chave em navegadores, aplicativos distribuídos, repositórios ou logs. Faça as chamadas em um backend sob seu controle.
A API usa autenticação Bearer e JSON. Salve a chave em uma variável de ambiente; nunca a escreva diretamente no código.
export HINOW_API_KEY="hi_sua_chave"
export HINOW_BASE_URL="https://api.hinow.ai/v1"| Configuração | Valor |
|---|---|
| Base URL | https://api.hinow.ai/v1 |
| Autenticação | Authorization: Bearer $HINOW_API_KEY |
| Corpo JSON | Content-Type: application/json |
| Modelo inicial | hinow/hinova |
Escolha a linguagem mais próxima da sua aplicação. Todos os exemplos abaixo fazem exatamente a mesma requisição HTTP.
curl --fail-with-body --silent --show-error \
-X POST "https://api.hinow.ai/v1/chat/completions" \
-H "Authorization: Bearer $HINOW_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "hinow/hinova",
"messages": [
{"role": "system", "content": "Responda com objetividade."},
{"role": "user", "content": "Explique o que é uma API em uma frase."}
]
}'import os
import requests
response = requests.post(
"https://api.hinow.ai/v1/chat/completions",
headers={
"Authorization": f"Bearer {os.environ['HINOW_API_KEY']}",
"Content-Type": "application/json",
},
json={
"model": "hinow/hinova",
"messages": [
{"role": "system", "content": "Responda com objetividade."},
{"role": "user", "content": "Explique o que é uma API em uma frase."},
],
},
timeout=60,
)
response.raise_for_status()
print(response.json()["choices"][0]["message"]["content"])const response = await fetch("https://api.hinow.ai/v1/chat/completions", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.HINOW_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "hinow/hinova",
messages: [
{ role: "system", content: "Responda com objetividade." },
{ role: "user", content: "Explique o que é uma API em uma frase." },
],
}),
});
if (!response.ok) throw new Error(await response.text());
const data = await response.json();
console.log(data.choices[0].message.content);<?php
$ch = curl_init("https://api.hinow.ai/v1/chat/completions");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer " . getenv("HINOW_API_KEY"),
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => json_encode([
"model" => "hinow/hinova",
"messages" => [
["role" => "system", "content" => "Responda com objetividade."],
["role" => "user", "content" => "Explique o que é uma API em uma frase."],
],
]),
CURLOPT_TIMEOUT => 60,
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($body === false || $status >= 400) throw new RuntimeException($body ?: curl_error($ch));
$data = json_decode($body, true, flags: JSON_THROW_ON_ERROR);
echo $data["choices"][0]["message"]["content"];{
"id": "chatcmpl_01JEXEMPLO",
"object": "chat.completion",
"created": 1786200000,
"model": "hinow/hinova",
"choices": [{
"index": 0,
"message": {
"role": "assistant",
"content": "Uma API é uma interface que permite que sistemas troquem dados e executem funções de forma padronizada."
},
"finish_reason": "stop"
}],
"usage": {
"prompt_tokens": 31,
"completion_tokens": 24,
"total_tokens": 55
}
}Primeira chamada concluída
Se você recebeu uma resposta com choices, a autenticação, a URL e o modelo estão configurados corretamente.
| Campo | Como usar |
|---|---|
id | Identificador da geração; registre-o ao investigar uma chamada. |
model | Modelo HINOW que produziu a resposta. |
choices[0].message.content | Texto final retornado pelo modelo. |
choices[0].finish_reason | Motivo do encerramento, como stop ou tool_calls. |
usage.prompt_tokens | Tokens enviados na entrada. |
usage.completion_tokens | Tokens gerados na saída. |
usage.total_tokens | Total usado para acompanhar consumo e custo. |
Contrato de Chat Completions
A resposta contém diretamente id, choices e usage. Não procure esses campos dentro de um envelope success/data.
Compare antes de publicar
Avalie capacidade, velocidade e preço com entradas reais do seu negócio.
Sua primeira integração já pode ir para um protótipo. As seções seguintes mostram como evoluí-la; abra apenas os exemplos de resposta que precisar.
Consulte GET https://api.hinow.ai/v1/models para descobrir o catálogo disponível na conta. Use o campo endpoint para filtrar modelos compatíveis com a operação desejada.
curl --fail-with-body --silent --show-error \
"https://api.hinow.ai/v1/models" \
-H "Authorization: Bearer $HINOW_API_KEY" \
| jq '.data[] | select(.id | startswith("hinow/")) | {id, category, endpoint, cost}'{
"object": "list",
"data": [
{"id": "hinow/hinova", "category": "chat", "endpoint": "/v1/chat/completions"},
{"id": "hinow/himax", "category": "chat", "endpoint": "/v1/chat/completions"},
{"id": "hinow/himegia", "category": "image", "endpoint": "/v1/images"}
]
}Chat Completions não mantém estado entre chamadas. Reenvie as mensagens relevantes, em ordem, para dar contexto à próxima resposta.
curl --fail-with-body --silent --show-error \
-X POST "https://api.hinow.ai/v1/chat/completions" \
-H "Authorization: Bearer $HINOW_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "hinow/hinova",
"messages": [
{"role": "user", "content": "Meu plano se chama Horizonte."},
{"role": "assistant", "content": "Entendido."},
{"role": "user", "content": "Qual é o nome do meu plano?"}
]
}'Use streaming em interfaces conversacionais para exibir a resposta enquanto ela é gerada. Cada evento começa com data: e o fluxo termina em data: [DONE].
curl --fail-with-body --silent --show-error -N \
-X POST "https://api.hinow.ai/v1/chat/completions" \
-H "Authorization: Bearer $HINOW_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "hinow/hinova",
"stream": true,
"messages": [{"role": "user", "content": "Conte de um a três."}]
}'data: {"id":"chatcmpl_01JEXEMPLO","choices":[{"index":0,"delta":{"role":"assistant"}}]}
data: {"id":"chatcmpl_01JEXEMPLO","choices":[{"index":0,"delta":{"content":"Um"}}]}
data: {"id":"chatcmpl_01JEXEMPLO","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
data: [DONE]curl --fail-with-body --silent --show-error \
-X POST "https://api.hinow.ai/v1/chat/completions" \
-H "Authorization: Bearer $HINOW_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "hinow/higenesis",
"response_format": {"type": "json_object"},
"messages": [
{"role": "system", "content": "Responda somente com JSON válido."},
{"role": "user", "content": "Retorne status ok e prioridade 1."}
]
}'{
"id": "chatcmpl_01JEXEMPLO",
"object": "chat.completion",
"model": "hinow/higenesis",
"choices": [{
"index": 0,
"message": {"role": "assistant", "content": "{\"status\":\"ok\",\"prioridade\":1}"},
"finish_reason": "stop"
}],
"usage": {"prompt_tokens": 29, "completion_tokens": 12, "total_tokens": 41}
}Ainda é uma string
O JSON gerado fica em choices[0].message.content. Faça o parse e valide o objeto antes de usá-lo no sistema.
O modelo escolhe e preenche a função; sua aplicação valida os argumentos, executa o código e envia o resultado em uma nova chamada. Nunca execute argumentos sem validação.
curl --fail-with-body --silent --show-error \
-X POST "https://api.hinow.ai/v1/chat/completions" \
-H "Authorization: Bearer $HINOW_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "hinow/higenesis",
"tools": [{
"type": "function",
"function": {
"name": "consultar_clima",
"description": "Consulta o clima atual de uma cidade",
"parameters": {
"type": "object",
"properties": {"cidade": {"type": "string"}},
"required": ["cidade"]
}
}
}],
"tool_choice": "auto",
"messages": [{"role": "user", "content": "Qual é o clima em Recife? Use a ferramenta."}]
}'{
"choices": [{
"message": {
"role": "assistant",
"content": null,
"tool_calls": [{
"id": "call_01JEXEMPLO",
"type": "function",
"function": {"name": "consultar_clima", "arguments": "{\"cidade\":\"Recife\"}"}
}]
},
"finish_reason": "tool_calls"
}]
}curl --fail-with-body --silent --show-error \
-X POST "https://api.hinow.ai/v1/chat/completions" \
-H "Authorization: Bearer $HINOW_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "hinow/higenesis",
"messages": [{
"role": "user",
"content": [
{"type": "text", "text": "Descreva esta imagem em uma frase."},
{"type": "image_url", "image_url": {"url": "https://exemplo.com/imagem.jpg"}}
]
}]
}'IMAGE_BASE64="$(base64 < imagem.jpg | tr -d '\n')"
jq -n --arg image "data:image/jpeg;base64,$IMAGE_BASE64" '{
model: "hinow/higenesis",
messages: [{
role: "user",
content: [
{type: "text", text: "Descreva esta imagem em uma frase."},
{type: "image_url", image_url: {url: $image}}
]
}]
}' | curl --fail-with-body --silent --show-error \
-X POST "https://api.hinow.ai/v1/chat/completions" \
-H "Authorization: Bearer $HINOW_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @-{
"id": "chatcmpl_01JEXEMPLO",
"object": "chat.completion",
"model": "hinow/higenesis",
"choices": [{
"message": {"role": "assistant", "content": "A imagem mostra um produto sobre um fundo claro."},
"finish_reason": "stop"
}],
"usage": {"prompt_tokens": 215, "completion_tokens": 18, "total_tokens": 233}
}curl --fail-with-body --silent --show-error \
-X POST "https://api.hinow.ai/v1/images" \
-H "Authorization: Bearer $HINOW_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "hinow/himegia",
"prompt": "Still de produto minimalista, fundo azul e luz lateral suave",
"parameters": {"aspect_ratio": "1:1", "output_format": "png"}
}'curl --fail-with-body --silent --show-error \
-X POST "https://api.hinow.ai/v1/images" \
-H "Authorization: Bearer $HINOW_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "hinow/himegia",
"prompt": "Preserve o produto e altere somente o fundo para verde-claro.",
"images": ["https://exemplo.com/produto.png"],
"parameters": {"aspect_ratio": "1:1", "output_format": "png"}
}'{
"success": true,
"data": {
"urls": ["https://cdn.exemplo.com/imagem-gerada.png"],
"thumbnail_url": "https://cdn.exemplo.com/imagem-gerada-thumb.png",
"model": "hinow/himegia",
"category": "image",
"operation": "generate",
"cost": 0.04,
"metadata": {"aspect_ratio": "1:1", "output_format": "png"}
},
"request_id": "req_01JEXEMPLO",
"processed_at": "2026-08-09T15:00:00.000Z"
}Mídia usa outro envelope
Em geração de imagem, leia o resultado em data.urls. O request_id ajuda a rastrear a operação e data.cost informa o custo retornado.
O upload usa multipart e devolve um id. Use esse identificador somente em recursos que documentarem suporte a file_id; enviar um arquivo não o adiciona automaticamente a uma conversa.
curl --fail-with-body --silent --show-error \
-X POST "https://api.hinow.ai/v1/files" \
-H "Authorization: Bearer $HINOW_API_KEY" \
-F "purpose=assistants" \
-F "file=@documento.pdf"curl --fail-with-body --silent --show-error \
"https://api.hinow.ai/v1/files" \
-H "Authorization: Bearer $HINOW_API_KEY"FILE_ID="file_id_retornado"
curl --fail-with-body --silent --show-error \
"https://api.hinow.ai/v1/files/$FILE_ID" \
-H "Authorization: Bearer $HINOW_API_KEY"FILE_ID="file_id_retornado"
curl --fail-with-body --silent --show-error \
"https://api.hinow.ai/v1/files/$FILE_ID/content" \
-H "Authorization: Bearer $HINOW_API_KEY" \
--output arquivo-baixadoFILE_ID="file_id_retornado"
curl --fail-with-body --silent --show-error \
-X DELETE "https://api.hinow.ai/v1/files/$FILE_ID" \
-H "Authorization: Bearer $HINOW_API_KEY"{
"id": "file_01JEXEMPLO",
"object": "file",
"bytes": 48213,
"created_at": 1786200000,
"filename": "documento.pdf",
"purpose": "assistants",
"status": "processed"
}{
"id": "file_01JEXEMPLO",
"object": "file",
"deleted": true
}A disponibilidade depende do catálogo da conta. Selecione um modelo cujo endpoint seja /v1/embeddings e use o identificador retornado.
EMBED_MODEL="$(curl --fail-with-body --silent --show-error \
"https://api.hinow.ai/v1/models" \
-H "Authorization: Bearer $HINOW_API_KEY" \
| jq -r '.data[] | select(.endpoint == "/v1/embeddings") | .id' \
| head -n 1)"
test -n "$EMBED_MODEL" || { echo "Embeddings indisponíveis" >&2; exit 1; }
jq -n --arg model "$EMBED_MODEL" '{
model: $model,
input: "Texto que será convertido em vetor."
}' | curl --fail-with-body --silent --show-error \
-X POST "https://api.hinow.ai/v1/embeddings" \
-H "Authorization: Bearer $HINOW_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @-{
"object": "list",
"data": [{"object": "embedding", "index": 0, "embedding": [0.0121, -0.0084, 0.0317, "..."]}],
"model": "modelo-retornado-pelo-catalogo",
"usage": {"prompt_tokens": 8, "total_tokens": 8}
}Essas modalidades podem variar por conta. Consulte https://api.hinow.ai/v1/models e habilite o recurso somente quando o catálogo publicar um modelo para o endpoint correspondente:
POST https://api.hinow.ai/v1/audio/speech— texto para voz.POST https://api.hinow.ai/v1/audio/transcriptions— transcrição, quando disponível.POST https://api.hinow.ai/v1/videos— geração ou transformação de vídeo.
Serviços de mídia podem ser assíncronos ou ficar temporariamente indisponíveis. Preserve o request_id, trate novas tentativas com cuidado e não prometa a conclusão antes da resposta final.
TTS_MODEL="$(curl --fail-with-body --silent --show-error \
"https://api.hinow.ai/v1/models" -H "Authorization: Bearer $HINOW_API_KEY" \
| jq -r '.data[] | select(.endpoint == "/v1/audio/speech") | .id' | head -n 1)"
test -n "$TTS_MODEL" || { echo "Texto para voz indisponível" >&2; exit 1; }
jq -n --arg model "$TTS_MODEL" '{
model: $model,
prompt: "Olá! Este é um teste curto da API HINOW."
}' | curl --fail-with-body --silent --show-error \
-X POST "https://api.hinow.ai/v1/audio/speech" \
-H "Authorization: Bearer $HINOW_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @-STT_MODEL="$(curl --fail-with-body --silent --show-error \
"https://api.hinow.ai/v1/models" -H "Authorization: Bearer $HINOW_API_KEY" \
| jq -r '.data[] | select(.endpoint == "/v1/audio/transcriptions") | .id' | head -n 1)"
test -n "$STT_MODEL" || { echo "Transcrição indisponível" >&2; exit 1; }
jq -n --arg model "$STT_MODEL" --arg audio "https://exemplo.com/audio.mp3" '{
model: $model,
audio_url: $audio
}' | curl --fail-with-body --silent --show-error \
-X POST "https://api.hinow.ai/v1/audio/transcriptions" \
-H "Authorization: Bearer $HINOW_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @-VIDEO_MODEL="$(curl --fail-with-body --silent --show-error \
"https://api.hinow.ai/v1/models" -H "Authorization: Bearer $HINOW_API_KEY" \
| jq -r '.data[] | select(.endpoint == "/v1/videos") | .id' | head -n 1)"
test -n "$VIDEO_MODEL" || { echo "Vídeo indisponível" >&2; exit 1; }
jq -n --arg model "$VIDEO_MODEL" '{
model: $model,
prompt: "Um círculo azul se move lentamente sobre fundo branco.",
parameters: {duration: 3, aspect_ratio: "16:9"}
}' | curl --fail-with-body --silent --show-error \
-X POST "https://api.hinow.ai/v1/videos" \
-H "Authorization: Bearer $HINOW_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @-{
"success": true,
"data": {
"urls": ["https://cdn.exemplo.com/resultado.mp3"],
"model": "modelo-retornado-pelo-catalogo",
"category": "audio",
"operation": "text-to-speech",
"cost": 0.01
},
"request_id": "req_01JEXEMPLO",
"processed_at": "2026-08-09T15:00:00.000Z"
}O catálogo é a fonte de disponibilidade
Não fixe no código identificadores que não estejam publicados. Se nenhum modelo apontar para o endpoint desejado, o recurso não está disponível para a conta naquele momento.
Sempre verifique o status HTTP antes de acessar choices ou data. Em produção, registre o código do erro e o request_id, sem registrar a chave nem conteúdo sensível.
{
"error": {
"message": "O modelo solicitado não foi encontrado.",
"type": "invalid_request_error",
"code": "model_not_found"
},
"request_id": "req_01JEXEMPLO"
}| Status | Ação recomendada |
|---|---|
400 | Corrija o corpo, o parâmetro ou o formato enviado. |
401 | Confira a chave e o cabeçalho Authorization: Bearer. |
404 | Confira a URL completa e o identificador do modelo. |
429 | Aguarde e repita com backoff exponencial e jitter. |
5xx | Preserve o request_id e repita somente operações seguras ou idempotentes. |
Precisa criar ou substituir uma chave?
Crie, revise e gerencie suas chaves de API diretamente na plataforma HINOW.
- Mantenha a chave em um cofre de segredos e faça rotação periódica.
- Defina timeout de conexão e duração total.
- Limite novas tentativas para evitar duplicidade e custo inesperado.
- Valide argumentos de ferramentas e JSON retornado pelo modelo.
- Registre
request_id, modelo, latência, status e uso; nunca registre a chave. - Teste qualidade, custo e tempo de resposta com casos reais antes de liberar tráfego.
- Consulte o catálogo para recursos cuja disponibilidade varia por conta.
Aprofunde a integração
Use a referência técnica para conferir parâmetros e escolha uma biblioteca para o seu ambiente.

