Skip to main content
POST
/
v1
/
files
Upload a reference file
curl --request POST \
  --url https://api.example.com/v1/files \
  --header 'Content-Type: multipart/form-data' \
  --header 'X-Api-Key: <api-key>' \
  --form file='@example-file' \
  --form purpose=reference \
  --form 'metadata=<string>'
{
  "id": "file_01HXMQ7Z3K8Y2NABCDEFGHJKMN",
  "object": "file",
  "purpose": "reference",
  "mime_type": "image/jpeg",
  "size_bytes": 1247892,
  "width_px": 1024,
  "height_px": 768,
  "url": "https://...?token=...",
  "expires_at": "2026-05-04T14:00:00Z",
  "created_at": "2026-05-03T14:00:00Z",
  "metadata": {
    "campaign": "launch-2026"
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.aurous-labs.com/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
X-Api-Key
string
header
required

Your team API key (starts with al_live_ — legacy keys may start with og_).

Headers

​
Idempotency-Key
string

Stripe-style idempotency key (1-256 chars). Same key + same purpose + metadata returns the cached response with Aurous-Idempotent-Replayed: true. Same key against a different route (e.g. previously used on /v1/images) returns 409 invalid_request / idempotency_key_in_use. Replay window is 24 hours. Absent header is treated as non-idempotent (each call processes anew).

​
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

multipart/form-data
​
file
file
required

The image bytes (PNG / JPEG / WebP, max 10MB, max 4096px).

​
purpose
enum<string>
required

How the file will be used downstream.

Available options:
reference,
first_frame,
last_frame
​
metadata
string

JSON-encoded metadata object. Optional.

Response

File stored

​
id
string
required

Opaque file ID.

Example:

"file_01HXMQ7Z3K8Y2NABCDEFGHJKMN"

​
object
string
required

Object discriminator.

Example:

"file"

​
purpose
enum<string>
required
Available options:
reference,
first_frame,
last_frame
Example:

"reference"

​
mime_type
enum<string>
required
Available options:
image/png,
image/jpeg,
image/webp
Example:

"image/jpeg"

​
size_bytes
number
required

File size in bytes.

Example:

1247892

​
width_px
object
required

Decoded image width in pixels (max 4096).

Example:

1024

​
height_px
object
required

Decoded image height in pixels (max 4096).

Example:

768

​
url
string
required

Time-limited signed URL valid for ~1h. Re-mint a fresh URL by re-fetching GET /v1/files/:id. Do NOT cache long-term — the underlying bucket is private.

Example:

"https://...?token=..."

​
expires_at
string
required

Hard 24h TTL — the file is automatically purged at this timestamp.

Example:

"2026-05-04T14:00:00Z"

​
created_at
string
required

Creation timestamp.

Example:

"2026-05-03T14:00:00Z"

​
metadata
object

Echoed metadata.

Example:
{ "campaign": "launch-2026" }