API reference · v1.0.0

Lightplay API

REST and JSON over HTTPS. Upload a scene and a portrait, create a job, follow its progress, review, and download the result.

Base URL

https://YOUR-HOST

Authentication

Every /v1 call needs Authorization: Bearer <token>. The token is a signed JWT that your identity issuer provides. The service checks the signature, issuer, audience, expiry, subject and tenant. Assets and jobs belong to the tenant and subject of the token.

Conventions

JSON requests reject unknown fields. POST endpoints that create jobs accept an optional Idempotency-Key header. A repeated key with the same body returns the same job. Errors return {"detail": ...}.

Endpoints

GET/health

Liveness check. No authentication.

Response 200

statusstring"ok" when the service is up.

GET/v1/capabilities

Supported edits, policies and input limits for this deployment.

Response 200

editsstring[]Supported edits. Currently ["face_replace"].
max_actorsintegerActors replaced per job. Currently 1.
hair_policies, deliveriesstring[]"preserve_source" and "draft".
input_review_required, output_review_requiredbooleanBoth reviews are required.
max_upload_bytesintegerUpload size limit.
limitsobjectDuration, size, frame rate and face size limits for inputs.
unsupportedstring[]Edits that the service rejects, such as hair or body replacement.

Errors

  • 401Missing or invalid bearer token.

POST/v1/assets

Upload a scene video (role source) or a portrait (role reference).

Request

fileform · string · requiredThe media file.
roleform · "source" | "reference" · requiredsource for the scene video, reference for the portrait.

Response 201

idstringAsset ID for later calls.
rolestring"source" or "reference".
media_typestringDetected media type.
bytes, sha256integer, stringSize and content hash.
created_atstringRFC 3339 timestamp.

Errors

  • 401Missing or invalid bearer token.
  • 413File exceeds the upload limit.
  • 415Unsupported media type, or a reference that is not a still image.
  • 422Invalid input. detail holds a message, or {code, message}.

GET/v1/assets/{asset_id}

Metadata of an asset that you own.

Response 200

id, role, media_type, bytes, sha256, created_atSame fields as the upload response.

Errors

  • 401Missing or invalid bearer token.
  • 404Asset not found or not owned by the caller.
  • 422Invalid input. detail holds a message, or {code, message}.

GET/v1/assets/{asset_id}/content

Download the asset bytes, including job artifacts such as the prepared guide.

Response 200

(binary)The file, with its media type.

Errors

  • 401Missing or invalid bearer token.
  • 404Asset not found or not owned by the caller.
  • 422Invalid input. detail holds a message, or {code, message}.

GET/v1/assets/{asset_id}/faces

Detected faces in a portrait or in the first frame of a video.

Response 200

faces[].face_indexintegerIndex to pass as face_index.
faces[].bboxobjectNormalized x, y, width, height.
sampleobjectSampled frame: kind, frame_index, time_seconds, width, height.
requires_selectionbooleanTrue when more than one face is visible.

Errors

  • 401Missing or invalid bearer token.
  • 404Asset not found.
  • 503Face detection is temporarily unavailable.
  • 422Invalid input. detail holds a message, or {code, message}.

POST/v1/faces/normalize

Cut a portrait to a transparent face oval. Finishes without review.

Request

Idempotency-Keyheader · string · optionalOptional. Repeat the same key to retry safely.
asset_idbody · string · required · 1–64 charsUploaded portrait.
face_indexbody · integer · optional · ≥ 0Face to use, from the faces endpoint. Required when several faces exist.

Response 202

(job)objectJob object. See the job status response.

Errors

  • 401Missing or invalid bearer token.
  • 409Idempotency key reused with a different request.
  • 422Invalid input. detail holds a message, or {code, message}.

POST/v1/jobs

Create a face replacement job. It pauses for input review before generation.

Request

Idempotency-Keyheader · string · optionalOptional. Repeat the same key to retry safely.
source_asset_idbody · string · required · 1–64 charsUploaded scene video.
reference_asset_idbody · string · required · 1–64 charsUploaded portrait.
targetbody · object · optionalActor to replace: {face_index}. Required when several faces exist.
hair_policybody · "preserve_source" · optional · default "preserve_source"Keep the hair from the scene.
deliverybody · "draft" · optional · default "draft"Output tier.
authorizationbody · object · required{accepted: true} confirms permission to process the video and the likeness.

Response 202

(job)objectJob object. See the job status response.

Errors

  • 401Missing or invalid bearer token.
  • 409Idempotency key reused with a different request.
  • 422Invalid input. detail holds a message, or {code, message}.

GET/v1/jobs/{job_id}

Current job status.

Response 200

id, kindstringJob ID and job kind.
statestringqueued, running, awaiting_input_review, awaiting_output_review, succeeded, failed, cancelled, and transient states.
stagestringCurrent processing stage.
progressobjectCompleted and total work units.
action_requiredobjectNext client action, with the review fingerprint when a review is due.
artifactsobject[]Asset IDs for prepared inputs and drafts to inspect.
technical_completed, quality_acceptedbooleanTechnical checks passed, output review accepted.
result_asset_idstringFinal asset after acceptance.
errorobjectSafe error code and message on failure.

Errors

  • 401Missing or invalid bearer token.
  • 404Job not found.
  • 422Invalid input. detail holds a message, or {code, message}.

GET/v1/jobs/{job_id}/events

Ordered progress events after a cursor.

Request

afterquery · integer · optional · ≥ 0, default 0Event cursor. Default 0.

Response 200

events[]object[]sequence, state, stage, message, progress, at.
cursorintegerPass as after to fetch newer events.

Errors

  • 401Missing or invalid bearer token.
  • 404Job not found.
  • 422Invalid input. detail holds a message, or {code, message}.

POST/v1/jobs/{job_id}/review

Accept or reject the inputs or the draft that you inspected.

Request

decisionbody · "accept" | "reject" · requiredaccept or reject.
fingerprintbody · string · required · 1–256 charsFingerprint from action_required. Must match the reviewed version.
notebody · string · optional · 0–2000 charsOptional review note.

Response 200

(job)objectUpdated job. Input acceptance starts generation.

Errors

  • 401Missing or invalid bearer token.
  • 409Job is not waiting for review, fingerprint changed, or technical checks failed.
  • 422Invalid input. detail holds a message, or {code, message}.

POST/v1/jobs/{job_id}/cancel

Cancel a job. A cancelled job never publishes a result.

Response 200

(job)objectUpdated job.

Errors

  • 401Missing or invalid bearer token.
  • 409An accepted result cannot be cancelled.
  • 422Invalid input. detail holds a message, or {code, message}.

POST/v1/jobs/{job_id}/resume

Safely resume an interrupted job.

Response 202

(job)objectUpdated job.

Errors

  • 401Missing or invalid bearer token.
  • 409The job cannot resume, or its submission state is uncertain.
  • 422Invalid input. detail holds a message, or {code, message}.

GET/v1/jobs/{job_id}/result

Download the accepted result.

Response 200

(binary)MP4 video for a replacement job, PNG for a normalization job.

Errors

  • 401Missing or invalid bearer token.
  • 409The job has no accepted result.
  • 422Invalid input. detail holds a message, or {code, message}.