Getting Started

Prerequisites

Before using the Developer API, you need:

1. An account on Image to Text
2. A Developer API Key with the needed scopes
3. Available Processing Credits in your account

Step 1: Create an API Key

Go to Settings → API Keys and click Create API Key. Choose one or more scopes:

• OCR — access to POST /api/v1/ocr
• Image — access to POST /api/v1/images/convert and POST /api/v1/images/compress

The full secret is shown only once at creation time. Store it securely.

Important: API keys are server-side secrets. Never expose them in client-side code, public repositories, or mobile apps.

Step 2: Make Your First Request

Use the Authorization: Bearer <key> header (or x-api-key header) to authenticate:

curl -X POST https://image-to-text.org/api/v1/ocr \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/sample.png",
    "mode": "formatted"
  }'

Both image_url and base64 inputs are supported via JSON. File uploads use multipart/form-data:

curl -X POST https://image-to-text.org/api/v1/ocr \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "mode=formatted"

Step 3: Understand the Response

A successful OCR response looks like:

{
  "success": true,
  "request_id": "abc123...",
  "elapsed_ms": 1500,
  "data": {
    "markdown": "# Document Title\n\n...",
    "text": "Document Title\n\n...",
    "pages": [...],
    "usage": {
      "credits": 10,
      "pages": 3,
      "mode": "formatted"
    }
  }
}

An error response follows a standard contract:

{
  "success": false,
  "request_id": "abc123...",
  "error": {
    "code": "credits_insufficient",
    "message": "Insufficient credits. This OCR API request needs 10 credits.",
    "retryable": false
  }
}

Authentication

All endpoints accept two authentication methods:

Both are equivalent — use whichever is more convenient for your HTTP client.

Idempotency

For billable requests, you can supply an Idempotency-Key header to safely retry without double-charging:

curl -X POST https://image-to-text.org/api/v1/ocr \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: unique-key-2024-001" \
  -F "[email protected]"

The key is valid for 24 hours. Subsequent requests with the same key and identical input return the cached result without charging credits again.

Next Steps

• Read the API Overview for error codes, rate limits, and billing
• See the OCR API Reference for full endpoint details
• See Image Processing API for convert and compress endpoints