pixamake

Documentation

Jobs

Create, follow, list and cancel cleaning jobs.

A job is one video being cleaned. Credits are reserved when the job is created and returned if it fails or is canceled.

Lifecycle

Status Meaning
queued Credits reserved, waiting for a processing slot
analyzing Reading the captions and the speech of the video
processing Frames are being rebuilt and checked
succeeded The clean video is ready in result.url
failed Processing did not complete; see error (credits returned)
canceled Stopped by you (credits returned)

While a job runs, stage tells what happens and progress goes from 0 to 1. Stages: queued, preparing, reading_text, downloading, masking, cleaning, verifying, assembling, finalizing, retrying.

Jobs of a workspace run in parallel up to the plan limit (2, 5 or 15). Extra jobs wait in the queue; higher plans are served first when the platform is busy.

Create a job

POST /v1/jobs

Field Type Description
upload_id string An upload created with POST /v1/uploads
video_url string Public URL of the video (instead of upload_id)
filename string Optional display name
texts string[] Optional: the exact texts shown on screen to erase. When given, the automatic reading step is skipped
metadata object Optional: up to 20 string keys and values, returned with the job and in webhooks

Send an Idempotency-Key header to retry safely: the same key returns the same job instead of creating a second one.

curl https://pixamake.ai/v1/jobs \
  -H "Authorization: Bearer $PIXAMAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0d6c1c5e-62f4-4f57-9c1c-4e6a7c1a2f10" \
  -d '{"upload_id": "up_7Qm2rT9vXk3LpZ8aWn4c", "metadata": {"campaign": "spring-sale"}}'

The job object

{
  "id": "job_3kT9xQ2vLm8RfZp1Wq7a",
  "object": "job",
  "status": "succeeded",
  "stage": null,
  "progress": 1,
  "source": "api",
  "input": { "filename": "ad.mp4", "duration_seconds": 30, "width": 1080, "height": 1920, "size_bytes": 4821331 },
  "credits": 75,
  "credits_refunded": false,
  "result": { "url": "https://...", "expires_at": "2026-10-04T14:12:00.000Z", "size_bytes": 5310877 },
  "error": null,
  "metadata": { "campaign": "spring-sale" },
  "created_at": "2026-10-04T13:05:41.120Z",
  "started_at": "2026-10-04T13:05:42.008Z",
  "finished_at": "2026-10-04T13:09:57.774Z"
}

result.url is a download link valid for one hour. Each GET /v1/jobs/{id} returns a fresh one. Files are kept for the retention period of your plan (7, 30 or 90 days).

Retrieve a job

GET /v1/jobs/{id}. Poll every 5 to 10 seconds, or use webhooks.

List jobs

GET /v1/jobs?limit=20&status=succeeded&starting_after=job_...

Parameter Description
limit 1 to 100, default 20
status Filter by status
starting_after Cursor: the id of the last job of the previous page 
{ "object": "list", "data": [ { "id": "job_..." } ], "has_more": true, "next_cursor": "job_..." }

Cancel a job

POST /v1/jobs/{id}/cancel stops a queued or running job and returns its credits. Finished jobs are returned unchanged.

Failure codes

error.code Meaning
no_text_found No caption or overlay was found in the video. No credits used.
nothing_erased The engine could not find the text to erase. No credits used.
processing_failed The engine stopped with an error. Credits returned.
timeout Processing took too long and was stopped. Credits returned.
start_failed The video could not be prepared after several attempts. Credits returned.
PreviousUploading videosNext Webhooks