Quickstart
Make your first call to the HINOW API and move on to streaming, JSON, tools, images, files, embeddings and media.
Updated on Aug 09, 2026
- 1
Create a key
Generate a key at platform.hinow.ai and store it as a secret on the server.
- 2
Send a message
Make a POST to https://api.hinow.ai/v1/chat/completions with a HINOW model.
- 3
Read the response
The text is in choices[0].message.content; the tokens consumed are in usage.
Set up your access
Sign in to the platform to generate an API key. If you do not have access yet, create your account first.
The key belongs on the server
Do not expose the key in browsers, distributed applications, repositories or logs. Make the calls from a backend under your control.
The API uses Bearer authentication and JSON. Save the key in an environment variable; never write it directly in the code.
export HINOW_API_KEY="hi_sua_chave"
export HINOW_BASE_URL="https://api.hinow.ai/v1"| Setting | Value |
|---|---|
| Base URL | https://api.hinow.ai/v1 |
| Authentication | Authorization: Bearer $HINOW_API_KEY |
| JSON body | Content-Type: application/json |
| Starting model | hinow/hinova |
Choose the language closest to your application. Every example below makes exactly the same HTTP request.
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": "An API is an interface that lets systems exchange data and run functions in a standardized way."
},
"finish_reason": "stop"
}],
"usage": {
"prompt_tokens": 31,
"completion_tokens": 24,
"total_tokens": 55
}
}First call complete
If you received a response with choices, then authentication, the URL and the model are correctly configured.
| Field | How to use it |
|---|---|
id | Identifier of the generation; log it when investigating a call. |
model | HINOW model that produced the response. |
choices[0].message.content | Final text returned by the model. |
choices[0].finish_reason | Reason for stopping, such as stop or tool_calls. |
usage.prompt_tokens | Tokens sent in the input. |
usage.completion_tokens | Tokens generated in the output. |
usage.total_tokens | Total used to track consumption and cost. |
Chat Completions contract
The response contains id, choices and usage directly. Do not look for these fields inside a success/data envelope.
Compare before shipping
Evaluate capability, speed and price with real inputs from your business.
Your first integration is already enough for a prototype. The sections below show how to evolve it; open only the response examples you need.
Query GET https://api.hinow.ai/v1/models to discover the catalog available on the account. Use the endpoint field to filter models compatible with the operation you want.
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 does not keep state between calls. Resend the relevant messages, in order, to give context to the next response.
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 in conversational interfaces to display the response while it is generated. Each event starts with data: and the stream ends with 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":"An"}}]}
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}
}It is still a string
The generated JSON is in choices[0].message.content. Parse and validate the object before using it in your system.
The model chooses and fills in the function; your application validates the arguments, runs the code and sends the result in a new call. Never run arguments without validation.
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": "The image shows a product against a light background."},
"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"
}Media uses a different envelope
In image generation, read the result from data.urls. The request_id helps trace the operation and data.cost reports the cost returned.
The upload uses multipart and returns an id. Use that identifier only in features that document support for file_id; uploading a file does not automatically add it to a conversation.
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
}Availability depends on the account catalog. Select a model whose endpoint is /v1/embeddings and use the identifier returned.
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}
}These modalities can vary per account. Check https://api.hinow.ai/v1/models and enable the capability only when the catalog publishes a model for the corresponding endpoint:
POST https://api.hinow.ai/v1/audio/speech— text to speech.POST https://api.hinow.ai/v1/audio/transcriptions— transcription, when available.POST https://api.hinow.ai/v1/videos— video generation or transformation.
Media services can be asynchronous or temporarily unavailable. Preserve the request_id, handle retries carefully and do not promise completion before the final response.
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"
}The catalog is the source of availability
Do not hardcode identifiers that are not published. If no model points to the endpoint you want, the capability is not available to the account at that moment.
Always check the HTTP status before accessing choices or data. In production, log the error code and the request_id, without logging the key or sensitive content.
{
"error": {
"message": "The requested model was not found.",
"type": "invalid_request_error",
"code": "model_not_found"
},
"request_id": "req_01JEXEMPLO"
}| Status | Recommended action |
|---|---|
400 | Fix the body, the parameter or the format you sent. |
401 | Check the key and the Authorization: Bearer header. |
404 | Check the full URL and the model identifier. |
429 | Wait and retry with exponential backoff and jitter. |
5xx | Preserve the request_id and retry only safe or idempotent operations. |
Need to create or replace a key?
Create, review and manage your API keys directly on the HINOW platform.
- Keep the key in a secrets vault and rotate it periodically.
- Set a connection timeout and a total duration.
- Limit retries to avoid duplication and unexpected cost.
- Validate tool arguments and the JSON returned by the model.
- Log
request_id, model, latency, status and usage; never log the key. - Test quality, cost and latency with real cases before releasing traffic.
- Check the catalog for capabilities whose availability varies per account.
Go deeper into the integration
Use the technical reference to check parameters and choose a library for your environment.

