Skip to main content
POST
/
v1
/
characters
/
uploads
/
init
Mint a signed upload URL for one character reference image
curl --request POST \
  --url https://api.aurous-labs.com/v1/characters/uploads/init \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "filename": "front-portrait.jpg",
  "extension": "jpg",
  "content_type": "image/jpeg"
}
'
{
  "upload_id": "upl_01HXMQ7Z3K8Y2NABCDEFGHJKMR",
  "upload_url": "https://aurous.storage/.../upload?signature=…",
  "upload_headers": {
    "Content-Type": "image/jpeg"
  },
  "expires_at": "2026-05-08T10:15:00Z"
}
POST /v1/characters/uploads/init is the first step of the upload flow for creating a character. It returns a short-lived signed PUT URL plus an opaque upload_id. Upload your image bytes to that URL, then pass the upload_id to POST /v1/characters (or call POST /v1/characters/uploads/classify first to detect the pose). You typically call this endpoint once per reference image. A character supports 1–6 refs.

​
When to use

  • You already have ref images on disk or in your own storage and want to attach them to a new character without round-tripping bytes through your API.
  • You want to capture pose metadata before committing the character (use upload-classify).
If instead you want the platform to generate refs from a text description, skip the upload flow and pass generate: true + attributes to POST /v1/characters (the synthesize flow).

​
Lifecycle

  1. POST /v1/characters/uploads/init → { upload_id, upload_url, expires_at }.
  2. PUT <upload_url> with the image bytes (any well-formed PUT, no extra headers required).
  3. Optional: POST /v1/characters/uploads/classify with the same upload_id to detect the pose.
  4. POST /v1/characters with { upload_ids: [upl_..., ...] } to consume the uploads and create the character.

​
Example

# 1. Mint the URL
curl -X POST https://api.aurous-labs.com/v1/characters/uploads/init \
  -H "X-Api-Key: $AUROUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "front-portrait.jpg",
    "extension": "jpg",
    "content_type": "image/jpeg"
  }'

# Response: {
#   "upload_id":      "upl_01H...",
#   "upload_url":     "https://...",
#   "upload_headers": { "Content-Type": "image/jpeg" },
#   "expires_at":     "..."
# }

# 2. Upload the bytes (set every header from `upload_headers` on the PUT)
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/jpeg" \
  --data-binary @ref-portrait.jpg

​
Limits

  • Rate limit: bucket characters_post — 30 requests/min sustained, 60 burst per team.
  • Upload URL TTL: 15 minutes. Mint a fresh URL if the PUT lands later.
  • Upload ticket TTL: 24 hours. After that the bytes are evicted and upload_id is no longer accepted on POST /v1/characters.

​
Common pitfalls

  • The upload_url is not authenticated — the signature is in the query string. Do not add X-Api-Key to the PUT.
  • One ticket = one image. Mint multiple tickets in parallel for multi-ref characters.
  • Browsers may need a CORS-aware proxy in front of the PUT — the V1 surface targets server-side integrators and does not advertise CORS headers on the upload host.

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
​
filename
string
required

Original filename (used for Content-Disposition; not stored as the storage key).

Required string length: 1 - 120
Example:

"front-portrait.jpg"

​
extension
enum<string>
required

File extension. Must match content_type; mismatched combinations return 400.

Available options:
jpeg,
jpg,
png,
webp
Example:

"jpg"

​
content_type
enum<string>
required

MIME type. Must match extension; mismatched combinations return 400.

Available options:
image/jpeg,
image/png,
image/webp
Example:

"image/jpeg"

Response

Upload ticket minted

​
upload_id
string
required

Upload ticket ID. Use as upload_id on POST /v1/characters/uploads/classify and POST /v1/characters.

Example:

"upl_01HXMQ7Z3K8Y2NABCDEFGHJKMR"

​
upload_url
string
required

Pre-signed PUT URL — upload bytes via HTTP PUT with the headers from upload_headers. The URL expires at expires_at.

Example:

"https://aurous.storage/.../upload?signature=…"

​
upload_headers
object
required

HTTP headers to include on the PUT request (Content-Type matches the request payload).

Example:
{ "Content-Type": "image/jpeg" }
​
expires_at
string
required

Upload URL expiration (ISO 8601). Re-mint via /uploads/init if you need to retry past this point.

Example:

"2026-05-08T10:15:00Z"