Developer Reference

API Documentation

Everything you need to integrate Ocilar in minutes. Base URL: https://api.ocilar.com/api/v1

Authentication

All API requests must include your API key in the X-API-Key header. You can get your API key from your dashboard after creating an account.

Request header

X-API-Key: sk-your_api_key_here

Never expose your API key in client-side code. Always make API calls from your server or backend.

Quickstart

Solve your first CAPTCHA in under a minute.

curl -X POST https://api.ocilar.com/api/v1/solve/sat \
  -H "X-API-Key: sk-..." \
  -H "Content-Type: application/json" \
  -d '{"image":"<base64_string>"}'

# Response
{"text":"2VBF39","latency_ms":69,"credits_used":1}

pip install ocilar

from ocilar import OcilarClient

client = OcilarClient(api_key="sk-...")
result = client.solve_sat(image_base64="<base64>")
print(result.text)  # "2VBF39"

npm install @ocilar/sdk

import { OcilarClient } from '@ocilar/sdk'

const client = new OcilarClient({ apiKey: 'sk-...' })
const { text } = await client.solveSat({ image: base64 })
console.log(text) // "2VBF39"

Rate limits

Rate limits are enforced per API key and depend on your plan.

Plan	Rate limit	Monthly solves
PAYG	3 req/s	Pay per use
Starter	5 req/s	15,000
Pro	20 req/s	75,000
Business	50 req/s	300,000
Enterprise	100 req/s	1,000,000

Rate limit headers are included on every response:

X-RateLimit-Limit: 20
X-RateLimit-Remaining: 18
X-RateLimit-Reset: 1710000060

Image CAPTCHA — SAT / IMSS / Generic

POST /solve/sat · POST /solve/imss · POST /solve/image

Solve image-based CAPTCHAs. Accepts a base64-encoded image. Average latency: <70ms. Accuracy: 97%+.

Request body

Field	Type	Required	Description
`image`	string	Yes	Base64-encoded image (PNG, JPG, WEBP)
`case_sensitive`	boolean	No	Default: true

Response

{
  "text": "2VBF39",
  "confidence": 0.98,
  "latency_ms": 69,
  "credits_used": 1
}

reCAPTCHA v2 / v3

POST /solve/recaptcha

Solve Google reCAPTCHA v2 and v3. Returns a token ready to submit to the target form. reCAPTCHA v3 score is guaranteed ≥0.7.

Request body

Field	Type	Required	Description
`version`	string	Yes	`"v2"` or `"v3"`
`sitekey`	string	Yes	The site key from the target page
`url`	string	Yes	URL of the page with the CAPTCHA
`action`	string	v3 only	reCAPTCHA v3 action name (e.g. `"submit"`)

Response

{
  "token": "03AGdBq25SxXT...",
  "score": 0.9,
  "latency_ms": 3200,
  "credits_used": 1
}

hCaptcha

POST /solve/hcaptcha

Request body

Field	Type	Required	Description
`sitekey`	string	Yes	hCaptcha sitekey
`url`	string	Yes	URL of the page

Response

{
  "token": "P1_eyJ0...",
  "latency_ms": 4100,
  "credits_used": 1
}

Cloudflare Turnstile

POST /solve/turnstile

Request body

Field	Type	Required	Description
`sitekey`	string	Yes	Turnstile sitekey
`url`	string	Yes	URL of the page

Response

{
  "token": "0.AbCdEf...",
  "latency_ms": 2800,
  "credits_used": 1
}

Document AI — INE

POST /extract/ine

Extract structured data from Mexican INE (voter ID). Send both front and back as multipart/form-data.

Request (multipart/form-data)

Field	Type	Description
`front`	file	Front of the INE (JPG, PNG, PDF)
`back`	file	Back of the INE (JPG, PNG, PDF)

Response

{
  "nombre": "JULIO JUAREZ",
  "curp": "JUAJ850101HMCRRL09",
  "clave_elector": "JUJRJL850101HMCRRL09",
  "fecha_nacimiento": "1985-01-01",
  "sexo": "H",
  "estado": "JALISCO",
  "municipio": "GUADALAJARA",
  "seccion": "0123",
  "vigencia": "2029",
  "credits_used": 1
}

Document AI — CSF

POST /extract/csf

Extract data from Constancia de Situación Fiscal (SAT). Accepts PDF.

Response

{
  "rfc": "JUAJ850101ABC",
  "nombre": "JULIO JUAREZ",
  "regimen_fiscal": "612 - Personas Físicas con Actividades Empresariales",
  "codigo_postal": "44100",
  "fecha_inicio_actividades": "2020-01-15",
  "credits_used": 1
}

Document AI — CFDI

POST /extract/cfdi

Extract structured data from CFDI XML invoices.

Response

{
  "uuid": "6128a3d4-...",
  "emisor_rfc": "AAA010101AAA",
  "receptor_rfc": "JUAJ850101ABC",
  "total": 11600.00,
  "subtotal": 10000.00,
  "iva": 1600.00,
  "fecha": "2026-03-16T10:00:00",
  "credits_used": 1
}

Document AI — Generic OCR

POST /extract/ocr

Extract raw text from any image or PDF document. Supports handwriting and printed text.

Request body

Field	Type	Description
`file`	file	Image or PDF (max 10MB)
`language`	string	Optional. e.g. `"es"`, `"en"`. Default: auto-detect

Response

{
  "text": "Full extracted text...",
  "pages": 1,
  "credits_used": 1
}

Error codes

All errors follow this structure:

{
  "error": "invalid_api_key",
  "message": "The provided API key is invalid or expired.",
  "status": 401
}

HTTP	Code	Description
400	`bad_request`	Missing or invalid request parameters
401	`invalid_api_key`	API key missing, invalid, or expired
402	`insufficient_credits`	Account has no credits remaining
422	`solve_failed`	CAPTCHA could not be solved — not charged
429	`rate_limit_exceeded`	Too many requests. Slow down.
500	`internal_error`	Server error — retry with exponential backoff
503	`service_unavailable`	Temporary outage — check status page

Failed solves (422) are not charged to your account.

SDKs & Tools

Python

pip install ocilar

Supports async/await via ocilar.AsyncClient

Node.js

npm install @ocilar/sdk

TypeScript types included

go get github.com/InsaneTreset/ocilar-go

Idiomatic Go with context support

PHP

composer require ocilar/ocilar-php

PSR-18 compatible HTTP client