Skip to main content
POST
/
v1
/
characters
/
uploads
/
classify
Classify the pose of an uploaded reference image
curl --request POST \
  --url https://api.aurous-labs.com/v1/characters/uploads/classify \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "upload_id": "upl_01HXMQ7Z3K8Y2NABCDEFGHJKMR"
}
'
{
  "upload_id": "upl_01HXMQ7Z3K8Y2NABCDEFGHJKMR",
  "pose": "front",
  "confidence": 0.92
}
POST /v1/characters/uploads/classify runs pose detection on an uploaded reference image and returns a label (portrait, front, side, back, or other) plus a confidence score. Call it after the PUT to upload_url finishes and before POST /v1/characters if you want to label or de-duplicate refs in your own UI. This endpoint is optional. The platform does not require classification before consuming an upload_id — refs without a labeled pose default to other.

​
When to use

  • You’re building an upload UI where customers can review which pose was detected before committing.
  • You want to reject a duplicate front upload before the user submits the form.
  • You want to display the detected pose alongside the uploaded thumbnail.
If you don’t need any of that, skip classify and call POST /v1/characters directly with upload_ids.

​
Example

curl -X POST https://api.aurous-labs.com/v1/characters/uploads/classify \
  -H "X-Api-Key: $AUROUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"upload_id": "upl_01HXMQ7Z3K8Y2ABCDEFGHJKM"}'

​
Limits

  • Rate limit: bucket characters_post — 30 requests/min sustained, 60 burst per team.
  • Idempotent: yes — classify is a pure read of the uploaded bytes; calling twice returns the same answer (no duplicate cost).

​
Errors

CodeHTTPWhen
upload_invalid400upload_id is unknown, expired, or already consumed by POST /v1/characters.
resource_not_found404upload_id belongs to a different team.

​
Common pitfalls

  • Classify returns other for poses that don’t match the canon — don’t surface “unknown” as an error in your UI; treat it as an acceptable label.
  • The confidence score is informative, not a gate. A low-confidence front is still a valid front for the synthesize layer.
  • Once POST /v1/characters consumes the upload, calling classify on the same upload_id returns 400 upload_invalid. Cache the classify result client-side if you need it later.

Authorizations

​
X-Api-Key
string
header
required

Your team API key (starts with al_live_).

Headers

​
Aurous-Version
string

Optional API version pin (YYYY-MM-DD). Defaults to your team's pinned version, or the system default 2026-05-15 for unauthenticated requests.

Pattern: ^\d{4}-\d{2}-\d{2}$
Example:

"2026-05-15"

Body

application/json
​
upload_id
string
required

Upload ticket ID returned by POST /v1/characters/uploads/init.

Example:

"upl_01HXMQ7Z3K8Y2NABCDEFGHJKMR"

Response

Classification result

​
upload_id
string
required

Upload ticket ID echoed back.

Example:

"upl_01HXMQ7Z3K8Y2NABCDEFGHJKMR"

​
pose
enum<string>
required

Detected pose for the uploaded image.

Available options:
portrait,
front,
side,
back,
other
Example:

"front"

​
confidence
number
required

Classifier confidence score on the 0-1 range.

Required range: 0 <= x <= 1
Example:

0.92