API reference

Characters

A character keeps a person’s identity consistent across generations. Create one from three face photos, or from a preset portrait. Characters also own social accounts for publishing. Plan limits apply (Influencer 10, Agency 30).

The character object

idstring
Character ID.
objectstring
Always character.
namestring
Display name.
genderstring
male or female.
voice_keystring | null
Voice used where the character speaks; see Voices.
imagesstring[]
Stored reference photos.
typestring
photo or preset.
preset_base_idstring | null
Preset used, for preset characters.
analysisobject | null
Appearance analysis used to keep the identity consistent.
created_atinteger
Unix ms.
updated_atinteger
Unix ms.

Create a character

POST/v1/characters

Scope: generateIdempotency-Key requiredReturns 201

From exactly three clear photos of the same face. Free. You must have the person’s consent (see the API terms).

Body

namestringrequired
1–30 characters.
genderstringrequired
male or female.
imagesstring (media)[]required
Exactly 3 face photos. Upload ID (upl_…), public https:// URL, or base64 data URL.
voice_keystring
Voice key; defaults to the standard voice.

Errors

Code	When
`LIMIT_REACHED`	Character limit for the plan reached (`details.code` = CHARACTER_LIMIT).
`VALIDATION_ERROR`	Wrong number of images or an unavailable voice.

Request

curl -X POST https://api.oriorai.com/v1/characters \
  -H "Authorization: Bearer $ORIOR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Ava",
  "gender": "female",
  "images": [
    "upl_a1…",
    "https://example.com/ava-2.jpg",
    "upl_c3…"
  ],
  "voice_key": "voice-aria"
}'

const response = await fetch('https://api.oriorai.com/v1/characters', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ORIOR_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Ava",
    "gender": "female",
    "images": [
      "upl_a1…",
      "https://example.com/ava-2.jpg",
      "upl_c3…"
    ],
    "voice_key": "voice-aria"
  }),
})
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/characters",
    headers={"Authorization": f"Bearer {os.environ['ORIOR_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "name": "Ava",
        "gender": "female",
        "images": ["upl_a1…", "https://example.com/ava-2.jpg", "upl_c3…"],
        "voice_key": "voice-aria",
    },
    timeout=60,
)
response.raise_for_status()
data = response.json()

Response · 201

Response

{
  "id": "Qx8p2LmN4vRt",
  "object": "character",
  "name": "Ava",
  "gender": "female",
  "voice_key": "voice-aria",
  "type": "photo",
  "preset_base_id": null,
  "images": [
    "https://storage.googleapis.com/…/characters/Qx8p2LmN4vRt/face-0.jpg",
    "…",
    "…"
  ],
  "analysis": {
    "character_analysis": {
      "detailed_description": "…"
    }
  },
  "created_at": 1758620000000,
  "updated_at": 1758620000000
}

List preset characters

GET/v1/characters/presets

Scope: readReturns 200

base_id values for preset characters: ready portraits (used as-is) and customisable base looks.

No parameters

Request

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

const response = await fetch('https://api.oriorai.com/v1/characters/presets', {
  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/characters/presets",
    headers={"Authorization": f"Bearer {os.environ['ORIOR_API_KEY']}"},
    timeout=60,
)
response.raise_for_status()
data = response.json()

Response · 200

Response

{
  "object": "list",
  "ready": [
    {
      "base_id": "mila",
      "name": "Mila",
      "gender": "female",
      "description": "…",
      "collection": "Natural",
      "image_url": "https://www.oriorai.com/presets/ready/mila.webp",
      "customizable": false
    }
  ],
  "customizable": [
    {
      "base_id": "luna",
      "name": "Luna",
      "gender": "female",
      "description": "…",
      "customizable": true,
      "defaults": {
        "skin_tone": "light",
        "hair_color": "brown",
        "eye_color": "brown",
        "body_type": "slim",
        "age_range": "young"
      }
    }
  ]
}

Create a preset character

POST/v1/characters/preset

Scope: generateIdempotency-Key requiredReturns 201

From a preset portrait. Costs 2 credits.

Body

namestringrequired
1–20 characters.
base_idstringrequired
From List preset characters.
customizationobject
Required for customisable bases, ignored for ready portraits.
- skin_tonestringrequired
  light or medium.
- hair_colorstringrequired
  black, brown or blonde.
- eye_colorstringrequired
  brown, green or blue.
- body_typestringrequired
  slim, average or athletic.
- age_rangestringrequired
  young, middle or mature.
voice_keystring
Voice key.

Errors

Code	When
`VALIDATION_ERROR`	Unknown base_id or invalid customization.
`INSUFFICIENT_CREDITS`	Balance below 2 credits.

Request

curl -X POST https://api.oriorai.com/v1/characters/preset \
  -H "Authorization: Bearer $ORIOR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Luna",
  "base_id": "luna",
  "customization": {
    "skin_tone": "light",
    "hair_color": "blonde",
    "eye_color": "green",
    "body_type": "slim",
    "age_range": "young"
  }
}'

const response = await fetch('https://api.oriorai.com/v1/characters/preset', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ORIOR_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Luna",
    "base_id": "luna",
    "customization": {
      "skin_tone": "light",
      "hair_color": "blonde",
      "eye_color": "green",
      "body_type": "slim",
      "age_range": "young"
    }
  }),
})
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/characters/preset",
    headers={"Authorization": f"Bearer {os.environ['ORIOR_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "name": "Luna",
        "base_id": "luna",
        "customization": {
            "skin_tone": "light",
            "hair_color": "blonde",
            "eye_color": "green",
            "body_type": "slim",
            "age_range": "young",
        },
    },
    timeout=60,
)
response.raise_for_status()
data = response.json()

Response · 201

Response

{
  "id": "Qx8p2LmN4vRt",
  "object": "character",
  "name": "Luna",
  "gender": "female",
  "voice_key": "voice-aria",
  "type": "preset",
  "preset_base_id": "luna",
  "images": [
    "https://storage.googleapis.com/…"
  ],
  "analysis": {
    "character_analysis": {
      "detailed_description": "…"
    }
  },
  "created_at": 1758620000000,
  "updated_at": 1758620000000
}

List characters

GET/v1/characters

Scope: readReturns 200

All characters of the account, newest first.

No parameters

Request

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

const response = await fetch('https://api.oriorai.com/v1/characters', {
  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/characters",
    headers={"Authorization": f"Bearer {os.environ['ORIOR_API_KEY']}"},
    timeout=60,
)
response.raise_for_status()
data = response.json()

Response · 200

Response

{
  "data": [
    {
      "id": "Qx8p2LmN4vRt",
      "object": "character",
      "name": "Ava",
      "gender": "female",
      "voice_key": "voice-aria",
      "type": "photo",
      "preset_base_id": null,
      "images": [
        "https://storage.googleapis.com/…/characters/Qx8p2LmN4vRt/face-0.jpg",
        "…",
        "…"
      ],
      "analysis": {
        "character_analysis": {
          "detailed_description": "…"
        }
      },
      "created_at": 1758620000000,
      "updated_at": 1758620000000
    }
  ]
}

Retrieve a character

GET/v1/characters/{id}

Scope: readReturns 200

One character.

Path parameters

idstringrequired
Character ID.

Request

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

const response = await fetch('https://api.oriorai.com/v1/characters/Qx8p2LmN4vRt', {
  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/characters/Qx8p2LmN4vRt",
    headers={"Authorization": f"Bearer {os.environ['ORIOR_API_KEY']}"},
    timeout=60,
)
response.raise_for_status()
data = response.json()

Response · 200

Response

{
  "id": "Qx8p2LmN4vRt",
  "object": "character",
  "name": "Ava",
  "gender": "female",
  "voice_key": "voice-aria",
  "type": "photo",
  "preset_base_id": null,
  "images": [
    "https://storage.googleapis.com/…/characters/Qx8p2LmN4vRt/face-0.jpg",
    "…",
    "…"
  ],
  "analysis": {
    "character_analysis": {
      "detailed_description": "…"
    }
  },
  "created_at": 1758620000000,
  "updated_at": 1758620000000
}

Update a character

PATCH/v1/characters/{id}

Scope: generateIdempotency-Key requiredReturns 200

Rename or change the voice. Send at least one field.

Path parameters

idstringrequired
Character ID.

Body

namestring
1–30 characters.
voice_keystring | null
New voice; null resets to the default.

Request

curl -X PATCH https://api.oriorai.com/v1/characters/Qx8p2LmN4vRt \
  -H "Authorization: Bearer $ORIOR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Ava Rose"
}'

const response = await fetch('https://api.oriorai.com/v1/characters/Qx8p2LmN4vRt', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.ORIOR_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Ava Rose"
  }),
})
const data = await response.json()
if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`)

import os, uuid
import requests

response = requests.patch(
    "https://api.oriorai.com/v1/characters/Qx8p2LmN4vRt",
    headers={"Authorization": f"Bearer {os.environ['ORIOR_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "name": "Ava Rose",
    },
    timeout=60,
)
response.raise_for_status()
data = response.json()

Response · 200

Response

{
  "id": "Qx8p2LmN4vRt",
  "object": "character",
  "name": "Ava Rose",
  "gender": "female",
  "voice_key": "voice-aria",
  "type": "photo",
  "preset_base_id": null,
  "images": [
    "https://storage.googleapis.com/…/characters/Qx8p2LmN4vRt/face-0.jpg",
    "…",
    "…"
  ],
  "analysis": {
    "character_analysis": {
      "detailed_description": "…"
    }
  },
  "created_at": 1758620000000,
  "updated_at": 1758620000000
}

Delete a character

DELETE/v1/characters/{id}

Scope: generateIdempotency-Key requiredReturns 200

Deletes the character and its photos and disconnects its social accounts. Past generations are kept.

Path parameters

idstringrequired
Character ID.

Request

curl -X DELETE https://api.oriorai.com/v1/characters/Qx8p2LmN4vRt \
  -H "Authorization: Bearer $ORIOR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

const response = await fetch('https://api.oriorai.com/v1/characters/Qx8p2LmN4vRt', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.ORIOR_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
  },
})
const data = await response.json()
if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`)

import os, uuid
import requests

response = requests.delete(
    "https://api.oriorai.com/v1/characters/Qx8p2LmN4vRt",
    headers={"Authorization": f"Bearer {os.environ['ORIOR_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    timeout=60,
)
response.raise_for_status()
data = response.json()

Response · 200

Response

{
  "id": "Qx8p2LmN4vRt",
  "object": "character",
  "deleted": true
}