Skip to content

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. 1

    Create a key

    Generate a key at platform.hinow.ai and store it as a secret on the server.

  2. 2

    Send a message

    Make a POST to https://api.hinow.ai/v1/chat/completions with a HINOW model.

  3. 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.

1. Prepare the environment

The API uses Bearer authentication and JSON. Save the key in an environment variable; never write it directly in the code.

terminalbash
export HINOW_API_KEY="hi_sua_chave"
export HINOW_BASE_URL="https://api.hinow.ai/v1"
SettingValue
Base URLhttps://api.hinow.ai/v1
AuthenticationAuthorization: Bearer $HINOW_API_KEY
JSON bodyContent-Type: application/json
Starting modelhinow/hinova

2. Make the first call

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."}
    ]
  }'
{
  "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.

3. Understand the response

FieldHow to use it
idIdentifier of the generation; log it when investigating a call.
modelHINOW model that produced the response.
choices[0].message.contentFinal text returned by the model.
choices[0].finish_reasonReason for stopping, such as stop or tool_calls.
usage.prompt_tokensTokens sent in the input.
usage.completion_tokensTokens generated in the output.
usage.total_tokensTotal 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.

4. Choose the right model

Compare before shipping

Evaluate capability, speed and price with real inputs from your business.

Next capabilities

Your first integration is already enough for a prototype. The sections below show how to evolve it; open only the response examples you need.

List available models

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"}
  ]
}

Keep a conversation going

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?"}
    ]
  }'

Receive the response in streaming

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]

Receive structured JSON

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.

Call a function

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"
  }]
}

Analyze images

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"}}
      ]
    }]
  }'
{
  "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}
}

Create or edit an image

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"}
  }'
{
  "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.

Upload and manage files

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"
{
  "id": "file_01JEXEMPLO",
  "object": "file",
  "bytes": 48213,
  "created_at": 1786200000,
  "filename": "documento.pdf",
  "purpose": "assistants",
  "status": "processed"
}
{
  "id": "file_01JEXEMPLO",
  "object": "file",
  "deleted": true
}

Create embeddings

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}
}

Audio, transcription and video

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 @-
{
  "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.

Handle errors correctly

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"
}
StatusRecommended action
400Fix the body, the parameter or the format you sent.
401Check the key and the Authorization: Bearer header.
404Check the full URL and the model identifier.
429Wait and retry with exponential backoff and jitter.
5xxPreserve 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.

Production checklist

  • 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.

Was this page helpful?