API reference

Uploads

Every media field in the API accepts an upload ID, a public https URL or a base64 data URL. Upload first when a file is large, is reused across requests, or is not publicly reachable.

Uploads are deleted after 7 days. Media attached to a character or product is copied and kept with it.

The upload object

idstring
upl_ + 32 hex characters. Use it in any media field.
kindstring
image, video or audio (from the content type).
content_typestring
MIME type.
sizeinteger | null
Bytes; null until a signed upload finishes.
urlstring
Public URL of the stored file.
statusstring
pending (signed upload not finished) or ready.
created_atinteger
Unix ms.
expires_atinteger
Unix ms, 7 days after creation.

Create an upload

POST/v1/uploads

Scope: generateIdempotency-Key requiredReturns 201

Three modes — send exactly one: content_type (returns a signed URL you PUT the file to, for files up to 200 MB), url (Orior downloads a public https file), or data (inline base64 data URL, up to 20 MB).

Body

content_typestring
Signed mode. image/png, image/jpeg, image/webp, image/heic, image/gif, video/mp4, video/quicktime, video/webm, video/x-m4v, audio/mpeg, audio/mp4, audio/aac, audio/wav, audio/ogg, audio/webm.
sizeinteger
Signed mode, optional. Bytes, checked against the limit up front.
urlstring
Import mode. Public https URL (port 443, no credentials, at most 3 redirects).
datastring
Inline mode. data:<mime>;base64,<…>.

Notes

Signed mode: PUT the raw bytes to upload_url with the returned Content-Type within 15 minutes. The upload becomes ready the first time it is used or retrieved.
Limits: images 20 MB, videos 200 MB, audio 50 MB.

Errors

Code	When
`VALIDATION_ERROR`	Unsupported type, too large, private/unreachable URL, or not a data URL.

Request

curl -X POST https://api.oriorai.com/v1/uploads \
  -H "Authorization: Bearer $ORIOR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "content_type": "video/mp4",
  "size": 48123904
}'

const response = await fetch('https://api.oriorai.com/v1/uploads', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ORIOR_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "content_type": "video/mp4",
    "size": 48123904
  }),
})
const data = await response.json()
if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`)

import os, uuid
import requests

response = requests.post(
    "https://api.oriorai.com/v1/uploads",
    headers={"Authorization": f"Bearer {os.environ['ORIOR_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "content_type": "video/mp4",
        "size": 48123904,
    },
    timeout=60,
)
response.raise_for_status()
data = response.json()

Response · 201

Response

{
  "id": "upl_4f1c9e0a7b2d4c6e8f0a1b2c3d4e5f60",
  "kind": "video",
  "content_type": "video/mp4",
  "size": 48123904,
  "url": "https://storage.googleapis.com/…/api-uploads/…/upl_4f1c….mp4",
  "status": "pending",
  "created_at": 1758620000000,
  "expires_at": 1759224800000,
  "upload_url": "https://storage.googleapis.com/…?X-Goog-Signature=…",
  "upload_method": "PUT",
  "upload_headers": {
    "Content-Type": "video/mp4"
  },
  "upload_expires_at": 1758620900000
}

Retrieve an upload

GET/v1/uploads/{id}

Scope: readReturns 200

Returns the upload; for a signed upload this confirms the file arrived and marks it ready.

Path parameters

idstringrequired
Upload ID.

Errors

Code	When
`VALIDATION_ERROR`	The file was never uploaded, exceeds the limit, or the upload expired.
`NOT_FOUND`	Unknown ID or another account’s upload.

Request

curl https://api.oriorai.com/v1/uploads/upl_4f1c9e0a7b2d4c6e8f0a1b2c3d4e5f60 \
  -H "Authorization: Bearer $ORIOR_API_KEY"

const response = await fetch('https://api.oriorai.com/v1/uploads/upl_4f1c9e0a7b2d4c6e8f0a1b2c3d4e5f60', {
  headers: {
    Authorization: `Bearer ${process.env.ORIOR_API_KEY}`,
  },
})
const data = await response.json()
if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`)

import os
import requests

response = requests.get(
    "https://api.oriorai.com/v1/uploads/upl_4f1c9e0a7b2d4c6e8f0a1b2c3d4e5f60",
    headers={"Authorization": f"Bearer {os.environ['ORIOR_API_KEY']}"},
    timeout=60,
)
response.raise_for_status()
data = response.json()

Response · 200

Response

{
  "id": "upl_4f1c9e0a7b2d4c6e8f0a1b2c3d4e5f60",
  "kind": "video",
  "content_type": "video/mp4",
  "size": 48123904,
  "url": "https://storage.googleapis.com/…",
  "status": "ready",
  "created_at": 1758620000000,
  "expires_at": 1759224800000
}