Mint a character upload URL

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

import requests

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

payload = {
    "filename": "front-portrait.jpg",
    "extension": "jpg",
    "content_type": "image/jpeg"
}
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({filename: 'front-portrait.jpg', extension: 'jpg', content_type: 'image/jpeg'})
};

fetch('https://api.aurous-labs.com/v1/characters/uploads/init', 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/init",
  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([
    'filename' => 'front-portrait.jpg',
    'extension' => 'jpg',
    'content_type' => 'image/jpeg'
  ]),
  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/init"

	payload := strings.NewReader("{\n  \"filename\": \"front-portrait.jpg\",\n  \"extension\": \"jpg\",\n  \"content_type\": \"image/jpeg\"\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/init")
  .header("X-Api-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"filename\": \"front-portrait.jpg\",\n  \"extension\": \"jpg\",\n  \"content_type\": \"image/jpeg\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"filename\": \"front-portrait.jpg\",\n  \"extension\": \"jpg\",\n  \"content_type\": \"image/jpeg\"\n}"

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

{
  "upload_id": "upl_01HXMQ7Z3K8Y2NABCDEFGHJKMR",
  "upload_url": "https://aurous.storage/.../upload?signature=…",
  "upload_headers": {
    "Content-Type": "image/jpeg"
  },
  "expires_at": "2026-05-08T10:15:00Z"
}

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

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

import requests

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

payload = {
    "filename": "front-portrait.jpg",
    "extension": "jpg",
    "content_type": "image/jpeg"
}
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({filename: 'front-portrait.jpg', extension: 'jpg', content_type: 'image/jpeg'})
};

fetch('https://api.aurous-labs.com/v1/characters/uploads/init', 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/init",
  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([
    'filename' => 'front-portrait.jpg',
    'extension' => 'jpg',
    'content_type' => 'image/jpeg'
  ]),
  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/init"

	payload := strings.NewReader("{\n  \"filename\": \"front-portrait.jpg\",\n  \"extension\": \"jpg\",\n  \"content_type\": \"image/jpeg\"\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/init")
  .header("X-Api-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"filename\": \"front-portrait.jpg\",\n  \"extension\": \"jpg\",\n  \"content_type\": \"image/jpeg\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"filename\": \"front-portrait.jpg\",\n  \"extension\": \"jpg\",\n  \"content_type\": \"image/jpeg\"\n}"

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

{
  "upload_id": "upl_01HXMQ7Z3K8Y2NABCDEFGHJKMR",
  "upload_url": "https://aurous.storage/.../upload?signature=…",
  "upload_headers": {
    "Content-Type": "image/jpeg"
  },
  "expires_at": "2026-05-08T10:15:00Z"
}

{
  "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/init mints an upload ticket: a short-lived signed PUT URL plus an opaque upload_id. Upload your image bytes to that URL, then spend the ticket on one of two routes:

PUT /v1/characters/{id}/refs/{view} — the builder. The photo becomes the reference for one named view, used as-is, after a fit check. Pay only for the views you do not fill.
POST /v1/characters — the one-shot create. The photos are the input to synthesis; the platform renders all eight views from them and charges for all eight.

POST /v1/characters/uploads/classify can label a ticket’s pose first, but it is optional on either path. You typically call this endpoint once per reference image. A one-shot create accepts 1–6 photos; those photos are the input to synthesis, and the references the character will carry are the eight named views the platform renders from them — see List character views. Screen the file locally first. GET /v1/characters/views returns a constraints object — min_short_side_px, max_aspect_ratio, max_dimension_px, content_types — and those are exactly the values the builder enforces on PUT /v1/characters/{id}/refs/{view}. Checking them client-side turns a wasted mint-upload-reject round-trip into a local comparison.

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 are filling a draft’s views one at a time with the builder — mint one ticket per photo.
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

POST /v1/characters/uploads/init → { upload_id, upload_url, expires_at }.
PUT <upload_url> with the image bytes (any well-formed PUT, no extra headers required).
Optional: POST /v1/characters/uploads/classify with the same upload_id to detect the pose.
Spend it — either PUT /v1/characters/{id}/refs/{view} with { "upload_id": "upl_..." } to file the photo into one view of a character you already have, or POST /v1/characters with { upload_ids: [upl_..., ...] } to create a character from those photos in one shot.

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

const init = await fetch("https://api.aurous-labs.com/v1/characters/uploads/init", {
  method: "POST",
  headers: {
    "X-Api-Key": process.env.AUROUS_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    filename: "front-portrait.jpg",
    extension: "jpg",
    content_type: "image/jpeg",
  }),
}).then((r) => r.json());

// Echo every header from `upload_headers` on the PUT so the storage
// layer accepts the upload without rewriting the Content-Type.
await fetch(init.upload_url, {
  method: "PUT",
  headers: init.upload_headers,
  body: fs.readFileSync("./ref-portrait.jpg"),
});

console.log(init.upload_id); // pass to POST /v1/characters

import os, requests

init = requests.post(
    "https://api.aurous-labs.com/v1/characters/uploads/init",
    headers={"X-Api-Key": os.environ["AUROUS_API_KEY"]},
    json={
        "filename": "front-portrait.jpg",
        "extension": "jpg",
        "content_type": "image/jpeg",
    },
).json()

# Echo every header from `upload_headers` on the PUT so the storage
# layer accepts the upload without rewriting the Content-Type.
with open("ref-portrait.jpg", "rb") as f:
    requests.put(init["upload_url"], data=f.read(), headers=init["upload_headers"])

print(init["upload_id"])

Limits

Rate limit: bucket characters_post — 30 requests/min sustained, 60 burst per team.
Upload URL TTL: 15 minutes — this is what expires_at in the response reports. Mint a fresh ticket if the PUT would land later.
Upload ticket TTL: 24 hours, and expires_at does not report it. After that the bytes are evicted and upload_id is no longer accepted on POST /v1/characters or PUT /v1/characters/{id}/refs/{view}.
Tickets are not consumed. Within its 24 hours a ticket stays usable by every route that takes one: classify keeps answering for it, every create that lists it produces a separate character and a separate charge, and a PUT that is refused leaves it fully intact — that is what lets you re-send a wrong_view photo to the view it actually shows without re-uploading the bytes. Guard create retries with an Idempotency-Key rather than relying on the ticket to be spent.

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). 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

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).

Show child attributes

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"

Get started

Guides

Concepts

API Reference

Resources

Mint a character upload URL

When to use

Lifecycle

Example

Limits

Common pitfalls

Authorizations

Headers

Body

Response

​When to use

​Lifecycle

​Example

​Limits

​Common pitfalls

Authorizations

Headers

Body

Response

When to use

Lifecycle

Example

Limits

Common pitfalls