# StableSAM API

Video segmentation and object tracking via micropayments. No API keys.

Base URL: `https://stablesam.dev`

## Required Workflow

StableSAM does not accept raw file uploads.

1. Upload the input video to StableUpload.
2. Compute the video's frame count locally before submission.
3. Use the StableUpload `publicUrl` as `videoUrl`.
4. Submit the StableSAM request with `declaredFrameCount`.
5. Poll the StableSAM job until it completes.

## Important MVP Rules

- `videoUrl` must be a StableUpload public URL.
- `declaredFrameCount` is required.
- Requests above `960` frames are rejected.
- Requests whose StableUpload asset is above `100 MB` are rejected.
- Price is computed dynamically from `declaredFrameCount`.
- Segmented output video is silent. StableSAM does not preserve the source audio track.

## Suggested local frame count check

Before calling StableSAM, inspect the local file with a local tool such as `ffprobe` and compute:

- total frames
- or `duration * fps`

Prefer exact frame count when available.

## Upload Step

Use StableUpload first:

`POST https://stableupload.dev/api/upload`

```json
{
  "filename": "clip.mp4",
  "contentType": "video/mp4",
  "tier": "100mb"
}
```

Then `PUT` the file to the returned `uploadUrl` and use `publicUrl` in StableSAM.

## Create Job

`POST /api/segment`

```json
{
  "type": "sam-3-video-segment",
  "videoUrl": "https://f.stableupload.dev/abc123/clip.mp4",
  "declaredFrameCount": 320,
  "prompt": "person, skateboard",
  "pointPrompts": [],
  "boxPrompts": [],
  "applyMask": true,
  "videoOutputType": "mp4",
  "detectionThreshold": 0.5
}
```

## Point Prompt Example

```json
{
  "type": "sam-3-video-segment",
  "videoUrl": "https://f.stableupload.dev/abc123/clip.mp4",
  "declaredFrameCount": 320,
  "prompt": "",
  "pointPrompts": [
    { "x": 640, "y": 300, "label": 1, "objectId": 1, "frameIndex": 0 },
    { "x": 580, "y": 310, "label": 0, "objectId": 1, "frameIndex": 0 }
  ],
  "boxPrompts": [],
  "applyMask": true,
  "videoOutputType": "mp4",
  "detectionThreshold": 0.5
}
```

## Box Prompt Example

```json
{
  "type": "sam-3-video-segment",
  "videoUrl": "https://f.stableupload.dev/abc123/clip.mp4",
  "declaredFrameCount": 320,
  "prompt": "",
  "pointPrompts": [],
  "boxPrompts": [
    {
      "xMin": 450,
      "yMin": 120,
      "xMax": 760,
      "yMax": 620,
      "objectId": 1,
      "frameIndex": 0
    }
  ],
  "applyMask": true,
  "videoOutputType": "mp4",
  "detectionThreshold": 0.5
}
```

## Poll Job

`GET /api/jobs/{jobId}`

Statuses:

- `pending`
- `queued`
- `processing`
- `complete`
- `failed`

## Guidance for Agents

- Use StableUpload public URLs only.
- Compute `declaredFrameCount` locally before sending the request.
- Keep `objectId` stable across prompts for the same object.
- Use `frameIndex: 0` unless a later frame is intentionally needed.
- Use foreground points first and add background points only to reduce mask bleed.
- Use `videoOutputType: "mp4"` unless `webm` is specifically required.
- If you need audio in the final asset, mux the original audio back in after segmentation. StableSAM outputs silent video.