apyhub
▣ ARTIFICIAL INTELLIGENCE

Prompted Image Segmentation API

What it does

Prompted Segmentation lets you isolate objects in an image using either a point prompt or a bounding box. Send a binary file plus coordinates, and get back segmentation masks encoded as RLE, along with the prompt you used and a mask score.

Use POST /point when you know a pixel on the object you want to include or exclude. Provide x, y, file, and optionally label to mark the point as foreground (1) or background (0). The response includes masks, the selected point, and best_mask_index so you can choose the most likely result.

Use POST /box when you already have a region of interest. Provide x1, y1, x2, y2, and file, and the service returns the normalized box, a score, and mask_rle for the segmented object. The RLE mask format is compact for storage and easy to pass into downstream image workflows.

Prompted Segmentation fits annotation pipelines, background removal tools, and object-focused image editing where you need a fast mask from minimal user input.

▣ ENDPOINT 01 / 02
POST
Segment the object at a specific pixel coordinate
http://localhost:8080/dosvak/prompted-segmentation/point
QUICKSTARTGUIDE

Quickstart

Upload an image and a single point to get segmentation masks for that point.

curl -X POST "http://localhost:8080/dosvak/prompted-segmentation/point" \
  -H "apy-token: $APY_TOKEN" \
  -F "file=@/path/to/image.jpg" \
  -F "x=120" \
  -F "y=80" \
  -F "label=1"

What you'll get back

Returns a JSON object with optional top-level fields: masks is an array of mask results, point is the point used for segmentation, and best_mask_index is the index of the best mask.

{
  "masks": [
    {
      "index": 0,
      "score": 0.98,
      "mask_rle": {
        "size": [720, 1280],
        "order": "F",
        "counts": [123, 45, 67]
      }
    }
  ],
  "point": {
    "x": 120,
    "y": 80
  },
  "best_mask_index": 0
}
TRY ITLIVE · 100 ATOMS
Loading your default key…
The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.
Max 100MB total per request (all files combined). Larger? Use this API's URL-based endpoint instead, if it has one.
body*
X pixel coordinate
Y pixel coordinate
1 = foreground (include), 0 = background (exclude)

About this endpoint

What it does

Segments an object in an uploaded image using a specified pixel coordinate as the prompt. It accepts the image file plus point coordinates, and returns one or more predicted masks along with the selected point and the index of the best mask.

Request Body

ParameterTypeMandatoryDescription
xIntegerNoX pixel coordinate.
yIntegerNoY pixel coordinate.
fileStringYesImage file to segment. Binary upload.
labelENUMNoPrompt label: 0 = background (exclude), 1 = foreground (include). Default: 1.

Response

Returns a JSON object with masks as an array of mask objects, point as an object containing the prompted x and y coordinates, and best_mask_index as an integer. Each mask includes an index integer, a score number, and a mask_rle object describing the run-length encoded mask.

ParameterTypeMandatoryDescription
masksObject ArrayNoArray of predicted masks. Each item contains index (integer), score (number), and mask_rle (object).
pointObjectNoThe prompt point used for segmentation. Contains x and y integer coordinates.
best_mask_indexIntegerNoIndex of the mask selected as the best prediction.

Body

Name
Type
Description
bodyREQUIRED
object
—

Max 100MB total per request (all files combined). Larger? Use this API's URL-based endpoint instead, if it has one.

▣ ENDPOINT 02 / 02
POST
Segment the object inside a bounding box
http://localhost:8080/dosvak/prompted-segmentation/box
QUICKSTARTGUIDE

Quickstart

Upload an image to detect a segmentation box around the object.

curl -X POST "http://localhost:8080/dosvak/prompted-segmentation/box" \
  -H "apy-token: $APY_TOKEN" \
  -F "file=@/path/to/image.jpg"

What you'll get back

Returns a JSON object with:

  • box as an object containing x1, x2, y1, and y2 integers,
  • score as a number,
  • mask_rle as an object with size, order, and counts for the run-length encoded mask.
{
  "box": { "x1": 12, "x2": 248, "y1": 34, "y2": 290 },
  "score": 0.98,
  "mask_rle": {
    "size": [256, 256],
    "order": "F",
    "counts": [123, 8, 45, 16]
  }
}
TRY ITLIVE · 100 ATOMS
Loading your default key…
The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.
Max 100MB total per request (all files combined). Larger? Use this API's URL-based endpoint instead, if it has one.
body*

About this endpoint

What it does

Segments the object in the uploaded image that falls inside the provided bounding box coordinates. It returns the detected box, a segmentation confidence score, and a run-length encoded mask.

Request Body

ParameterTypeMandatoryDescription
x1IntegerNoLeft coordinate of the bounding box.
x2IntegerNoRight coordinate of the bounding box.
y1IntegerNoTop coordinate of the bounding box.
y2IntegerNoBottom coordinate of the bounding box.
fileStringYesImage file to segment. Binary upload (format: binary).

Response

Returns a JSON object with three top-level fields: box is an object with integer coordinates, score is a number, and mask_rle is an object containing the encoded mask data.

ParameterTypeMandatoryDescription
boxObjectNoSegmentation box coordinates returned by the service. Contains x1, x2, y1, and y2 as integer fields.
scoreNumberNoSegmentation confidence score.
mask_rleObjectNoRun-length encoded boolean mask. Contains size (Integer Array, [height, width]), order (ENUM, allowed value: F), and counts (Integer Array, run lengths in column-major order).

Body

Name
Type
Description
bodyREQUIRED
object
—

Max 100MB total per request (all files combined). Larger? Use this API's URL-based endpoint instead, if it has one.

▣ COMMON ERRORS

Errors any endpoint can return

400bad_request

Required parameter missing or malformed body.

401unauthorized

API key missing, revoked, or not authorized for this service.

429rate_limited

Your plan's per-second rate exceeded. Retry with exponential backoff.

503upstream_busy

Backend temporarily unavailable. Try again in a few seconds.

Product
CatalogPricingBecome a providerStatus (opens in new tab)
Company
AboutBlogCareers (opens in new tab)Contact
Legal
Terms of ServicePrivacy PolicyProvider terms
© 2026 APYHUB · BUILT FOR DEVELOPERS