`client.segment`¶

Bases: SyncResource

Sync segment namespace (client.segment).

segment ¶

segment(project_id: UUID | str, asset_id: UUID | str, *, points: list[SegmentPointParam] | None = None, box: list[float] | None = None) -> SegmentResponse

Promptable segmentation on one image. Provide at least one prompt: points (each {"x", "y", "label"} with label 1=positive/0=negative) and/or box ([x1, y1, x2, y2] in original-image pixels). Returns the single best mask (or none); nothing is persisted.

Parameters:

Name	Type	Description	Default
`project_id`	`UUID \| str`	project the asset belongs to.	required
`asset_id`	`UUID \| str`	image asset to segment (must be in this project's dataset).	required
`points`	`list[SegmentPointParam] \| None`	up to 64 SAM click prompts; a longer list is rejected with a 422 (VALIDATION_ERROR). Each is `{"x", "y", "label"}` in original-image pixels, label 1=positive / 0=negative.	`None`
`box`	`list[float] \| None`	single `[x1, y1, x2, y2]` box prompt in original-image pixels.	`None`

Raises:

Type	Description
`NotFoundError`	asset not in this project's dataset (ASSET_NOT_FOUND).
`UnavailableError`	the SAM endpoint is down / off-hours (DEPENDENCY_UNAVAILABLE).
`UnprocessableError`	no prompt given, or a malformed box (VALIDATION_ERROR).
`ForbiddenError`	caller is not a project member (AUTH_FORBIDDEN).

Response models¶

Models returned by client.segment methods (fields, types, and what each means).

Interactive SAM 2.1 segmentation domain models (ADR-0077).

Class-agnostic, human-in-the-loop: prompts (clicks/box) in, a polygon suggestion out — nothing is persisted server-side. Tolerant response readers (extra="allow"); geometry + enums come from common.

SegmentSuggestion ¶

Bases: BaseModel

One SAM mask suggestion. geometry is the same shape annotation.geometry stores, so an accepted suggestion commits through the normal annotation-create path.

SegmentResponse ¶