API reference

Generations

Every image and video request creates a generation. It moves queued → processing → completed | failed, or queued → cancelled. Credits for failed and cancelled generations are refunded automatically.

The generation object

idstring
Identifier, gen_ + 32 hex characters.
objectstring
Always generation.
typestring
image or video.
modelstring
orior-image for images; the video model ID for videos.
statusstring
One of queued · processing · completed · failed · cancelled. Terminal states: completed, failed, cancelled.
creditsinteger
Credits charged when the request was accepted.
refunded_creditsinteger
Credits returned (failed, cancelled, or unspent). Net cost = credits − refunded_credits.
resultobject | null
Present when completed.
- urlstring
  Full-resolution output (WebP image or MP4 video). Permanent until you delete the generation.
- thumbnail_urlstring | null
  Small preview (400px for images; poster for videos when available).
errorobject | null
Present when failed or cancelled.
- codestring
  CONTENT_BLOCKED, INSUFFICIENT_CREDITS, TIMEOUT, PROVIDER_ERROR, RATE_LIMIT, VALIDATION_ERROR, UNKNOWN or CANCELLED.
- messagestring
  Human-readable explanation. Do not parse; use code.
requestobject
The normalised parameters the generation ran with (defaults filled in). Media inputs are summarised, not echoed.
timelinearray
Stage failures and automatic recoveries recorded while generating — see Generations.
- atinteger
  Unix time in milliseconds.
- stagestring
  scene_analysis, character_analysis, prompt_merge, text_model, image_generation, video_generation, storage or queue.
- resolutionstring
  What happened next: continued_without_analysis, retried, fallback or stopped.
- statusinteger | null
  Upstream HTTP status, when known.
- messagestring
  Human-readable summary of what failed and what happened next.
created_atinteger
Unix time in milliseconds.
completed_atinteger | null
When the generation reached a terminal state.

Retrieve a generation

GET/v1/generations/{id}

Scope: readReturns 200

Current state. Poll every 3–5 s for images and 10–15 s for videos, or use webhooks.

Path parameters

idstringrequired
Generation ID.

Request

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

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

Response · 200

Response

{
  "id": "gen_7f3c9a1e2b4d4c8f9a0b1c2d3e4f5a6b",
  "object": "generation",
  "type": "image",
  "model": "orior-image",
  "status": "completed",
  "credits": 2,
  "refunded_credits": 0,
  "result": {
    "url": "https://storage.googleapis.com/…/generated-images/…/3kf9.webp",
    "thumbnail_url": "https://storage.googleapis.com/…/3kf9_thumb.webp"
  },
  "error": null,
  "request": {
    "prompt": "A barista smiling behind a latte, morning light",
    "character_id": null,
    "product_id": null,
    "aspect_ratio": "9:16",
    "resolution": "2K",
    "edit": false,
    "has_scene_image": false,
    "reference_images": 0
  },
  "timeline": [],
  "created_at": 1758620000000,
  "completed_at": 1758620031000
}

List generations

GET/v1/generations

Scope: readReturns 200

Newest first. Cursor-paginated.

Query parameters

typestring
image or video.
statusstring
queued · processing · completed · failed · cancelled
limitintegerdefault: 20
1–100.
cursorstring
next_cursor from the previous page.

Request

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

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

Response · 200

Response

{
  "data": [
    {
      "id": "gen_7f3c9a1e2b4d4c8f9a0b1c2d3e4f5a6b",
      "object": "generation",
      "type": "image",
      "model": "orior-image",
      "status": "completed",
      "credits": 2,
      "refunded_credits": 0,
      "result": {
        "url": "https://storage.googleapis.com/…/generated-images/…/3kf9.webp",
        "thumbnail_url": "https://storage.googleapis.com/…/3kf9_thumb.webp"
      },
      "error": null,
      "request": {
        "prompt": "A barista smiling behind a latte, morning light",
        "character_id": null,
        "product_id": null,
        "aspect_ratio": "9:16",
        "resolution": "2K",
        "edit": false,
        "has_scene_image": false,
        "reference_images": 0
      },
      "timeline": [],
      "created_at": 1758620000000,
      "completed_at": 1758620031000
    }
  ],
  "next_cursor": "gen_7f3c9a1e2b4d4c8f9a0b1c2d3e4f5a6b"
}

Cancel a generation

POST/v1/generations/{id}/cancel

Scope: generateIdempotency-Key requiredReturns 200

Only while queued. Refunds the full price.

Path parameters

idstringrequired
Generation ID.

Errors

Code	When
`CONFLICT`	Already processing or finished.

Request

curl -X POST https://api.oriorai.com/v1/generations/gen_7f3c9a1e2b4d4c8f9a0b1c2d3e4f5a6b/cancel \
  -H "Authorization: Bearer $ORIOR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

const response = await fetch('https://api.oriorai.com/v1/generations/gen_7f3c9a1e2b4d4c8f9a0b1c2d3e4f5a6b/cancel', {
  method: 'POST',
  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.post(
    "https://api.oriorai.com/v1/generations/gen_7f3c9a1e2b4d4c8f9a0b1c2d3e4f5a6b/cancel",
    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": "gen_7f3c9a1e2b4d4c8f9a0b1c2d3e4f5a6b",
  "object": "generation",
  "type": "image",
  "model": "orior-image",
  "status": "cancelled",
  "credits": 2,
  "refunded_credits": 2,
  "result": null,
  "error": {
    "code": "CANCELLED",
    "message": "The generation was cancelled."
  },
  "request": {
    "prompt": "A barista smiling behind a latte, morning light",
    "character_id": null,
    "product_id": null,
    "aspect_ratio": "9:16",
    "resolution": "2K",
    "edit": false,
    "has_scene_image": false,
    "reference_images": 0
  },
  "timeline": [],
  "created_at": 1758620000000,
  "completed_at": 1758620031000
}

Delete a generation

DELETE/v1/generations/{id}

Scope: generateIdempotency-Key requiredReturns 200

Permanently deletes the output files and the record, including from the Orior library. Credits are not affected. Only finished generations can be deleted.

Path parameters

idstringrequired
Generation ID.

Errors

Code	When
`CONFLICT`	Still queued or processing.

Request

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

const response = await fetch('https://api.oriorai.com/v1/generations/gen_7f3c9a1e2b4d4c8f9a0b1c2d3e4f5a6b', {
  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/generations/gen_7f3c9a1e2b4d4c8f9a0b1c2d3e4f5a6b",
    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": "gen_7f3c9a1e2b4d4c8f9a0b1c2d3e4f5a6b",
  "object": "generation",
  "deleted": true
}