Skip to main content
This guide walks you through a complete end-to-end flow: uploading a video, creating a job, checking its status, and fetching the final output.
Replace YOUR_TOKEN with your API credentials and https://your-api-host with your deployment’s base URL. See Authentication for details.
1

Upload a video

Send your video file to POST /api/v1/videos/upload as multipart form data.
curl -X POST https://your-api-host/api/v1/videos/upload \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@my_video.mp4" \
  -F "webhook_url=https://example.com/webhook"
The response includes a video_id you’ll use in the next step.
{
  "success": true,
  "message": "Video uploaded successfully",
  "data": {
    "video_id": "vid_abc123",
    "filename": "my_video.mp4",
    "file_size_bytes": 52428800,
    "metadata": {
      "width": 1920,
      "height": 1080,
      "duration_seconds": 60.0,
      "frame_rate": 30.0,
      "codec": "h264",
      "bitrate_kbps": 5000,
      "format": "mp4"
    },
    "uploaded_at": "2024-04-05T10:30:00Z",
    "storage_url": "file:///storage/vid_abc123/my_video.mp4"
  }
}
Pass a template_video_id in the form data to apply the style from a previously uploaded video to this one.
2

Create a processing job

Submit the video_id from the previous step to create a job.
curl -X POST https://your-api-host/api/v1/jobs \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "video_id": "vid_abc123",
    "config": { "quality": "high" },
    "webhook_url": "https://example.com/webhook"
  }'
The response confirms the job is queued and returns a job_id.
{
  "success": true,
  "message": "Job created",
  "data": {
    "job_id": "job_xyz789",
    "video_id": "vid_abc123",
    "status": "queued",
    "progress_percent": 0,
    "current_stage": null,
    "created_at": "2024-04-05T10:30:00Z",
    "updated_at": "2024-04-05T10:30:00Z"
  }
}
3

Poll job status

Check the job’s progress by calling GET /api/v1/jobs/{job_id}. Poll this endpoint until status is completed or failed.
curl https://your-api-host/api/v1/jobs/job_xyz789 \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "success": true,
  "message": "Job retrieved",
  "data": {
    "job_id": "job_xyz789",
    "video_id": "vid_abc123",
    "status": "processing",
    "progress_percent": 62,
    "current_stage": "style_application",
    "created_at": "2024-04-05T10:30:00Z",
    "updated_at": "2024-04-05T10:31:15Z"
  }
}
Possible statuses: queued → processing → completed (or failed / cancelled)Processing stages in order: video_analysis, audio_analysis, motion_analysis, style_extraction, style_application, rendering
If you registered a webhook_url, Clipzy will POST the final result to your endpoint when the job finishes—so you don’t need to poll continuously.
4

Get results

Once status is completed, retrieve the output from GET /api/v1/jobs/{job_id}/result.
curl https://your-api-host/api/v1/jobs/job_xyz789/result \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "success": true,
  "message": "Job result retrieved",
  "data": {
    "job_id": "job_xyz789",
    "status": "completed",
    "progress_percent": 100,
    "output_video_url": "file:///storage/job_xyz789/output.mp4",
    "processing_time_seconds": 900.0,
    "style_json": {
      "version": "1.0",
      "color_grade": {
        "temperature": 10,
        "tint": 5,
        "saturation": 20,
        "contrast": 15,
        "highlights": 10,
        "shadows": -5
      },
      "aspect_ratio": "16:9",
      "frame_rate": 30,
      "audio_style": {
        "normalization_level": 0.85,
        "compression_ratio": 4.0,
        "bass_boost": 20,
        "enhance_speech": true
      },
      "cut_frequency": 3.5,
      "motion_intensity": 65,
      "zoom_usage": 30,
      "primary_transition": {
        "type": "fade",
        "duration_ms": 300,
        "easing": "ease-in-out"
      },
      "detected_beats": [
        { "timestamp_ms": 0, "confidence": 0.95, "frequency": "bass" }
      ],
      "tempo_bpm": 120.0,
      "music_genre": "pop",
      "created_at": "2024-04-05T10:30:00Z",
      "source_duration_seconds": 60.0,
      "extraction_confidence": 0.92
    }
  }
}
Download your output video from output_video_url. The style_json field contains the extracted Style DNA, which you can reuse as a template for future jobs.

​
What’s next