Machine API

Queue analyses programmatically

Submit a video by URL, optionally with a character registry, and receive calibrated consistency scores by webhook or by polling job status.

Submit a job

POST https://mhfxmaylqosurzzupfyy.supabase.co/functions/v1/api-score
Authorization: Bearer <api_key>
Content-Type: application/json

{
  "video_url": "https://example.com/shot.mp4",
  "registry": [
    {
      "name": "ada",
      "image_urls": ["https://example.com/ada-1.png", "https://example.com/ada-2.png"]
    }
  ],
  "judge": true,
  "webhook_url": "https://your.app/hooks/consistency",
  "client_ref": "scene-014"
}

Response:

{
  "job_id": "1f0b…c7",
  "status_url": "https://mhfxmaylqosurzzupfyy.supabase.co/functions/v1/job-status?id=1f0b…c7"
}

Full example:

curl -X POST https://mhfxmaylqosurzzupfyy.supabase.co/functions/v1/api-score \
  -H "Authorization: Bearer $VC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://example.com/shot.mp4",
    "registry": [{ "name": "ada", "image_urls": ["https://example.com/ada-1.png"] }],
    "judge": true,
    "webhook_url": "https://your.app/hooks/consistency",
    "client_ref": "scene-014"
  }'

Read the result

The result is POSTed to webhook_url when the run finishes, and is always readable at:

GET https://mhfxmaylqosurzzupfyy.supabase.co/functions/v1/job-status?id=<job_id>
Authorization: Bearer <api_key>

{
  "id": "1f0b…c7",
  "status": "done",
  "result": {
    "overall": 0.86,
    "consistency": 0.91,
    "persistence": 0.79,
    "findings_count": 4,
    "dimensions": {
      "identity_drift": 0.88,
      "scene_layout": 0.83,
      "placement": 0.90
    }
  },
  "report_url": "https://…/report.html?token=…"
}

Fields

video_url: Required. https URL to the video, up to 2 GB. The worker downloads it.
registry: Optional array of { name, image_urls[] } — up to 8 reference images per character.
judge: Optional boolean. Runs the deep VLM consistency supervisor pass.
webhook_url: Optional. Receives the finished result payload by POST.
client_ref: Optional string echoed back in the webhook payload.

Webhook payload

When the run finishes we POST this JSON to webhook_url:

{
  "job_id": "1f0b…c7",
  "status": "done",
  "client_ref": "scene-014",
  "result": { "overall": 0.86, "consistency": 0.91, "persistence": 0.79, "findings": [ … ] }
}

Rate limits & retention

5 active jobs: Per account on create-job (browser uploads). Exceeding it returns HTTP 429.
30 jobs / hour: Per API key on api-score. Exceeding it returns HTTP 429 with an error message.
2 GB max: Per video, for both uploads and video_url submissions.
7 day retention: Uploaded videos are deleted 7 days after the run.
90 day retention: Reports are deleted 90 days after the run.