# AI3D API v2 model: sam3-image

Segment objects in an image with SAM 3 text, point, and box prompts. The output can include one or more masks, optional scores and boxes, and a preview image.

- AI3D model ID: `sam3-image`
- Fal endpoint: `fal-ai/sam-3/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/sam-3/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: `prompt` (default `wheel`), `point_prompts` (up to 64 `{ "x", "y", "label", "object_id?" }` points), `box_prompts` (up to 64 `{ "x_min", "y_min", "x_max", "y_max", "object_id?" }` boxes), `apply_mask` (default `true`), `output_format` (`png`, `jpeg`, or `webp`, default `png`), `return_multiple_masks` (default `false`), `max_masks` (1–32, default 3), `include_scores` (default `false`), `include_boxes` (default `false`), and `sync_mode` (must remain `false`). Coordinates are non-negative source-image pixels; labels are 1 for foreground or 0 for background; `object_id` groups prompts for the same object. Boxes require positive width and height.

Example:

```json
{
  "model": "sam3-image",
  "image_url": "https://example.com/object.png",
  "input": {
    "prompt": "red car",
    "point_prompts": [{"x": 500, "y": 375, "label": 1}],
    "box_prompts": [],
    "return_multiple_masks": true,
    "max_masks": 3,
    "include_scores": 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 available mask and preview images from the job's authenticated `artifacts` URLs; AI3D archives up to 40 returned images per job. Scores and normalized boxes are metadata, not image artifacts.

Fal pricing is per request for this endpoint. Check `GET /v2/billing/prices` for the current rate and reservation. The final charge uses Fal-reported usage when available. Do not automatically resubmit a `submission_unknown` job.