Jobs

Create, monitor, and retrieve results for Clipzy ML Engine processing jobs.

A job represents a single video processing run. Create a job with an uploaded video_id, poll its status, and retrieve the result once it reaches the completed state.

Job statuses

Status	Description
queued	Job accepted and waiting for a worker.
processing	Actively being processed.
completed	Processing finished successfully.
failed	Processing encountered an unrecoverable error.
cancelled	Job was cancelled before completion.

Processing stages

While a job has status: "processing", the current_stage field reflects the active pipeline step:

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

---

POST /api/v1/jobs

Create a new processing job for an uploaded video.

Request body

video_id · string · required

The video_id returned when you uploaded the source video.

template_video_id · string

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

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.

webhook_url · string

A URL the engine will POST to when the job reaches a terminal state (completed, failed, or cancelled).

Response fields

success · boolean · required

true when the job was created successfully.

message · string · required

Human-readable confirmation.

data · object · required

A JobResponse object.

Hide properties

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 status. One of queued, processing, completed, failed, or cancelled.

progress_percent · integer · required

Completion percentage from 0 to 100.

current_stage · string

Active pipeline stage when status is processing. null otherwise. See the stage table above for possible values.

created_at · string · required

ISO 8601 timestamp when the job was created.

updated_at · string · required

ISO 8601 timestamp of the most recent status update.

started_at · string

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

completed_at · string

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

template_video_id · string

ID of the template video, if one was provided. null otherwise.

Example request

curl --request POST \
  --url http://{host}/api/v1/jobs \
  --header "Content-Type: application/json" \
  --data '{
    "video_id": "vid_abc123",
    "template_video_id": "vid_template456",
    "config": { "quality": "high" },
    "webhook_url": "https://example.com/webhooks/clipzy"
  }'

Example response

{
  "success": true,
  "message": "Job created successfully",
  "data": {
    "job_id": "job_xyz789",
    "video_id": "vid_abc123",
    "status": "queued",
    "progress_percent": 0,
    "current_stage": null,
    "created_at": "2024-04-05T10:31:00Z",
    "updated_at": "2024-04-05T10:31:00Z",
    "started_at": null,
    "completed_at": null,
    "template_video_id": "vid_template456"
  }
}

---

GET /api/v1/jobs/{job_id}

Retrieve the current status of a job.

Path parameters

job_id · string · required

The job_id returned when the job was created.

Response fields

Returns the standard response envelope with a JobResponse object as data. See the field descriptions under POST /api/v1/jobs above.

Example request

curl --request GET \
  --url http://{host}/api/v1/jobs/job_xyz789

Example response

{
  "success": true,
  "message": "Job retrieved successfully",
  "data": {
    "job_id": "job_xyz789",
    "video_id": "vid_abc123",
    "status": "processing",
    "progress_percent": 45,
    "current_stage": "style_extraction",
    "created_at": "2024-04-05T10:31:00Z",
    "updated_at": "2024-04-05T10:32:15Z",
    "started_at": "2024-04-05T10:31:10Z",
    "completed_at": null,
    "template_video_id": "vid_template456"
  }
}

---

GET /api/v1/jobs/{job_id}/result

Retrieve the full result of a completed job, including the extracted StyleJSON and the output video URL.

This endpoint returns meaningful output only when the job status is "completed". For jobs in other states, style_json and output_video_url will be null.

Path parameters

job_id · string · required

The job_id of the completed job.

Response fields

Returns a JobDetailResponse, which extends JobResponse with the following additional fields:

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

Populated when the job status is "failed". null otherwise.

Show properties

stage · string

The pipeline stage where the failure occurred.

error_message · string

Human-readable description of the failure.

timestamp · string

ISO 8601 timestamp when the failure occurred.

processing_time_seconds · float

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

Example request

curl --request GET \
  --url http://{host}/api/v1/jobs/job_xyz789/result

Example response

{
  "success": true,
  "message": "Job result retrieved successfully",
  "data": {
    "job_id": "job_xyz789",
    "video_id": "vid_abc123",
    "status": "completed",
    "progress_percent": 100,
    "current_stage": null,
    "created_at": "2024-04-05T10:31:00Z",
    "updated_at": "2024-04-05T10:35:42Z",
    "started_at": "2024-04-05T10:31:10Z",
    "completed_at": "2024-04-05T10:35:42Z",
    "template_video_id": "vid_template456",
    "style_json": {
      "version": "1.0",
      "aspect_ratio": "16:9",
      "frame_rate": 30,
      "cut_frequency": 3.5,
      "motion_intensity": 65,
      "zoom_usage": 30,
      "use_subtitles": false,
      "tempo_bpm": 120.0,
      "music_genre": "pop",
      "created_at": "2024-04-05T10:35:40Z",
      "source_duration_seconds": 60.0,
      "extraction_confidence": 0.92
    },
    "output_video_url": "https://storage.example.com/output/job_xyz789.mp4",
    "error": null,
    "processing_time_seconds": 272.4
  }
}

---

GET /api/v1/jobs

List jobs with pagination.

Query parameters

page · integer · default: "1"

Page number to retrieve, starting at 1.

page_size · integer · default: "10"

Number of jobs to return per page.

Response fields

data · object · required

Hide properties

jobs · JobResponse[] · required

Array of JobResponse objects for the current page. See field descriptions under POST /api/v1/jobs.

total · integer · required

Total number of jobs across all pages.

page · integer · required

The current page number.

page_size · integer · required

The number of items returned per page.

Example request

curl --request GET \
  --url "http://{host}/api/v1/jobs?page=1&page_size=10"

Example response

{
  "success": true,
  "message": "Jobs retrieved successfully",
  "data": {
    "jobs": [
      {
        "job_id": "job_xyz789",
        "video_id": "vid_abc123",
        "status": "completed",
        "progress_percent": 100,
        "current_stage": null,
        "created_at": "2024-04-05T10:31:00Z",
        "updated_at": "2024-04-05T10:35:42Z",
        "started_at": "2024-04-05T10:31:10Z",
        "completed_at": "2024-04-05T10:35:42Z",
        "template_video_id": "vid_template456"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 10
  }
}