# AI3D API v2 model: sam2-auto-segment

Automatically segment an image with Segment Anything 2. Results include a combined mask and individual masks.

- AI3D model ID: `sam2-auto-segment`
- Fal endpoint: `fal-ai/sam2/auto-segment`
- Task: `image_to_image`
- Availability: Check `GET https://api.ai3d.dev/v2/models`; key model allowlists can affect access.
- Shared implementation guide: <https://api.ai3d.dev/v2/llms.txt>
- AI3D API reference: <https://api.ai3d.dev/v2/openapi.json>
- Fal reference: <https://fal.ai/models/fal-ai/sam2/auto-segment/llms.txt>

## Request

Submit through the AI3D v2 job API; do not call Fal directly or put provider credentials in a client.

- Method and URL: `POST https://api.ai3d.dev/v2/jobs`
- Authentication: `Authorization: Bearer <AI3D_API_KEY>` with write permission and this model allowed on the key.
- Source: required top-level `image_url`, a publicly reachable HTTPS PNG, JPEG, or WebP image. For a local image, use `POST /v2/uploads` and pass its returned `image_url`.
- Optional `input` fields: `points_per_side` (1–128, default 32), `pred_iou_thresh` (0–1, default 0.88), `stability_score_thresh` (0–1, default 0.95), `min_mask_region_area` (non-negative integer, default 100), `output_format` (`png` or `jpeg`, default `png`), and `sync_mode` (must remain `false`).

Example:

```json
{
  "model": "sam2-auto-segment",
  "image_url": "https://example.com/object.png",
  "input": {
    "points_per_side": 32,
    "pred_iou_thresh": 0.88,
    "stability_score_thresh": 0.95,
    "min_mask_region_area": 100,
    "output_format": "png"
  }
}
```

## Job lifecycle and billing

Submit with an `Idempotency-Key`, then poll `GET /v2/jobs/{job_id}` until the job is `succeeded`, `failed`, or `submission_unknown`. Download the combined mask and available individual mask images from the job's authenticated `artifacts` URLs. AI3D archives up to 40 returned images per job.

The default Fal reservation estimate is 30 compute units and scales with the square of `points_per_side` relative to 32. Check `GET /v2/billing/prices` for the current unit rate and reservation; final usage is settled from Fal-reported billable units when available and can differ from the estimate. Do not automatically resubmit a `submission_unknown` job.