Geração de texto

A primeira chamada, os papéis de mensagem e o caminho do teste à produção.

Atualizado em 09 de ago. de 2026

Os modelos geram texto a partir de mensagens: prosa, Markdown, JSON, código. A chamada é sempre a mesma — POST https://api.hinow.ai/v1/chat/completions com a lista de mensagens — e é sem estado: o modelo vê exatamente o que você mandou, nada além.

A primeira chamada

curl 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": "Explique em uma frase o que é streaming de tokens."}
    ]
  }'

from openai import OpenAI
import os

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

resposta = client.chat.completions.create(
    model="hinow/hinova",
    messages=[
        {"role": "user", "content": "Explique em uma frase o que é streaming de tokens."},
    ],
)

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

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.hinow.ai/v1',
  apiKey: process.env.HINOW_API_KEY,
});

const resposta = await client.chat.completions.create({
  model: 'hinow/hinova',
  messages: [
    { role: 'user', content: 'Explique em uma frase o que é streaming de tokens.' },
  ],
});

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

A resposta desta chamada, como veio da API:

{
  "id": "chatcmpl-R2dSu3p8...",
  "object": "chat.completion",
  "created": 1786238029,
  "model": "hinow/hinova",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Streaming de tokens é a técnica de transmitir a resposta de uma inteligência artificial palavra por palavra (ou token por token) em tempo real, permitindo que o usuário veja o texto sendo gerado instantaneamente, em vez de esperar que a resposta completa seja concluída antes de exibir qualquer conteúdo."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 132, "completion_tokens": 60, "total_tokens": 192 }
}

Três campos importam no dia a dia:

choices[0].message.content — o texto gerado.
finish_reason — por que a geração parou: stop (terminou sozinho), length (bateu no max_tokens) ou tool_calls (o modelo pediu uma função).
usage — a contagem de tokens da entrada e da saída. É o que multiplica o preço; registre-a desde o primeiro dia.

Papéis de mensagem

Cada mensagem tem um papel específico:

system — instruções persistentes da aplicação, como objetivo, tom, formato e limites.
user — o pedido de quem usa.
assistant — as respostas anteriores do modelo. É assim que o histórico entra numa API sem estado.

Pense no system como a definição de uma função e no user como os argumentos: um fixa o comportamento, o outro varia a cada chamada.

{
  "model": "hinow/hinova",
  "messages": [
    {
      "role": "system",
      "content": "Você é o assistente de suporte do HiNow. Comece pela resposta direta em uma frase. Máximo de 60 palavras."
    },
    { "role": "user", "content": "por que minha chamada volta 429?" }
  ]
}

A resposta a essa chamada: "O erro 429 indica que você excedeu o limite de requisições permitidas. Aguarde um momento ou ajuste a frequência das chamadas para respeitar a cota da API." — 27 palavras, começando pela resposta direta. As duas instruções do system foram seguidas sem reforço no user.

Instruções orientam; seu código valida

Instruções de sistema aumentam muito a chance de conformidade, mas não são garantia. Toda regra que não pode ser quebrada — formato, conteúdo, limite — precisa ser validada no código, depois da resposta. Para formato, use modo JSON ou chamadas de função.

Conversas com histórico

A API não guarda a conversa: cada chamada leva o histórico inteiro, com as falas do modelo no papel assistant. É o que permite editar o passado — corrigir uma resposta, resumir turnos antigos, remover o que não interessa mais:

{
  "model": "hinow/hinova",
  "messages": [
    { "role": "system", "content": "Você é o assistente de suporte do HiNow." },
    { "role": "user", "content": "por que minha chamada volta 429?" },
    { "role": "assistant", "content": "O erro 429 indica que você excedeu o limite de requisições. Aguarde o tempo do cabeçalho Retry-After." },
    { "role": "user", "content": "e como eu descubro qual é o meu limite?" }
  ]
}

O histórico é reenviado — e contabilizado como entrada — a cada chamada. Em sessões longas, resuma turnos antigos e mantenha as instruções, decisões e fatos que ainda podem alterar a resposta. Consulte o limite vigente do modelo antes de enviar documentos extensos.

Controle da saída

temperature

Controla quanto a amostragem pode variar. Valores menores são úteis em classificação, extração e código; valores maiores permitem respostas mais diversas. Mesmo com temperature: 0, a saída não é garantidamente idêntica entre chamadas. Valide o comportamento com avaliações.

Tamanho da resposta

Dois mecanismos, com papéis diferentes:

O limite pedido no prompt ("no máximo 60 palavras", "exatamente 3 marcadores") orienta o estilo e a extensão desejada. Valide a quantidade no código quando ela for obrigatória.
max_tokens corta a geração no limite, no meio da frase se for preciso, e marca finish_reason: "length". É rede de segurança contra gasto descontrolado — não controle de tamanho. Cheque o finish_reason sempre: uma resposta cortada parece completa a olho nu.

Streaming

Com stream: true, a resposta chega por server-sent events, um pedaço por vez, conforme o modelo gera. Cada evento é uma linha data: com um chat.completion.chunk; o texto vem em delta.content e é concatenado do seu lado:

data: {"object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":""}}]}
data: {"object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"ol"}}]}
data: {"object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"á, mundo"}}]}
data: {"object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":""},"finish_reason":"stop"}],"usage":{"prompt_tokens":128,"completion_tokens":5,"total_tokens":133}}
data: [DONE]

Duas regras práticas:

O usage vem só no último evento, junto do finish_reason. Quem fecha a conexão ao ver texto suficiente perde a contagem de tokens.
O fluxo termina com a linha data: [DONE] — é ela que encerra, não a ausência de dados.

Use streaming em experiências interativas para reduzir a latência percebida. Em tarefas de backend que precisam do resultado completo antes de continuar, uma resposta sem streaming costuma simplificar o processamento e o tratamento de erros.

Leitura de imagem

Use um modelo com modalidade image_to_text, como hinow/higenesis, para combinar instruções de texto com uma imagem. Confira category em GET https://api.hinow.ai/v1/models antes de habilitar o recurso na aplicação:

{
  "model": "hinow/higenesis",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "O que este gráfico mostra?" },
        { "type": "image_url", "image_url": { "url": "https://exemplo.com/grafico.png" } }
      ]
    }
  ]
}

O url aceita um endereço acessível pela API ou uma URL data: com a imagem em base64. Para fluxos predominantemente visuais, compare o HiGenesis com o modelo especializado hinow/hivision.

Do teste à produção

A saída é não determinística: a mesma entrada produz respostas diferentes. Isso muda o modo de trabalhar:

Monte um conjunto de avaliação com casos reais e resposta esperada. É ele que diz se uma mudança de prompt melhorou ou só mudou.
Nos testes automatizados, verifique propriedade, não igualdade — é JSON? tem os campos? está no limite de tamanho? — porque o texto exato varia.
Versione o prompt no código, junto de quem o usa: prompt é código, e revisão, diff e rollback valem para ele.
Registre o usage de cada chamada. É a sua conta de custo real — e o primeiro lugar onde um prompt inchado aparece.

Próximos passos

JSON e chamadas de funçãoReceba JSON válido ou conecte funções da sua aplicação.Abrir Geração de códigoEscrever, revisar e corrigir código com os modelos.Abrir Como escrever promptsCinco ajustes de redação que mudam o resultado.Abrir

Esta página foi útil?