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
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. Image and video jobs accept different tuning parameters — see the dedicated tables below.
type (for example maskThreshold on a video job) is rejected with a 400.Common Fields
| Field | Type | Required | Description |
|---|---|---|---|
type | string | Yes | "image" or "video" |
tasks | string[] | Yes | Task IDs from presign uploads. Up to 100 for image jobs; exactly one for video jobs. |
prompts | string[] | Yes | At least one non-empty text prompt for segmentation targets |
generatePreview | boolean | No | Default false. When true, renders a preview artifact — a composited PNG overlay for images, or a baked MP4 for video. |
Image Parameters
| Field | Type | Default | Description |
|---|---|---|---|
threshold | number | 0.5 | Detection confidence threshold (0–1). Higher keeps fewer, more confident detections. |
maskThreshold | number | 0.5 | Mask binarization threshold (0–1). |
Video Parameters
| Field | Type | Default | Description |
|---|---|---|---|
scoreThreshold | number | 0.0 | Per-object detection score threshold (0–1). |
fps | number | — | Sample the video at this frame rate (> 0). Mutually exclusive with numFrames. |
numFrames | integer | — | Sample exactly this many evenly-spaced frames (> 0). Mutually exclusive with fps. |
maxFrames | integer | — | Upper bound on the number of frames processed (> 0). |
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"],
"scoreThreshold": 0.5,
"fps": 6,
"generatePreview": true
}'Response
202 Accepted
{
"jobId": "job-abc-987",
"type": "image",
"totalItems": 1
}List 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": "success",
"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
Fetch full details for a single job including per-task status. Each task moves through queued → processing → success | failed. This response carries no mask data — poll it until the job succeeds, then retrieve masks via the Results flow.
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",
"error": "",
"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 | Finished — request the results archive to download masks |
failed | Processing failed — check task-level errors for details |