API reference

Images

Creates an image generation. Combine a prompt with a saved character (identity), a scene image (composition, pose, setting), a product and tagged references. The pipeline analyses the inputs, writes the final prompt and generates with Google’s image model, falling back to another provider automatically when needed.

The request returns 202 immediately with a queued generation. Poll it or listen for generation.completed.

Create an image

POST/v1/images

Scope: generateIdempotency-Key requiredReturns 202

At least one of prompt, character_id, character_image, scene_image or product_id is required. Price: 2 credits (1K/2K) or 3 credits (4K).

Body

promptstring
What to create, up to 5,000 characters. Screened before any charge.
character_idstring
A character to preserve the identity of.
character_imagestring (media)
A face to use without saving a character. Upload ID (upl_…), public https:// URL, or base64 data URL.
scene_imagestring (media)
Reference for pose, framing, setting and lighting. Upload ID (upl_…), public https:// URL, or base64 data URL.
product_idstring
A product to place in the image, preserved exactly.
reference_imagesarray
Extra tagged references to mention in the prompt (e.g. “wearing the jacket from @ref1”). Up to 6.
- tagstring
  Tag used in the prompt, @ + up to 20 letters/digits/underscores. Defaults to @ref1, @ref2, …
- imagestring (media)required
  Upload ID (upl_…), public https:// URL, or base64 data URL.
aspect_ratiostringdefault: 9:16
1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9
resolutionstringdefault: 1K
1K, 2K or 4K.
editbooleandefault: false
Edit scene_image directly (no character composition). Ignored when character_id is set.

Errors

Code	When
`CONTENT_BLOCKED`	The prompt is not allowed. Nothing is charged.
`NOT_FOUND`	character_id or product_id does not belong to the account.
`INSUFFICIENT_CREDITS`	Balance below the price (`details.required`, `details.available`).
`SPEND_CAP_REACHED`	The key’s monthly cap would be exceeded.
`CONCURRENCY_LIMIT`	Too many API jobs running; retry after `Retry-After`.

Request

curl -X POST https://api.oriorai.com/v1/images \
  -H "Authorization: Bearer $ORIOR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "She is holding the serum next to her face, soft window light",
  "character_id": "Qx8p2LmN4vRt",
  "product_id": "Pm3kT9aQ",
  "aspect_ratio": "4:5",
  "resolution": "2K"
}'

const response = await fetch('https://api.oriorai.com/v1/images', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ORIOR_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "prompt": "She is holding the serum next to her face, soft window light",
    "character_id": "Qx8p2LmN4vRt",
    "product_id": "Pm3kT9aQ",
    "aspect_ratio": "4:5",
    "resolution": "2K"
  }),
})
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/images",
    headers={"Authorization": f"Bearer {os.environ['ORIOR_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "prompt": "She is holding the serum next to her face, soft window light",
        "character_id": "Qx8p2LmN4vRt",
        "product_id": "Pm3kT9aQ",
        "aspect_ratio": "4:5",
        "resolution": "2K",
    },
    timeout=60,
)
response.raise_for_status()
data = response.json()

Response · 202

Response

{
  "id": "gen_7f3c9a1e2b4d4c8f9a0b1c2d3e4f5a6b",
  "object": "generation",
  "type": "image",
  "model": "orior-image",
  "status": "queued",
  "credits": 2,
  "refunded_credits": 0,
  "result": null,
  "error": null,
  "request": {
    "prompt": "A barista smiling behind a latte, morning light",
    "character_id": "Qx8p2LmN4vRt",
    "product_id": "Pm3kT9aQ",
    "aspect_ratio": "4:5",
    "resolution": "2K",
    "edit": false,
    "has_scene_image": false,
    "reference_images": 0
  },
  "timeline": [],
  "created_at": 1758620000000,
  "completed_at": null
}