Ir para o conteúdo

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

    Crie uma chave

    Gere uma chave em platform.hinow.ai e guarde-a como segredo no servidor.

  2. 2

    Envie uma mensagem

    Faça um POST para https://api.hinow.ai/v1/chat/completions com um modelo HINOW.

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

1. Prepare o ambiente

A API usa autenticação Bearer e JSON. Salve a chave em uma variável de ambiente; nunca a escreva diretamente no código.

terminalbash
export HINOW_API_KEY="hi_sua_chave"
export HINOW_BASE_URL="https://api.hinow.ai/v1"
ConfiguraçãoValor
Base URLhttps://api.hinow.ai/v1
AutenticaçãoAuthorization: Bearer $HINOW_API_KEY
Corpo JSONContent-Type: application/json
Modelo inicialhinow/hinova

2. Faça a primeira chamada

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

3. Entenda a resposta

CampoComo usar
idIdentificador da geração; registre-o ao investigar uma chamada.
modelModelo HINOW que produziu a resposta.
choices[0].message.contentTexto final retornado pelo modelo.
choices[0].finish_reasonMotivo do encerramento, como stop ou tool_calls.
usage.prompt_tokensTokens enviados na entrada.
usage.completion_tokensTokens gerados na saída.
usage.total_tokensTotal 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.

4. Escolha o modelo certo

Compare antes de publicar

Avalie capacidade, velocidade e preço com entradas reais do seu negócio.

Próximos recursos

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.

Listar modelos disponíveis

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

Manter uma conversa

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

Receber a resposta em streaming

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]

Receber JSON estruturado

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.

Chamar uma função

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

Analisar imagens

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": "A imagem mostra um produto sobre um fundo claro."},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 215, "completion_tokens": 18, "total_tokens": 233}
}

Criar ou editar uma imagem

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

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.

Enviar e administrar arquivos

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

Criar embeddings

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

Áudio, transcrição e vídeo

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

Tratar erros corretamente

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"
}
StatusAção recomendada
400Corrija o corpo, o parâmetro ou o formato enviado.
401Confira a chave e o cabeçalho Authorization: Bearer.
404Confira a URL completa e o identificador do modelo.
429Aguarde e repita com backoff exponencial e jitter.
5xxPreserve 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.

Checklist para produção

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

Esta página foi útil?