---
title: Jobs
description: Create async image and video segmentation jobs, list job history, and retrieve per-item results.
---

Create an asynchronous job with uploaded task IDs and text prompts, then poll until it finishes. Request and response fields live in the [API reference](/docs/api) under `createJob`, `listJobs`, and `retrieveJob`.

## Create a job

```ts
const job = await client.jobs.create({
  type: "image",
  tasks: [upload.taskId],
  prompts: ["painting"],
  threshold: 0.5,
  maskThreshold: 0.5,
  generatePreview: true,
});
```

```bash
curl -X POST https://api.segmentationapi.com/v1/jobs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SEGMENTATION_API_KEY" \
  -d '{
    "type": "image",
    "tasks": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890.png"],
    "prompts": ["painting"]
  }'
```

Video jobs take exactly one task ID and use `scoreThreshold`, `fps` or `numFrames`, and `maxFrames` instead of the image thresholds. Sending a field that does not belong to the job `type` returns 400.

Unbilled accounts may submit one to three JPEG, PNG, or WebP images per job. Video and larger batches need paid access. See the [free API trial](/docs/free-api-trial).

## Status

`retrieveJob` returns queued → processing → success or failed per task. It never includes masks. When status is `success`, go to [results](/docs/results).

Start polling after a couple of seconds. Back off up to about 10 seconds between calls. Most image jobs finish in under 30 seconds.