Skip to main content
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.
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.
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.