Leitura de imagem
Envie uma imagem e receba texto: documentos, prints, gráficos e fotos. A chamada, o custo por imagem, qual modelo usar e os erros.
Atualizado em 10 de ago. de 2026
O hinow/hivision recebe uma imagem e responde sobre ela em texto: o que está escrito, o que o gráfico mostra, o que aparece na foto. É o caminho para tudo que entra no seu produto como imagem e precisa sair como dado.
Ele atende no mesmo endereço dos modelos de linguagem — POST https://api.hinow.ai/v1/chat/completions — com a mesma chave. Muda só o model e o formato do content da mensagem. O preço é por token: US$ 1,00 por milhão na entrada e US$ 3,00 por milhão na saída.
O modelo não edita nem cria imagens — para isso existe Geração de imagem. Aqui a imagem é entrada:
- Documentos digitalizados — notas, contratos, formulários e comprovantes que chegam fotografados ou escaneados.
- Capturas de tela — o chamado em que o usuário manda o print em vez de descrever o erro.
- Gráficos e painéis — ler o que o gráfico mostra e devolver em texto ou em campos.
- Fotografias — conferência de produto, estado de um equipamento, foto enviada pelo cliente.
- Triagem visual — classificar imagens em categorias antes de decidir o que fazer com cada uma.
A diferença para uma chamada de texto é uma só: o content da mensagem deixa de ser uma string e passa a ser uma lista de partes. Uma parte text com o pedido, uma parte image_url com a imagem.
curl https://api.hinow.ai/v1/chat/completions \
-H "Authorization: Bearer $HINOW_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "hinow/hivision",
"messages": [{
"role": "user",
"content": [
{"type": "text", "text": "O que este gráfico mostra? Responda em português, em uma frase."},
{"type": "image_url", "image_url": {"url": "https://exemplo.com/grafico.png"}}
]
}]
}'import os, requests
resposta = requests.post(
"https://api.hinow.ai/v1/chat/completions",
headers={"Authorization": f"Bearer {os.environ['HINOW_API_KEY']}"},
json={
"model": "hinow/hivision",
"messages": [{
"role": "user",
"content": [
{"type": "text", "text": "O que este gráfico mostra? Responda em português, em uma frase."},
{"type": "image_url", "image_url": {"url": "https://exemplo.com/grafico.png"}},
],
}],
},
).json()
print(resposta["choices"][0]["message"]["content"])
print(resposta["usage"]) # {'prompt_tokens': 389, ...}const resposta = 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/hivision",
messages: [{
role: "user",
content: [
{ type: "text", text: "O que este gráfico mostra? Responda em português, em uma frase." },
{ type: "image_url", image_url: { url: "https://exemplo.com/grafico.png" } },
],
}],
}),
}).then((r) => r.json());
console.log(resposta.choices[0].message.content);A resposta tem o mesmo envelope de uma chamada de texto: choices[0].message.content com o texto e usage com o consumo. Não existe campo separado para a imagem — ela já entrou na conta de prompt_tokens.
O campo url aceita duas coisas, e as duas funcionam:
- Endereço público —
https://exemplo.com/nota.png. A API busca a imagem, então ela precisa estar acessível pela internet. Um endereço emlocalhostou atrás de login não serve. - A imagem embutida — uma URL
data:com o arquivo em base64. Não depende de a imagem estar publicada em lugar nenhum, e é o caminho para arquivo que o usuário acabou de enviar.
import base64
with open("nota.png", "rb") as f:
embutida = "data:image/png;base64," + base64.b64encode(f.read()).decode()
parte = {"type": "image_url", "image_url": {"url": embutida}}URL que a API não alcança devolve 502
O erro não diz que o endereço é inválido — diz que a chamada falhou. Se um host público específico falhar enquanto outros funcionam, o problema é alcançabilidade daquele endereço, não falta de suporte a URL. Na dúvida, mande a imagem embutida em base64.
| Formato | Resultado |
|---|---|
| PNG | Funciona |
| JPEG | Funciona |
| WebP | Funciona |
O tipo declarado não é o que decide
Um PNG enviado como data:image/jpeg;base64,... foi lido normalmente — o conteúdo do arquivo é que vale. Ainda assim, declare o tipo certo: é o que mantém o seu próprio código honesto quando o formato mudar.
A imagem vira tokens e entra em prompt_tokens. O número não é proporcional ao tamanho do arquivo — a mesma figura enviada com 512px (19 KB) e com 1024px (55 KB) consumiu 389 tokens de prompt nas duas vezes.
A consequência prática é o contrário do que a intuição diz: encolher a imagem não barateia a chamada, e ainda pode custar a legibilidade de um texto pequeno. Envie a imagem em uma resolução em que o texto seja legível para uma pessoa.
A conta na prática
A 389 tokens de entrada e US$ 1,00 por milhão, mil leituras de imagem custam cerca de US$ 0,39 de entrada, mais a saída gerada. É a ordem de grandeza que importa ao dimensionar um processamento em lote.
Os modelos de linguagem da HINOW também leem imagem. A tabela abaixo é a mesma pergunta com a mesma imagem de 1024px, uma chamada por modelo:
| Modelo | Tokens de entrada | Tempo | Entrada / 1M | Quando escolher |
|---|---|---|---|---|
hinow/hivision | 389 | 6,0 s | US$ 1,00 | A imagem é o centro da tarefa |
hinow/himax | 578 | 24,1 s | US$ 2,26 | A imagem entra em um raciocínio complexo |
hinow/higenesis | 618 | 27,0 s | US$ 0,22 | Volume alto e pergunta objetiva |
hinow/hinova | 623 | 29,1 s | US$ 0,69 | A imagem é um detalhe em uma conversa |
Duas leituras dessa tabela:
- Para tarefa visual, o HiVision é o mais rápido e o que menos tokeniza a imagem — foi cerca de quatro vezes mais rápido que os modelos de uso geral na mesma pergunta.
- O mais barato por token não é o mais barato na tarefa. O HiGenesis tem a menor tarifa, mas gastou 618 tokens onde o HiVision gastou 389. Compare o custo da tarefa inteira, não o preço da tabela.
Quando a imagem é só uma parte de uma conversa que já está em outro modelo, continuar nele costuma valer mais do que trocar de modelo no meio do fluxo.
É o uso mais comum em produção: a imagem entra, um registro sai. Peça o formato de forma explícita e valide antes de gravar.
curl https://api.hinow.ai/v1/chat/completions \
-H "Authorization: Bearer $HINOW_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "hinow/hivision",
"messages": [{
"role": "user",
"content": [
{"type": "text", "text": "Extraia desta nota: numero, cnpj, total e vencimento. Responda só JSON, sem comentário: {\"numero\":\"\",\"cnpj\":\"\",\"total\":\"\",\"vencimento\":\"\"}"},
{"type": "image_url", "image_url": {"url": "data:image/png;base64,iVBORw0KGgo..."}}
]
}]
}'Em uma nota fiscal de teste, com os quatro campos, o hinow/hivision devolveu em 3,1 s:
{"numero": "2026-00814", "cnpj": "12.345.678/0001-90", "total": "R$ 5.190,50", "vencimento": "25/08/2026"}O hinow/higenesis acertou os mesmos quatro campos em 6,7 s, mas devolveu o total como "5.190,50", sem o R$. É exatamente o tipo de diferença que só aparece testando com os seus documentos: normalize no seu código, não confie no formato do texto que voltou.
Peça o idioma e peça só o JSON
Sem instrução explícita, a resposta pode vir em inglês e começar com uma apresentação do modelo antes do conteúdo. Ao pedir "responda só JSON, sem comentário", a saída volta limpa e pronta para JSON.parse. Ainda assim, trate o resultado como entrada não confiável: confira campos, tipos e faixas.
Basta acrescentar outra parte image_url na mesma lista. Serve para comparar duas versões de um documento, conferir antes e depois, ou pedir uma conclusão sobre um conjunto. Com duas imagens de 1024px, o prompt ficou em 660 tokens — cada imagem soma à conta.
"content": [
{"type": "text", "text": "Estes dois documentos são da mesma empresa? Responda sim ou não e por quê."},
{"type": "image_url", "image_url": {"url": "https://exemplo.com/nota-a.png"}},
{"type": "image_url", "image_url": {"url": "https://exemplo.com/nota-b.png"}}
]| Situação | O que acontece |
|---|---|
| URL que a API não alcança | 502 — a chamada falha como erro de execução |
| Chamada sem imagem, só texto | Responde normalmente, mas o usage volta zerado |
| Modelo de embeddings neste endpoint | 400 — o modelo não atende Chat Completions |
| Modelo inexistente | 404 |
Confirme o contrato da sua conta
Disponibilidade, preços e modalidades evoluem. GET https://api.hinow.ai/v1/models devolve o catálogo vigente — mas trate o campo category como informativo: modelos listados só como text_to_text aceitaram imagem nos testes.