Job

Schema reference for JobCreateRequest, JobResponse, and JobDetailResponse objects in the Clipzy ML Engine API.

JobCreateRequest

Parameters for creating a new processing job. Sent as a JSON body to POST /api/v1/jobs.

video_id · string · required

The video_id returned when you uploaded the source video. See Upload a video.

template_video_id · string

The video_id of a previously uploaded video to use as a style template. The engine extracts style parameters from this video and applies them to the source during processing.

config · object

Optional processing configuration.

Show properties

quality · string · default: "medium"

Output quality preset. One of "low", "medium", or "high". Higher quality increases processing time and resource usage.

webhook_url · string

A URL the engine will POST to when the job reaches a terminal state (completed, failed, or cancelled). The request body uses the standard response envelope with the JobDetailResponse as data.

---

JobResponse

Returned by POST /api/v1/jobs and GET /api/v1/jobs/{job_id}. Also included as array items in the paginated list response from GET /api/v1/jobs.

job_id · string · required

Unique identifier for the job.

video_id · string · required

ID of the source video being processed.

status · string · required

Current job lifecycle status. One of:

Value	Description
queued	Accepted and waiting for a worker.
processing	Actively being processed.
completed	Finished successfully.
failed	Encountered an unrecoverable error.
cancelled	Cancelled before completion.

progress_percent · integer · required

Completion percentage from 0 to 100.

current_stage · string

Active pipeline stage when status is "processing". null at all other times. Possible values:

Value	Description
video_analysis	Analyzing visual content.
audio_analysis	Analyzing audio characteristics.
motion_analysis	Detecting motion and camera movement.
style_extraction	Extracting style from the template video.
style_application	Applying extracted style to the source.
rendering	Encoding the output file.

created_at · string · required

ISO 8601 timestamp when the job was created.

updated_at · string · required

ISO 8601 timestamp of the most recent status change.

started_at · string

ISO 8601 timestamp when processing began. null if the job has not yet started.

completed_at · string

ISO 8601 timestamp when the job reached a terminal state. null if the job has not yet completed.

template_video_id · string

ID of the template video, if one was specified at creation time. null otherwise.

---

JobDetailResponse

Extends JobResponse with full result data. Returned by GET /api/v1/jobs/{job_id}/result.

Includes all fields from JobResponse above, plus:

style_json · object

The StyleJSON object extracted during processing. null if the job has not completed or if extraction failed. See the StyleJSON schema for the full field reference.

output_video_url · string

URL of the processed output video. null if the job has not completed successfully.

error · object

Failure details when status is "failed". null for all other statuses.

Show properties

stage · string

The pipeline stage where the failure occurred.

error_message · string

Human-readable description of the failure reason.

timestamp · string

ISO 8601 timestamp when the failure occurred.

processing_time_seconds · float

Total elapsed time for the processing run in seconds. null if the job has not completed.