Jobs

Create asynchronous segmentation jobs for images or videos, then poll for results. Each job processes 1-100 uploaded task IDs with the text prompts you specify.

Create a Job

POST/v1/jobs

Submit a type ("image" or "video"), a tasks array of task IDs from the upload flow, and a prompts array with at least one non-empty text phrase.

Request Body

Field	Type	Required	Description
`type`	`string`	Yes	`"image"` or `"video"`
`tasks`	`string[]`	Yes	1–100 task IDs from presign uploads
`prompts`	`string[]`	Yes	Text prompts for segmentation targets
`threshold`	`number`	No	Detection confidence threshold (0–1, image only)
`maskThreshold`	`number`	No	Mask binarization threshold (0–1, image only)
`generatePreview`	`boolean`	No	Generate overlay preview image/video

Image job

curl -X POST \
  https://api.segmentationapi.com/v1/jobs \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_SEGMENTATION_API_KEY" \
  -d '{
    "type": "image",
    "tasks": ["0000_a1b2c3d4"],
    "prompts": ["painting"],
    "threshold": 0.5,
    "maskThreshold": 0.5,
    "generatePreview": true
  }'

Video job

curl -X POST \
  https://api.segmentationapi.com/v1/jobs \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_SEGMENTATION_API_KEY" \
  -d '{
    "type": "video",
    "tasks": ["0001_e5f6g7h8"],
    "prompts": ["person"],
    "generatePreview": true
  }'

Response

202 Accepted

{
  "jobId": "job-abc-987",
  "type": "image",
  "status": "queued",
  "totalItems": 1
}

List Jobs

GET/v1/jobs

Retrieve a paginated list of jobs for your account. Pass limit (max 100) and nextToken for cursor-based pagination.

Request

curl -X GET \
  "https://api.segmentationapi.com/v1/jobs?limit=20" \
  -H "x-api-key: YOUR_SEGMENTATION_API_KEY"

200 OK

{
  "items": [
    {
      "jobId": "job-abc-987",
      "type": "image",
      "status": "completed",
      "totalItems": 1,
      "createdAt": "2026-03-07T12:00:00Z",
      "updatedAt": "2026-03-07T12:01:00Z"
    }
  ],
  "nextToken": "eyJvZmZzZXQiOjIwfQ=="
}

Query Param	Type	Default	Description
`limit`	`number`	`20`	Results per page (max 100)
`nextToken`	`string`	—	Cursor from previous response

Get a Job

GET/v1/jobs/{jobId}

Fetch full details for a single job including per-task status. Each task moves through queued → processing → success | failed.

Request

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

200 OK

{
  "userId": "user-123",
  "jobId": "job-abc-987",
  "type": "image",
  "tasks": [
    {
      "taskId": "0000_a1b2c3d4",
      "status": "success"
    }
  ]
}

Job Status Lifecycle

Status	Description
`queued`	Job is accepted and waiting for a processing slot
`processing`	Segmentation is actively processing
`success`	All tasks completed — masks are available
`failed`	Processing failed — check task-level errors for details

Polling tip: Start polling after 2–3 seconds. Use exponential backoff with a max interval of 10 seconds. Most image jobs complete in under 30 seconds.