TOOLS

OCR an Image API

Read the text in an image, by URL or as an inline base64 upload. Returns the full text plus every detected line with its confidence score and pixel bounding box. Runs locally on PP-OCR/ONNX — no cloud vision API, no per-image fee.

ocrimagetextrecognitionvisiondocument

Try it free Get an API key

How to call it

Send one POST to api.upapi.io/image-ocr.post with your key in the X-Api-Key header and the parameters below as a JSON body. Each call spends 4 weighted units of your monthly quota. The operation times out after 25 seconds. Identical requests are served from cache for 86400 seconds, unbilled.

endpoint

POST https://api.upapi.io/image-ocr.post

OCR an Image API reference

Request parameters

url: string — Public URL of the image to read (e.g. https://example.com/receipt.png). Provide this OR file, not both.
file: string — The image itself, base64-encoded (no data: URI prefix). Max 3.7 MB decoded — base64 inflates by 4/3 and the API request body is capped at 5 MB. Supply url instead for anything larger. Expected media type image/*.
languages: array — Scripts present in the image (e.g. en). Supported: ch, en — one bundled model covers Latin and Chinese. Omit for the default.

Response fields

text: stringrequired — All recognised text, one detected line per row
width: integerrequired — Image width in pixels
blocks: arrayrequired — Each detected line with its confidence and box
blocks[].bbox: objectrequired
blocks[].bbox.x: integerrequired — Left edge, pixels from the image's left
blocks[].bbox.y: integerrequired — Top edge, pixels from the image's top
blocks[].bbox.width: integerrequired
blocks[].bbox.height: integerrequired
blocks[].text: stringrequired — Text of this detected line
blocks[].confidence: numberrequired — Recognition confidence, 0-1
height: integerrequired — Image height in pixels
truncated: booleanrequired — True when more than 5000 text blocks were detected and cut

Example request and response

The example response is generated from this operation’s published output schema — it shows the shape and field names, not values from a recorded call.

json — example request body

{
  "url": "https://example.com/receipt.png"
}

json — example response shape

{
  "text": "Hello, world",
  "width": 1,
  "blocks": [
    {
      "bbox": {
        "x": 1,
        "y": 1,
        "width": 1,
        "height": 1
      },
      "text": "Hello, world",
      "confidence": 1
    }
  ],
  "height": 1,
  "truncated": false
}

Code snippets

cURL

curl

curl -X POST https://api.upapi.io/image-ocr.post \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{ "url": "https://example.com/receipt.png" }'

JavaScript

javascript

const response = await fetch('https://api.upapi.io/image-ocr.post', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY',
  },
  body: JSON.stringify({
  "url": "https://example.com/receipt.png"
}),
});

const data = await response.json();
console.log(data);

Python

python

import requests

response = requests.post(
    'https://api.upapi.io/image-ocr.post',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': 'YOUR_API_KEY',
    },
    json={
  "url": "https://example.com/receipt.png"
},
)

print(response.json())

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	payload := []byte(`{ "url": "https://example.com/receipt.png" }`)

	req, _ := http.NewRequest("POST", "https://api.upapi.io/image-ocr.post", bytes.NewBuffer(payload))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("x-api-key", "YOUR_API_KEY")

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	var result map[string]any
	json.Unmarshal(body, &result)
	fmt.Println(result)
}

PHP

php

<?php

$payload = json_encode([
    'url' => 'https://example.com/receipt.png',
]);

$ch = curl_init('https://api.upapi.io/image-ocr.post');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'x-api-key: YOUR_API_KEY',
    ],
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
var_dump($data);

Ruby

ruby

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://api.upapi.io/image-ocr.post')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = uri.scheme == 'https'

request = Net::HTTP::Post.new(uri.path)
request['Content-Type'] = 'application/json'
request['x-api-key'] = 'YOUR_API_KEY'
request.body = { "url": "https://example.com/receipt.png" }.to_json

response = http.request(request)
puts JSON.parse(response.body)

Java

java

import okhttp3.*;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.util.Map;

OkHttpClient client = new OkHttpClient();
ObjectMapper mapper = new ObjectMapper();

String json = "{ \"url\": \"https://example.com/receipt.png\" }";

RequestBody body = RequestBody.create(json, MediaType.get("application/json"));
Request request = new Request.Builder()
    .url("https://api.upapi.io/image-ocr.post")
    .post(body)
    .addHeader("Content-Type", "application/json")
    .addHeader("x-api-key", "YOUR_API_KEY")
    .build();

try (Response response = client.newCall(request).execute()) {
    Map<?, ?> result = mapper.readValue(response.body().string(), Map.class);
    System.out.println(result);
}

csharp

using System.Net.Http;
using System.Net.Http.Json;
using System.Text.Json;

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");

var payload = JsonSerializer.Deserialize<object>("{ \"url\": \"https://example.com/receipt.png\" }");
var response = await client.PostAsJsonAsync("https://api.upapi.io/image-ocr.post", payload);

var result = await response.Content.ReadFromJsonAsync<JsonElement>();
Console.WriteLine(result);

Frequently asked questions

How much does the OCR an Image API cost per call?

Each call spends 4 weighted units of your plan's monthly quota. Full pricing is at https://upapi.io/pricing.

How do I authenticate to the OCR an Image API?

Send your key in the X-Api-Key header. A free guest key is available without creating an account.

Are OCR an Image API responses cached?

Yes — identical requests are served from cache for 86400 seconds, and a cache hit is not billed.

More Tools APIs

Extract Text from PDF Render HTML or URL to PDF Capture Website Screenshot Search Hacker News Fetch URL as Markdown Get Cloudflare Page Title

Browse every Tools API →