Classify an uploaded ref

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"
}
'

import requests

url = "https://api.aurous-labs.com/v1/characters/uploads/classify"

payload = { "upload_id": "upl_01HXMQ7Z3K8Y2NABCDEFGHJKMR" }
headers = {
    "X-Api-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({upload_id: 'upl_01HXMQ7Z3K8Y2NABCDEFGHJKMR'})
};

fetch('https://api.aurous-labs.com/v1/characters/uploads/classify', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.aurous-labs.com/v1/characters/uploads/classify",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'upload_id' => 'upl_01HXMQ7Z3K8Y2NABCDEFGHJKMR'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Api-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.aurous-labs.com/v1/characters/uploads/classify"

	payload := strings.NewReader("{\n  \"upload_id\": \"upl_01HXMQ7Z3K8Y2NABCDEFGHJKMR\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Api-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.aurous-labs.com/v1/characters/uploads/classify")
  .header("X-Api-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"upload_id\": \"upl_01HXMQ7Z3K8Y2NABCDEFGHJKMR\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.aurous-labs.com/v1/characters/uploads/classify")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"upload_id\": \"upl_01HXMQ7Z3K8Y2NABCDEFGHJKMR\"\n}"

response = http.request(request)
puts response.read_body

{
  "upload_id": "upl_01HXMQ7Z3K8Y2NABCDEFGHJKMR",
  "pose": "front",
  "confidence": 0.92
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt",
    "reason": "wrong_view",
    "detected_view": "full_left"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt",
    "reason": "wrong_view",
    "detected_view": "full_left"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt",
    "reason": "wrong_view",
    "detected_view": "full_left"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt",
    "reason": "wrong_view",
    "detected_view": "full_left"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt",
    "reason": "wrong_view",
    "detected_view": "full_left"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt",
    "reason": "wrong_view",
    "detected_view": "full_left"
  }
}

POST

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"
}
'

import requests

url = "https://api.aurous-labs.com/v1/characters/uploads/classify"

payload = { "upload_id": "upl_01HXMQ7Z3K8Y2NABCDEFGHJKMR" }
headers = {
    "X-Api-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({upload_id: 'upl_01HXMQ7Z3K8Y2NABCDEFGHJKMR'})
};

fetch('https://api.aurous-labs.com/v1/characters/uploads/classify', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.aurous-labs.com/v1/characters/uploads/classify",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'upload_id' => 'upl_01HXMQ7Z3K8Y2NABCDEFGHJKMR'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Api-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.aurous-labs.com/v1/characters/uploads/classify"

	payload := strings.NewReader("{\n  \"upload_id\": \"upl_01HXMQ7Z3K8Y2NABCDEFGHJKMR\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Api-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.aurous-labs.com/v1/characters/uploads/classify")
  .header("X-Api-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"upload_id\": \"upl_01HXMQ7Z3K8Y2NABCDEFGHJKMR\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.aurous-labs.com/v1/characters/uploads/classify")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"upload_id\": \"upl_01HXMQ7Z3K8Y2NABCDEFGHJKMR\"\n}"

response = http.request(request)
puts response.read_body

{
  "upload_id": "upl_01HXMQ7Z3K8Y2NABCDEFGHJKMR",
  "pose": "front",
  "confidence": 0.92
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt",
    "reason": "wrong_view",
    "detected_view": "full_left"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt",
    "reason": "wrong_view",
    "detected_view": "full_left"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt",
    "reason": "wrong_view",
    "detected_view": "full_left"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt",
    "reason": "wrong_view",
    "detected_view": "full_left"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt",
    "reason": "wrong_view",
    "detected_view": "full_left"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt",
    "reason": "wrong_view",
    "detected_view": "full_left"
  }
}

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.

The five labels this endpoint returns predate the named views and are not the same vocabulary — they are a hint for your own upload UI, not a view name. A character’s references are addressed by view; see List character views.

New integrations should reach for PUT /v1/characters/{id}/refs/{view} instead. That route tells you the same thing and more, against the real eight-view vocabulary: it either files the photo into the view you named or returns 422 reference_unfit with a reason — and detected_view when the photo simply shows a different view, so you can re-send the same ticket to the right slot. This endpoint stays supported for the one-shot create flow; it is a legacy five-value labeller, not a fit check, and a label from it is never a guarantee that a photo will be accepted.

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_01HXMQ7Z3K8Y2VNABCDEFGHJKM"}'

const result = await fetch(
  "https://api.aurous-labs.com/v1/characters/uploads/classify",
  {
    method: "POST",
    headers: {
      "X-Api-Key": process.env.AUROUS_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ upload_id: "upl_01HXMQ7Z3K8Y2VNABCDEFGHJKM" }),
  },
).then((r) => r.json());

console.log(result.pose, result.confidence); // e.g. "front", 0.94

import os, requests

r = requests.post(
    "https://api.aurous-labs.com/v1/characters/uploads/classify",
    headers={"X-Api-Key": os.environ["AUROUS_API_KEY"]},
    json={"upload_id": "upl_01HXMQ7Z3K8Y2VNABCDEFGHJKM"},
).json()

print(r["pose"], r["confidence"])

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

Code	HTTP	When
`resource_not_found`	404	`upload_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. Its five labels do not map onto the eight named views: other covers four of them.
A classify result does not predict what the builder will accept. PUT /v1/characters/{id}/refs/{view} also checks dimensions, content policy, how many people are in frame and the nudity rules — see Views and lifecycle.
The confidence score is informative, not a gate. A low-confidence front is still a valid front for the synthesize layer.
Creating a character does not consume the ticket: classify keeps answering for the same upload_id until its 24-hour lifetime ends, and the ticket can be listed on another create (which produces another character and another charge).

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). Omit the header to receive the platform default, currently 2026-08-26.

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

Example:

"2026-08-26"

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

Get started

Guides

Concepts

API Reference

Resources

Classify an uploaded ref

When to use

Example

Limits

Errors

Common pitfalls

Authorizations

Headers

Body

Response

​When to use

​Example

​Limits

​Errors

​Common pitfalls

Authorizations

Headers

Body

Response

When to use

Example

Limits

Errors

Common pitfalls