JARAI Developers

Production Lifecycle

A production moves through a defined set of states from creation to completion. Understanding these states helps you build robust integrations.

Triggering a Production

Create a new production by posting to the account’s productions endpoint:

curl -X POST https://api.jarai.studio/v1/accounts/{accountId}/productions \
-H "X-API-Key: jarai_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
  "topic": "Weekly market analysis for tech sector",
  "languageId": "LANGUAGE_UUID",
  "countryId": "COUNTRY_UUID",
  "avatarId": "AVATAR_UUID",
  "projectTypeSlug": "social-video-30s",
  "metadataMD": "Focus on AI chip stocks and cloud infrastructure trends."
}'

Request Fields

Field Required Type Description
topic Yes string (1–500 chars) The subject matter for the production.
languageId Yes UUID Language for the production content.
countryId Yes UUID Target country/locale.
avatarId Yes UUID The AI avatar to use for the production.
projectTypeSlug No string Project type identifier. Defaults to the account’s default.
metadataMD No string (max 4,096 chars) Additional Markdown context passed to the AI pipeline.

Production States

Productions move through the following states:

Status Type Description
Queued Transient Production submitted, waiting to be picked up by the pipeline.
Producing Transient Pipeline is actively processing steps (narrative, visuals, audio, video).
AwaitingApproval Transient All pipeline steps complete. Deliverables available for review. Waiting for operator release.
Distributing Transient Content is being published to connected platforms.
Published Terminal All platforms published successfully.
Failed Terminal Production failed. Check errorCode and errorMessage for details.
Cancelled Terminal Production was cancelled by the partner or operator.

Terminal states are final — no further transitions occur. Transient states will eventually transition to a terminal state.

Production Expiry

API-triggered productions include an expiresAt timestamp. If the production is not picked up by the pipeline within this window (default: 10 minutes), it transitions to Failed with error code PRODUCTION_EXPIRED. This is safe to retry immediately.

Polling for Status

The status endpoint is account-scoped: use the accountId you triggered with and the productionId you got back — or just follow the Location header from the trigger response.

curl https://api.jarai.studio/v1/accounts/{accountId}/productions/{productionId} \
-H "X-API-Key: jarai_your_api_key_here"
Status Interval Reason
Queued 10 seconds Productions are picked up quickly; you want to know when processing starts.
Producing 30 seconds Pipeline steps take minutes each; frequent polling adds no value.
AwaitingApproval 60 seconds Waiting for operator action; no urgency.
Distributing 30 seconds Platform publishing typically completes within minutes.

For real-time updates without polling overhead, use webhooks instead.

Status Response Shape

{
  "productionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "accountId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "Producing",
  "createdAt": "2026-04-03T10:30:00Z",
  "updatedAt": "2026-04-03T10:35:22Z",
  "errorCode": null,
  "errorMessage": null,
  "stepsComplete": 5,
  "currentStep": "Image Acquisition",
  "platforms": [],
  "expiresAt": "2026-04-03T10:40:00Z"
}

Listing Productions

Retrieve all productions for an account with cursor-based pagination:

# First page (20 results by default)
curl "https://api.jarai.studio/v1/accounts/{accountId}/productions" \
-H "X-API-Key: jarai_your_api_key_here"

# Next page using cursor
curl "https://api.jarai.studio/v1/accounts/{accountId}/productions?after={lastProductionId}" \
-H "X-API-Key: jarai_your_api_key_here"

Results are ordered by createdAt descending. Default page size is 20 (maximum: 100).

Cancelling a Production

Cancel a production that has not yet reached a terminal state:

curl -X DELETE https://api.jarai.studio/v1/productions/{productionId} \
-H "X-API-Key: jarai_your_api_key_here"

Cancellation is idempotent — cancelling an already-cancelled production returns 204 again. Cancelling a Published or Failed production returns 409 ALREADY_TERMINAL. Only API-triggered productions can be cancelled by partners; manual and autonomous productions return 403 CANCELLATION_NOT_PERMITTED.

Production Error Codes

When a production reaches Failed status, the errorCode field indicates what went wrong:

Error Code Meaning Retry?
PROVIDER_UNAVAILABLE AI provider returned 5xx or was unreachable Yes — safe to retry
PROVIDER_QUOTA_EXHAUSTED AI model’s monthly token budget exhausted No — wait for next billing period
PRODUCTION_EXPIRED Not picked up within the expiry window Yes — retry immediately
COMPLIANCE_GATE_FAILED Content failed a compliance guardrail No — adjust topic or configuration
BUDGET_EXHAUSTED Account’s monthly AI spend limit reached No — wait for next month or top up budget
INVALID_CONFIGURATION Account configuration invalid for this production type No — fix configuration first
CONTENT_SENSITIVITY_SUPPRESSED Sensitivity rule blocked the production No — contact operator
INTERNAL_ERROR Unexpected system error Yes — retry once after 5 minutes

Next Steps