> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.segmentationapi.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.segmentationapi.com/_mcp/server.

# Jobs

> 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](/api-reference) under `createJob`, `listJobs`, and `retrieveJob`.

## Create a job

```ts
const job = await client.jobs.createJob({
  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](/guides/free-api-trial).

## Status

`retrieveJob` returns queued → processing → success or failed per task. It never includes masks. When status is `success`, go to [results](/guides/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.