Image input
Send an image and get text back: documents, screenshots, charts, and photos. The call, the cost per image, which model to use, and the errors.
Updated on Aug 10, 2026
hinow/hivision takes an image and answers about it in text: what is written, what the chart shows, what appears in the photo. It is the path for everything that enters your product as an image and has to come out as data.
It is served at the same address as the language models — POST https://api.hinow.ai/v1/chat/completions — with the same key. Only the model and the format of the message content change. Pricing is per token: US$ 1.00 per million on input and US$ 3.00 per million on output.
The model does not edit or create images — that is Image generation. Here the image is input:
- Scanned documents — invoices, contracts, forms, and receipts that arrive photographed or scanned.
- Screenshots — the ticket where the user sends a screenshot instead of describing the error.
- Charts and dashboards — read what the chart shows and return it as text or as fields.
- Photographs — product checks, equipment condition, a photo sent by the customer.
- Visual triage — classify images into categories before deciding what to do with each one.
There is a single difference from a text call: the message content stops being a string and becomes a list of parts. One text part with the request, one image_url part with the image.
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);The response has the same envelope as a text call: choices[0].message.content with the text and usage with the consumption. There is no separate field for the image — it is already counted in prompt_tokens.
The url field accepts two things, and both work:
- A public address —
https://example.com/invoice.png. The API fetches the image, so it has to be reachable over the internet. An address onlocalhostor behind a login will not do. - The image inline — a
data:URL with the file in base64. It does not depend on the image being published anywhere, and it is the path for a file the user has just uploaded.
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}}A URL the API cannot reach returns 502
The error does not say the address is invalid — it says the call failed. If one specific public host fails while others work, the problem is reachability of that address, not a lack of URL support. When in doubt, send the image inline in base64.
| Format | Result |
|---|---|
| PNG | Works |
| JPEG | Works |
| WebP | Works |
The declared type is not what decides
A PNG sent as data:image/jpeg;base64,... was read normally — the content of the file is what counts. Even so, declare the right type: it is what keeps your own code honest when the format changes.
The image becomes tokens and goes into prompt_tokens. The number is not proportional to the file size — the same figure sent at 512px (19 KB) and at 1024px (55 KB) consumed 389 prompt tokens both times.
The practical consequence is the opposite of what intuition says: shrinking the image does not make the call cheaper, and it can cost you the legibility of small text. Send the image at a resolution where a person could read the text.
The math in practice
At 389 input tokens and US$ 1.00 per million, a thousand image reads cost around US$ 0.39 of input, plus the output generated. That is the order of magnitude that matters when sizing a batch job.
The HINOW language models read images too. The table below is the same question with the same 1024px image, one call per model:
| Model | Input tokens | Time | Input / 1M | When to choose it |
|---|---|---|---|---|
hinow/hivision | 389 | 6.0 s | US$ 1.00 | The image is the centre of the task |
hinow/himax | 578 | 24.1 s | US$ 2.26 | The image feeds complex reasoning |
hinow/higenesis | 618 | 27.0 s | US$ 0.22 | High volume and a well-defined question |
hinow/hinova | 623 | 29.1 s | US$ 0.69 | The image is a detail in a conversation |
Two readings of that table:
- For a visual task, HiVision is the fastest and the one that tokenizes the image least — it was about four times faster than the general-purpose models on the same question.
- The cheapest per token is not the cheapest for the task. HiGenesis has the lowest rate, but it spent 618 tokens where HiVision spent 389. Compare the cost of the whole task, not the price on the table.
When the image is only one part of a conversation already running on another model, staying on it is usually worth more than switching models mid-flow.
This is the most common use in production: an image goes in, a record comes out. Ask for the format explicitly and validate before storing.
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..."}}
]
}]
}'On a test invoice, with the four fields, hinow/hivision answered in 3.1 s:
{"numero": "2026-00814", "cnpj": "12.345.678/0001-90", "total": "R$ 5.190,50", "vencimento": "25/08/2026"}hinow/higenesis got the same four fields right in 6.7 s, but returned the total as "5.190,50", without the R$. That is exactly the kind of difference that only shows up when you test with your own documents: normalize in your code, do not trust the format of the text that came back.
Ask for the language and ask for JSON only
Without an explicit instruction, the answer may come back in English and open with the model introducing itself before the content. Asking it to "answer with JSON only, no commentary" returns clean output, ready for JSON.parse. Even so, treat the result as untrusted input: check fields, types, and ranges.
Just add another image_url part to the same list. It serves to compare two versions of a document, check before and after, or ask for a conclusion about a set. With two 1024px images, the prompt came to 660 tokens — each image adds to the count.
"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"}}
]| Situation | What happens |
|---|---|
| A URL the API cannot reach | 502 — the call fails as an execution error |
| A call with no image, text only | Answers normally, but usage comes back zeroed |
| An embeddings model on this endpoint | 400 — the model does not serve Chat Completions |
| A model that does not exist | 404 |
Confirm the contract for your account
Availability, pricing, and modalities evolve. GET https://api.hinow.ai/v1/models returns the catalogue in force — but treat the category field as informative: models listed only as text_to_text accepted images in our tests.