Skip to Content
API referenceScenes

Scenes

Scenes are the Jetwild product itself — the tiered pipeline (Basic → Premium → Ultimate) as an API. Submit a master to POST /v1/scenes and get back titles, tags, model ID, chapters, quality scores, and marketing cuts; then read, curate, and export it. Reads require the scenes:read scope; writes require scenes:write. Endpoints return the Scene object.

Scene Intelligence = POST /v1/scenes

“Scene Intelligence” is the product name for the pipeline behind POST /v1/scenes. Depth is gated by tier: basic (scene intelligence), premium (marketing cuts), ultimate (distribution + Shield). For a single signal against your own content instead of the full pipeline, use the standalone Metadata API.

List scenes in the workspace, filtered and sorted.

scenes:read
GET/v1/scenes
Parameters
page
integer
Page number (default 1).
limit
integer
Items per page (default 25).
status
"QUEUED" | "PROCESSING" | "READY" | "FAILED"
Filter by pipeline status.
tier
"TIER_1" | "TIER_2" | "TIER_3"
Filter by tier.
site
string
Paysite id (Site.id); omit for the network rollup.
performer
string[]
Model slugs; OR within the array.
tag
string[]
Act tags; OR within the array.
from
string (ISO date)
Start of date range (inclusive).
to
string (ISO date)
End of date range (inclusive).
dateColumn
"createdAt" | "processedAt"
Which column from/to applies to (default createdAt).
sort
string
`<field>:<asc|desc>`; fields: createdAt, processedAt, qualityScore, durationS.
Response fields
items
Scene[]
The page of scenes (see the Scene object).
total
integer
Total matching scenes.
page
integer
Current page.
limit
integer
Items per page.
hasMore
boolean
True if more pages exist.
GET/v1/scenes
Request
GET /v1/scenes?status=READY&limit=2
Response
Press Run request to see the response

Fetch one scene and its generated metadata.

scenes:read
GET/v1/scenes/{id}
Parameters
id
string · required
Scene ID (or titleSlug / sceneName).

Returns the full Scene object — see the Scene object.

GET/v1/scenes/{id}
Request
GET /v1/scenes/sc_8841
Response
Press Run request to see the response

Create a scene and get a presigned upload URL for the master.

scenes:write
POST/v1/scenes
Console roles: OWNER, DIRECTOR
Request body
filename
string · required
Original filename of the video.
tier
"TIER_1" | "TIER_2" | "TIER_3" · required
Processing tier.
sceneName
string
URL-safe slug / storage folder; auto-derived from filename if omitted.
siteId
string
Paysite (Site.id); falls back to the workspace primary site.
sizeBytes
integer
File size in bytes.
contentType
string
MIME type, e.g. video/mp4.
models
string[]
Performer name hints (max 25).
Response fields
scene
Scene
The created scene (see the Scene object).
uploadUrl
string
Presigned URL to upload the master to.
uploadMethod
"PUT" | "POST"
HTTP method for the upload.
driver
"r2" | "local"
Storage backend in use.
POST/v1/scenes
Request
POST /v1/scenes
{
  "filename": "midnight-heat.mp4",
  "tier": "TIER_2",
  "siteId": "site_spizoo"
}
Response
Press Create scene to see the response

Create a scene from a public URL — the worker fetches the file (no client upload).

scenes:write
POST/v1/scenes/cloud-url
Console roles: OWNER, DIRECTOR
Request body
filename
string · required
Filename for the source video.
tier
"TIER_1" | "TIER_2" | "TIER_3" · required
Processing tier.
sourceUrl
string · required
Public http/https URL the worker fetches.
models
string[]
Performer name hints (max 25).

Same shape as Create a scene.

Re-queue a scene for processing.

scenes:write
POST/v1/scenes/{id}/reprocess
Console roles: OWNER, DIRECTOR
Parameters
id
string · required
Scene ID.
Request body
steeringNote
string
Optional operator note captured on the audit row (max 2000).

Returns the updated Scene object.

Generate (or look up) a short LLM-derived scene title. Idempotent.

scenes:write
POST/v1/scenes/{id}/generate-title
Console roles: OWNER, DIRECTOR
Parameters
id
string · required
Scene ID.
force
string
Pass true / 1 to discard the cached title and regenerate.
Response fields
generatedTitle
string | null
The cached or newly generated title.

Regenerate one marketing blurb or the scene summary.

scenes:write
POST/v1/scenes/{id}/regenerate-section
Console roles: OWNER, DIRECTOR
Parameters
id
string · required
Scene ID.
Request body
section
"sfw_blurb" | "nsfw_blurb" | "scene_summary" · required
Which section to regenerate.
steeringNote
string
Steering directive injected into the prompt (max 2000).
tone
"brand_voice" | "punchy" | "editorial" | "playful"
Tone preset (brand_voice = default).

Returns the updated Scene object.

Upgrade a scene to a higher tier; debits the credit delta and reprocesses.

scenes:write
POST/v1/scenes/{id}/upgrade-tier
Console roles: OWNER, DIRECTOR
Parameters
id
string · required
Scene ID.
Request body
targetTier
"TIER_1" | "TIER_2" | "TIER_3" · required
Target tier (only TIER_2 buildable today).

Returns the updated Scene object.

Delete a scene.

scenes:write
DELETE/v1/scenes/{id}
Console roles: OWNER, DIRECTOR
Parameters
id
string · required
Scene ID.
Response fields
deleted
boolean
True if deleted.
id
string
The deleted scene ID.

Shallow-merge keys into the scene's metadata.

scenes:write
PATCH/v1/scenes/{id}/metadata
Console roles: OWNER, DIRECTOR
Parameters
id
string · required
Scene ID.
Request body
metadata
object · required
Key/value pairs merged into Scene.metadata.

Returns the updated Scene object.

Transition the operator catalog status (DRAFT → READY → SCHEDULED → LIVE → ARCHIVED).

scenes:write
PATCH/v1/scenes/{id}/catalog-status
Console roles: OWNER, DIRECTOR, MARKETING
Parameters
id
string · required
Scene ID.
Request body
to
"DRAFT" | "READY" | "SCHEDULED" | "LIVE" | "ARCHIVED" · required
Target catalog status.
note
string
Transition note (max 500).

Returns the updated Scene object.

Post an operator note on a scene.

scenes:write
POST/v1/scenes/{id}/notes
Parameters
id
string · required
Scene ID.
Request body
body
string · required
Note text (1–2000 chars).
Response fields
id
string
Note ID.
sceneId
string
Scene the note is on.
userId
string
Author user ID.
body
string
Note text.
createdAt
string (ISO)
Created timestamp.

Set a MARKETING / COMPLIANCE / OWNER approval; recomputes the scene's approvalState.

scenes:write
POST/v1/scenes/{id}/approvals/{role}
Parameters
id
string · required
Scene ID.
role
"MARKETING" | "COMPLIANCE" | "OWNER" · required
Approval role.
Request body
status
"APPROVED" | "BLOCKED" · required
Approval decision.
note
string
Approval note (max 500).
Response fields
id
string
Approval row ID.
role
string
The approval role.
status
"APPROVED" | "PENDING" | "BLOCKED"
Resulting status.
decidedBy
string | null
Approver user ID.
decidedAt
string (ISO) | null
Decision timestamp.

Acknowledge a Shield residual-risk bucket (auto-cleared-but-unverified frames), making the scene ship-eligible for that class.

scenes:write
POST/v1/scenes/{id}/shield/acknowledge
Console roles: OWNER, DIRECTOR
Parameters
id
string · required
Scene ID.
Request body
class
string · required
Detection class being acknowledged, e.g. "alcohol" (max 64).
frameIds
string[] · required
IDs of the unverified frames reviewed (1–500).
Response fields
id
string
Audit event ID.
action
string
"shield.acknowledge_residual".
detail
object
{ class, frameIds }.
createdAt
string (ISO)
Timestamp.
Not a verdict override — critical/flagged/§2257 still hard-block. This clears the residual review bucket only.

Cursor-paginated unified activity timeline (notes, status changes, regen, UI events).

scenes:read
GET/v1/scenes/{id}/activity
Parameters
id
string · required
Scene ID.
cursor
string
Cursor `<ISO>:<id>` from a previous page.
limit
integer
Items per page (1–200, default 50).
Response fields
items
object[]
Timeline entries (mixed types).
cursor
string | null
Next cursor.
hasMore
boolean
True if more pages exist.

Tier-aware deliverable pack — file list + signed download URLs.

scenes:read
GET/v1/scenes/{id}/pack
Parameters
id
string · required
Scene ID.
Response fields
tier
string
Scene tier.
files
object[]
{ name, url, available, pending, sizeBytes, mimeType }.

Generate a short-lived share URL for a scene (records a SHARE event).

scenes:write
POST/v1/scenes/{id}/share
Parameters
id
string · required
Scene ID.
Response fields
shareUrl
string
Short-lived shareable URL.
expiresAt
string (ISO)
Expiry timestamp.

Replace the scene's deliverable-menu JSON.

scenes:write
PATCH/v1/scenes/{id}/deliverable-menu
Console roles: OWNER, DIRECTOR
Parameters
id
string · required
Scene ID.
Request body
deliverableMenu
object · required
Full replacement deliverable menu.

Returns the updated Scene object.

List recent UI engagement events for a scene (max 200).

scenes:read
GET/v1/scenes/{id}/events
Parameters
id
string · required
Scene ID.
Response fields
id
string
Event ID.
eventType
"VIEW" | "PLAY" | "SHARE" | "DOWNLOAD"
Event type.
occurredAt
string (ISO)
When it happened.
metadata
object
Free-form event metadata.

Hard-delete up to 500 scenes; missing/cross-workspace IDs report in failed[].

scenes:write
POST/v1/scenes/bulk-delete
Console roles: OWNER, DIRECTOR
Request body
ids
string[] · required
Scene IDs (1–500).
Response fields
deleted
string[]
Deleted scene IDs.
failed
{ id, reason }[]
Per-ID failures.

Re-queue up to 50 scenes. Rate-limited 3/min.

scenes:write
POST/v1/scenes/bulk-reprocess
Console roles: OWNER, DIRECTOR
Request body
sceneIds
string[] · required
Scene IDs (1–50).
steeringNote
string
Note applied to every scene (max 2000).
Response fields
reprocessed
string[]
Requeued scene IDs.
failed
{ id, reason }[]
Per-ID failures.

Re-tier up to 100 scenes with atomic per-scene credit debit. Rate-limited 3/min.

scenes:write
POST/v1/scenes/bulk-retier
Console roles: OWNER, DIRECTOR
Request body
sceneIds
string[] · required
Scene IDs (1–100).
targetTier
"TIER_1" | "TIER_2" | "TIER_3" · required
Target tier (only TIER_2 buildable).
Response fields
retiered
string[]
Retiered scene IDs.
failed
{ id, reason }[]
Per-ID failures (e.g. INSUFFICIENT_CREDITS).
totalCreditsDebited
integer
Credits actually charged.

Export pipeline-output URLs for up to 100 READY scenes. Rate-limited 3/min.

scenes:read
POST/v1/scenes/bulk-export
Console roles: OWNER, DIRECTOR, MARKETING
Request body
sceneIds
string[] · required
Scene IDs (1–100).
Response fields
sceneId
string
Scene ID.
files
{ name, url, type }[]
Downloadable artifacts (when READY).
error
string
Reason when a scene isn't exportable.
Last updated on
ObjectsModels