> ## Documentation Index
> Fetch the complete documentation index at: https://docs.astrom8.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Palm and Face Readings

> Private-upload workflow for asynchronous visual readings.

Visual readings are a Pro-tier asynchronous workflow for Palm and Face Reading products. They are feature-gated while visual-provider evaluation is in progress; use the estimate endpoint before building against the flow.

## Workflow

1. `POST /api/v3/visual-readings/estimate` to confirm availability and credits.
2. Create one private upload grant per image.
3. Upload directly to the returned signed URL with the required headers.
4. Complete each upload. AstroM8 validates the checksum and image, normalizes it to JPEG, removes metadata, and deletes the original object.
5. Submit a job with an `Idempotency-Key`.
6. Poll the job. Once complete, it returns a short-lived signed JSON artifact URL.

Face jobs require one upload with `purpose: "face"`. Palm jobs require two uploads with `purpose: "palm_left"` and `purpose: "palm_right"`, plus capture-handedness metadata.

<Note>
  Image inputs are private and are never returned by the API. Normalized input objects are deleted after inference. Store the returned result artifact rather than its one-hour signed URL.
</Note>

Uploads are rejected before billing when their decoded image is undersized, unreadable, animated, very dark, blown out, flat, or too blurred for reliable visual analysis. These are non-semantic image-quality checks; they do not identify a face or hand.

## Idempotency and credits

The job submission uses an atomic transaction: it reserves the idempotency key, verifies ownership and upload state, consumes the uploads, writes usage, and debits credits together. Retrying the same request with the same key replays its original job; a changed body with the same key returns a conflict.

If the worker reaches a terminal failure, it refunds the remaining charged credits exactly once. `json` includes the structured result, `branded` adds private hosted HTML, and `premium` adds a private PDF. If premium PDF rendering fails after the JSON and branded artifacts succeed, the job remains usable and is refunded down to branded pricing.

Failed job responses expose a safe `error_code` such as `provider_unavailable`, `provider_invalid_response`, `invalid_job_payload`, or `processing_failed`; raw provider and infrastructure errors are not exposed.

## Deletion

`DELETE /api/v3/visual-readings/jobs/{jobId}` removes a completed job and its private artifacts. A queued job is cancelled and fully refunded. An in-flight job returns `202` and is cancelled before it can publish an artifact; it is deleted once the worker has removed its normalized inputs.

## Reading scope

The returned reading is cultural and entertainment content grounded in explicit visual observations. It is not identity verification, medical advice, or an assessment of a person. Do not use it to make consequential decisions about people.