Results

The job status endpoint never returns masks. Once a job has succeeded, request a results archive — a zip containing output_manifest.json plus the mask artifacts — then poll until it is ready and download it.

Retrieve Results

Step 1 — Request the Archive

POST/v1/jobs/{jobId}/download

Kick off (or reuse) the archive build. Returns a download record whose status is pending, processing, or ready.

Request

curl -X POST \
  https://api.segmentationapi.com/v1/jobs/job-abc-987/download \
  -H "x-api-key: YOUR_SEGMENTATION_API_KEY"

202 Accepted

{
  "jobId": "job-abc-987",
  "status": "pending",
  "expiresAt": null,
  "downloadUrl": null,
  "retryAfterSeconds": 2,
  "error": null
}

Job must have succeeded. Requesting a download before the job reaches success returns 409 job_not_downloadable. Poll GET /v1/jobs/{jobId} first.

Step 2 — Poll Until Ready

GET/v1/jobs/{jobId}/download

Poll until status is ready, waiting retryAfterSeconds between requests (2s while pending, 5s while processing). When ready, the response includes a short-lived presigned downloadUrl.

Request

curl -X GET \
  https://api.segmentationapi.com/v1/jobs/job-abc-987/download \
  -H "x-api-key: YOUR_SEGMENTATION_API_KEY"

200 OK

{
  "jobId": "job-abc-987",
  "status": "ready",
  "expiresAt": "2026-03-08T12:01:00Z",
  "downloadUrl": "https://segmentation-assets-prod.s3.us-east-2.amazonaws.com/downloads/acct_demo_123/job-abc-987/job-job-abc-987.zip?X-Amz-Signature=example",
  "retryAfterSeconds": null,
  "error": null
}

Field	Type	Description
`status`	`string`	`pending` · `processing` · `ready` · `failed`
`downloadUrl`	`string \| null`	Presigned zip URL, present once `ready` (expires in ~5 minutes)
`retryAfterSeconds`	`number \| null`	Suggested wait before polling again
`expiresAt`	`string \| null`	When the archive is purged (retained ~24h)
`error`	`string \| null`	Failure reason when `status` is `failed`

Calling GET before you have POSTed a download request returns 404 download_not_requested.

Step 3 — Read the Manifest

Download and unzip downloadUrl. The archive contains output_manifest.json and the referenced mask artifacts. The manifest shape differs by job type.

Image jobs — each item carries a masks array of per-instance PNG masks with a maskIndex, confidence, and archive-relative url.

output_manifest.json (image)

{
  "accountId": "acct_demo_123",
  "jobId": "job-abc-987",
  "type": "image",
  "prompts": ["painting"],
  "items": [
    {
      "taskId": "0000_a1b2c3d4",
      "inputId": "0000_a1b2c3d4",
      "units": 1,
      "generatedAt": "2026-03-07T12:01:00Z",
      "previewUrl": "preview/0000_a1b2c3d4.png",
      "masks": [
        { "maskIndex": 0, "confidence": 0.97, "url": "masks/0000_a1b2c3d4/0.png" },
        { "maskIndex": 1, "confidence": 0.91, "url": "masks/0000_a1b2c3d4/1.png" }
      ]
    }
  ]
}

Video jobs — masks is a path to a per-frame COCO-RLE artifact (not individual PNGs), alongside counts and the sampling settings used. A baked preview MP4 is referenced by previewUrl when generatePreview was set.

output_manifest.json (video)

{
  "accountId": "acct_demo_123",
  "jobId": "job-def-654",
  "type": "video",
  "prompts": ["person"],
  "items": [
    {
      "taskId": "0001_e5f6g7h8",
      "inputId": "0001_e5f6g7h8",
      "units": 120,
      "generatedAt": "2026-03-07T12:05:00Z",
      "previewUrl": "preview/0001_e5f6g7h8.mp4",
      "masks": "masks/0001_e5f6g7h8/masks.json",
      "counts": {
        "framesProcessed": 120,
        "framesWithMasks": 118,
        "totalMasks": 240
      },
      "fps": 6,
      "scoreThreshold": 0.5
    }
  ]
}