Core concepts

Generations

Every image and video request becomes a generation: an asynchronous job with a status, a price, a result and a record of what happened along the way.

Lifecycle

Status	Meaning	Terminal
`queued`	Accepted and paid; waiting for capacity.	No
`processing`	Analysis, prompt writing and generation are running.	No
`completed`	`result.url` is ready.	Yes
`failed`	Could not be produced; credits refunded; see `error` and `timeline`.	Yes
`cancelled`	Cancelled while queued; credits refunded.	Yes

Typical durations: images 20–60 seconds, videos 1–6 minutes depending on model and length. Generations that cannot finish within 30 minutes fail with TIMEOUT.

Waiting for results

Webhooks (recommended): subscribe to generation.completed and generation.failed. The payload is the full generation. See Webhooks.
Polling: GET /generations/{id} every 3–5 s for images, 10–15 s for videos. Polling counts towards the rate limit.
Listing: GET /generations?status=processing to reconcile after a restart.

Orior’s pipeline recovers from many upstream problems on its own — retrying another account, switching to a fallback model, or continuing without an optional analysis. Each such event is recorded in timeline, in order. A completed generation with timeline entries succeeded after recovering; a failed one shows where it stopped.

stage	Step
`scene_analysis`	Reading the scene image (pose, framing, lighting).
`character_analysis`	Reading the character’s appearance.
`prompt_merge`	Combining analyses and your prompt into the final prompt.
`text_model`	Other language-model calls.
`image_generation`	Generating the image or the video’s first frame.
`video_generation`	Generating the video.
`storage`	Saving the result.
`queue`	The job as a whole (e.g. could not start).

resolution	What happened next
`retried`	The same step was retried on another account.
`fallback`	A fallback model or method was used.
`continued_without_analysis`	An optional analysis was skipped; the generation continued.
`stopped`	This attempt stopped (the generation fails unless a later step recovers).

Failed generation with a timeline

{
  "id": "gen_7f3c9a1e2b4d4c8f9a0b1c2d3e4f5a6b",
  "object": "generation",
  "type": "image",
  "model": "orior-image",
  "status": "failed",
  "credits": 2,
  "refunded_credits": 2,
  "result": null,
  "error": {
    "code": "PROVIDER_ERROR",
    "message": "The provider could not generate this request."
  },
  "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": [
    {
      "at": 1758620004000,
      "stage": "scene_analysis",
      "resolution": "fallback",
      "status": 503,
      "message": "The model returned HTTP 503; continued with a fallback."
    },
    {
      "at": 1758620029000,
      "stage": "image_generation",
      "resolution": "stopped",
      "status": 500,
      "message": "The model returned HTTP 500; this attempt stopped."
    }
  ],
  "created_at": 1758620000000,
  "completed_at": 1758620030000
}

Failures and refunds

When a generation fails, its full price is refunded automatically and shown in refunded_credits. error.code tells you why:

error.code	Meaning	Retry?
`CONTENT_BLOCKED`	The model declined the content.	Change the prompt or media.
`PROVIDER_ERROR`	Upstream models failed after all recoveries.	Yes, later.
`TIMEOUT`	Did not finish in time.	Yes.
`RATE_LIMIT`	Upstream capacity exhausted.	Yes, after a pause.
`VALIDATION_ERROR`	An input could not be used (e.g. unreadable image).	Fix the input.
`INSUFFICIENT_CREDITS`	Balance changed before the job started.	Top up.
`UNKNOWN`	Unclassified failure.	Yes; contact support if it repeats.

Retrying a failed generation is a new request: use a new Idempotency-Key (the old key would replay the original 202).

Cancelling

POST /generations/{id}/cancel works while the generation is queued and refunds it fully. Once processing, work has been paid to providers and cannot be cancelled (409 CONFLICT).

Results and retention

result.url is permanent and publicly readable by anyone with the URL; don’t treat it as secret.
Outputs also appear in the account’s Orior library, like app creations.
DELETE /generations/{id} removes the files and the record permanently. Credits are unaffected.
Generation records are kept until deleted; inputs follow media retention.