Create a reading

Submit one front and back pair with a stable idempotency key.

POST https://ocr.ecostudios.dev/api/v3/ine

By default, one request reads one person's INE, front and back. V3 also accepts an explicit single-side mode. Send the files as multipart/form-data; JSON, image URLs, PDFs and base64 uploads are not accepted by this endpoint.

Headers and form fields

Name	Required	Meaning
`X-API-Key`	Yes	Your server-side API key.
`Idempotency-Key`	Yes	Stable identifier for this transaction: 8–128 characters, using letters, digits, `.`, `_`, `:` or `-`.
`Accept: application/json`	Recommended	Request a JSON response.
`front`	With `both` or `front` mode	Exactly one front image; omit in `back` mode.
`back`	With `both` or `back` mode	Exactly one back image; omit in `front` mode.
`mode`	No	`both` (default), `front` or `back`.
`profile`	No	`standard` (default) or opt-in `extended`. See extended reading.

Let your multipart library generate Content-Type with its boundary. Do not set a bare multipart/form-data header when using FormData or cURL -F.

Image requirements

Property	Limit
Format	Static JPG, PNG or WEBP; animated images are rejected.
File size	32 bytes to 5 MiB per side.
Minimum dimensions	240 pixels wide and 140 pixels high.
Maximum dimensions	6,000 pixels on either side and 16 megapixels total.
Side contents	Front and back must have different bytes.

Keep the full credential visible, upright, sharply focused and free of glare. Avoid fingers covering text and large backgrounds. Passing technical limits does not establish that every character is readable. Some permitted images can still be too complex to prepare; image_too_complex asks for smaller dimensions or a tighter background crop.

Responses

The first POST waits for the reading. A completed reading returns HTTP 200; see the response fields. A replay while the same job is still processing can return HTTP 202:

{
  "request_id": "00000000-0000-4000-8000-000000000001",
  "status": "processing",
  "status_url": "/api/v3/ine/00000000-0000-4000-8000-000000000001"
}

The processing response includes Retry-After: 2 and a relative Location matching status_url. A 202 is a state report, not a durable-queue guarantee. Follow retrieve a result.

API responses include X-Request-Id and Cache-Control: no-store. A newly reserved reading can include Server-Timing; its durations are diagnostic, not a latency guarantee. Parallel stage durations must not be added together.

Quota reservation

Authentication, input checks and image inspection happen before reservation. A rejected request that never reserves a job consumes no reading unit. A new reservation occupies one unit. Completed readings and no_fields failures retain it; technical processing failures are credited back when their failure is recorded. The credit adjusts quota, not cash, and does not automatically retry the job. Historical failures retain their recorded usage. See limits and billing.

Reusing the same key, exact images, mode and profile retrieves the same job without another unit. Different bytes or options under an existing key return 409 idempotency_conflict. New photographs require a new key and can consume another unit. Read errors and retries before implementing recovery.