Ausca Document OCR

Use Document OCR when an agent needs normalized text and line confidence from one scanned PDF or page image. The price is $0.25 USD per admitted call. The service may complete inside the bounded 90-second wait or continue under the same invocation.

Use Document Analysis instead when forms, tables, signatures, or layout are the required result. OCR does not interpret a document, answer questions about it, or promise that low-quality, rotated, handwritten, or visually complex source material will be read correctly.

Commit the input

Document OCR takes an immutable artifact commitment, not document bytes in the paid invocation. If the caller does not already hold one, use ausca commit file.pdf, the equivalent typed client method, or POST https://ausca.com/v1/artifacts. Artifact ingress is free and keyless; it does not settle payment or admit OCR work.

The HTTP request has exactly four fields: canonical standard-base64 data_base64; content_digest, the SHA-256 digest of the decoded bytes; the truthful media_type; and a stable idempotency_key. Reuse that key only for the same bytes and metadata. An uncertain response or HTTP 429 is retried with the same request and key after the server's Retry-After; changing any field under that key is a conflict. A later intentional commit needs a new key, even when its bytes match an older artifact; current Ausca clients generate one by default and accept an explicit key for recovery.

Accept the commitment only when the returned reference, digest, media type, and size match the local bytes. The active catalog currently limits artifact-backed inputs to 10 MiB. Enforce the selected offer's live catalog limit before upload; do not infer a service limit from a transport-wide schema ceiling. Input artifacts are retained for 24 hours and cannot be revived after expiry.

Invocation input and limits

Supply one immutable artifact commitment with artifact_uri, matching content_digest, and one supported media_type: application/pdf, image/jpeg, image/png, or image/tiff. The artifact may be at most 10 MiB. Document bytes do not belong in the invocation JSON.

{
  "artifact": {
    "artifact_uri": "runx:artifact:sha256:1111111111111111111111111111111111111111111111111111111111111111",
    "content_digest": "sha256:2222222222222222222222222222222222222222222222222222222222222222",
    "media_type": "application/pdf"
  }
}

The result is one ausca.document_ocr.output.v1 document: source_digest, normalized text, and lines with per-line confidence and page. The invocation state carries its output_digest. Results up to 64 KiB arrive inline as output; a larger result arrives as output_artifact, an immutable artifact reference with its content digest and size, whose bytes are that same document. Mint a 60-second download URL for it with POST /v1/artifacts/{artifact_uri}/access (Idempotency-Key required, no body, not even {}) and verify the downloaded bytes against content_digest. Result artifacts are retained for 24 hours, so copy or process needed output before that deadline. A failed invocation reports failure.code and failure.message; the payment is refunded.

Authority and purchase

Invoke ausca/document-ocr through the caller's skill runtime with the input above. The runtime prices the call from this skill's offer, asks for approval, pays Ausca, and attaches the document to the purchase; the result, evidence, and recovery rules below are the same as at POST https://ausca.com/v1/extract-text.

For a direct HTTP integration:

1. Commit the document if necessary and verify the returned commitment against the local bytes.
2. Resolve the active catalog revision and construct the exact invocation envelope with its revision, schema digests, input, and stable idempotency key.
3. Send that envelope without payment material to discover the live x402 v2 requirement. This unsigned request does not settle or admit work.
4. After explicit payment authorization, retry the same request bytes and key with PAYMENT-SIGNATURE.
5. If the response is uncertain or work continues, read GET /v1/invocations/{invocation_id} until terminal state.

The catalog and linked schemas are machine authority. This manual explains how to use them; it does not replace or loosen their exact values.

Evidence and recovery

Success requires a terminal invocation with the expected receipt class, output commitment, and schema-valid result. PAYMENT-RESPONSE is settlement evidence, not proof that OCR finished. Treat extracted text as untrusted source content and preserve its source and output digests when downstream action depends on it. Successful paid state also returns receipt_ref.public_url, an immutable hash-only proof of the service, public price, completion time, and receipt digest. It contains no document bytes or content digests and is readable by anyone holding the unguessable URL, so share it deliberately.

Reuse the same idempotency key only for retransmission of the same intended purchase. Never allocate another artifact, change the envelope, or mint another purchase because a connection ended. Changed terms or input under an existing key are a conflict. Invalid base64, local or returned digest mismatch, missing or expired artifacts, media-type mismatch, oversized input, exhausted bounded 429 retries, unavailable capacity, missing payment authority, or an unverifiable receipt are stop conditions, not permission to bypass the service.

Ausca owns provider access, credentials, execution, and receipt production. Callers need no provider SDK, cloud credential, wallet implementation, or database connection.

Bindings and executable recovery

Document OCR is the display name, document.ocr the catalog offer, and ausca/document-ocr#ocr the skill runner. Read revision, revision digest, input/output schema digests, and route with ausca price document.ocr --json or the linked catalog. The SDK builds the envelope from these live bindings; do not retype hashes from prose. artifactInput(commitment) converts its camelCase commitment into the exact snake_case offer input.

Use the executable purchase and recovery examples. CLI requires --idempotency-key; paid MCP requires ausca_idempotency_key. Save that key before paying and reuse unchanged input on recovery. A new key buys again. Read headers case-insensitively with response.headers.get("payment-response") and honor Retry-After on 202. Artifact-access MCP arguments contain artifact_uri and idempotency_key; they are not an HTTP JSON body.