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

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

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

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

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

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

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

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

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

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

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

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

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_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
`upload_invalid`	400	`upload_id` is unknown, expired, or already consumed by `POST /v1/characters`.
`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.
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-07-16 for unauthenticated requests.

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

Example:

"2026-07-16"

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