# AI3D API v2 model: sam2-image

Use Segment Anything 2 with point or box prompts to segment a source image.

- AI3D model ID: `sam2-image`
- Fal endpoint: `fal-ai/sam2/image`
- 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/image/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: `prompts` (up to 64 `{ "x", "y", "label" }` points; coordinates are source-image pixels and label is 1 foreground or 0 background), `box_prompts` (up to 64 `{ "x_min", "y_min", "x_max", "y_max" }` boxes in source-image pixels), `apply_mask` (default `false`), `output_format` (`png`, `jpeg`, or `webp`, default `png`), and `sync_mode` (must remain `false`). Coordinates must be non-negative integers; boxes need positive width and height.

Example:

```json
{
  "model": "sam2-image",
  "image_url": "https://example.com/object.png",
  "input": {
    "prompts": [{"x": 500, "y": 375, "label": 1}],
    "box_prompts": [],
    "apply_mask": true
  }
}
```

## 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 successful output images from the job's authenticated `artifacts` URLs. Output names depend on the provider response.

AI3D reserves an estimate of 10 Fal compute units and settles from Fal-reported billable units when available. Check `GET /v2/billing/prices` for the current unit rate and reservation; final usage can differ from the estimate. Do not automatically resubmit a `submission_unknown` job.