Create an asynchronous segmentation job (image or video)

POST

/v1/jobs

curl --request POST \
  --url https://api.segmentationapi.com/v1/jobs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "type": "image", "prompts": [ "example" ], "generatePreview": true, "threshold": 1, "maskThreshold": 1, "tasks": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890.png", "b2c3d4e5-f6a7-8901-bcde-f12345678901.jpg" ] }'

Queue an image or video segmentation job from previously uploaded task IDs and text prompts. The job runs asynchronously. Poll retrieveJob until status is success, then fetch masks with retrieveJobResult or createJobDownload. Auth is required; there is no anonymous API.

Authorizations

• Authorizer

Request Body^required

Media typeapplication/json

One of: discriminator: type

object

object

type

required

string

Allowed values: image

Example

image

prompts

required

Required for all jobs and must include at least one non-empty prompt.

Array<string>

>= 1 items

generatePreview

When true, includes a composited preview image in the result.

boolean

threshold

Confidence threshold. Defaults to 0.5.

number

<= 1

maskThreshold

Mask threshold. Defaults to 0.5.

number

<= 1

tasks

required

Task ids returned by POST /v1/uploads/presign.

Array<string>

>= 1 items <= 100 items

Example

[
  "a1b2c3d4-e5f6-7890-abcd-ef1234567890.png",
  "b2c3d4e5-f6a7-8901-bcde-f12345678901.jpg"
]

object

object

type

required

string

Allowed values: video

Example

video

prompts

required

Array<string>

>= 1 items

generatePreview

When true, includes a baked preview video in the result.

boolean

scoreThreshold

Confidence threshold. Defaults to 0.

number

<= 1

fps

Sampling rate in frames per second. Mutually exclusive with numFrames.

number

numFrames

Number of frames to sample. Mutually exclusive with fps.

integer

>= 1

maxFrames

Upper bound on processed video frames.

integer

>= 1

tasks

required

Single task id returned by POST /v1/uploads/presign.

Array<string>

>= 1 items <= 1 items

Responses

202

Job accepted

Media typeapplication/json

object

jobId

required

string

type

required

string

Allowed values: image video

totalItems

required

integer

>= 1

trial

object

remainingTokens

required

integer

expiresAt

required

string format: date-time

Example

{
  "jobId": "job-abc-987",
  "type": "image",
  "totalItems": 2
}

400

Invalid request

Media typeapplication/json

object

error

required

string

message

string

remainingTokens

integer

requestedTokens

integer

>= 1

expiresAt

string format: date-time

activeJobId

string

upgradeUrl

string format: uri

retryAfterSeconds

integer

>= 1

Example^generated

{
  "error": "example",
  "message": "example",
  "remainingTokens": 1,
  "requestedTokens": 1,
  "expiresAt": "2026-04-15T12:00:00Z",
  "activeJobId": "example",
  "upgradeUrl": "https://example.com",
  "retryAfterSeconds": 1
}

401

Authentication is missing, invalid, or expired

Media typeapplication/json

object

error

required

string

message

string

remainingTokens

integer

requestedTokens

integer

>= 1

expiresAt

string format: date-time

activeJobId

string

upgradeUrl

string format: uri

retryAfterSeconds

integer

>= 1

Example^generated

{
  "error": "example",
  "message": "example",
  "remainingTokens": 1,
  "requestedTokens": 1,
  "expiresAt": "2026-04-15T12:00:00Z",
  "activeJobId": "example",
  "upgradeUrl": "https://example.com",
  "retryAfterSeconds": 1
}

402

Trial access is expired, exhausted, or insufficient

Media typeapplication/json

object

error

required

string

message

string

remainingTokens

integer

requestedTokens

integer

>= 1

expiresAt

string format: date-time

activeJobId

string

upgradeUrl

string format: uri

retryAfterSeconds

integer

>= 1

Example^generated

{
  "error": "example",
  "message": "example",
  "remainingTokens": 1,
  "requestedTokens": 1,
  "expiresAt": "2026-04-15T12:00:00Z",
  "activeJobId": "example",
  "upgradeUrl": "https://example.com",
  "retryAfterSeconds": 1
}

403

The provided taskId does not belong to the authenticated account

Media typeapplication/json

object

error

required

string

message

string

remainingTokens

integer

requestedTokens

integer

>= 1

expiresAt

string format: date-time

activeJobId

string

upgradeUrl

string format: uri

retryAfterSeconds

integer

>= 1

Example^generated

{
  "error": "example",
  "message": "example",
  "remainingTokens": 1,
  "requestedTokens": 1,
  "expiresAt": "2026-04-15T12:00:00Z",
  "activeJobId": "example",
  "upgradeUrl": "https://example.com",
  "retryAfterSeconds": 1
}

409

Request conflicts with the current resource state

Media typeapplication/json

object

error

required

string

message

string

remainingTokens

integer

requestedTokens

integer

>= 1

expiresAt

string format: date-time

activeJobId

string

upgradeUrl

string format: uri

retryAfterSeconds

integer

>= 1

Example^generated

{
  "error": "example",
  "message": "example",
  "remainingTokens": 1,
  "requestedTokens": 1,
  "expiresAt": "2026-04-15T12:00:00Z",
  "activeJobId": "example",
  "upgradeUrl": "https://example.com",
  "retryAfterSeconds": 1
}

500

Internal server error

Media typeapplication/json

object

error

required

string

message

string

remainingTokens

integer

requestedTokens

integer

>= 1

expiresAt

string format: date-time

activeJobId

string

upgradeUrl

string format: uri

retryAfterSeconds

integer

>= 1

Example^generated

{
  "error": "example",
  "message": "example",
  "remainingTokens": 1,
  "requestedTokens": 1,
  "expiresAt": "2026-04-15T12:00:00Z",
  "activeJobId": "example",
  "upgradeUrl": "https://example.com",
  "retryAfterSeconds": 1
}

502

Failed to enqueue job for background processing

Media typeapplication/json

object

error

required

string

message

string

remainingTokens

integer

requestedTokens

integer

>= 1

expiresAt

string format: date-time

activeJobId

string

upgradeUrl

string format: uri

retryAfterSeconds

integer

>= 1

Example^generated

{
  "error": "example",
  "message": "example",
  "remainingTokens": 1,
  "requestedTokens": 1,
  "expiresAt": "2026-04-15T12:00:00Z",
  "activeJobId": "example",
  "upgradeUrl": "https://example.com",
  "retryAfterSeconds": 1
}

503

Free trial queue capacity is temporarily unavailable

Media typeapplication/json

object

error

required

string

message

string

remainingTokens

integer

requestedTokens

integer

>= 1

expiresAt

string format: date-time

activeJobId

string

upgradeUrl

string format: uri

retryAfterSeconds

integer

>= 1

Example^generated

{
  "error": "example",
  "message": "example",
  "remainingTokens": 1,
  "requestedTokens": 1,
  "expiresAt": "2026-04-15T12:00:00Z",
  "activeJobId": "example",
  "upgradeUrl": "https://example.com",
  "retryAfterSeconds": 1
}

Headers

Retry-After

integer