Upload Flow

Media uploads use presigned S3 URLs. Request one with POST /v1/uploads/presign, upload directly to S3, then use the returned taskId when creating segmentation jobs.

Step 1 — Request a Presigned URL

Send a POST request with the contentType of the file you want to upload. The API returns a signed URL valid for 5 minutes, along with the taskId that identifies this upload in subsequent job requests.

Request

curl -X POST \
  https://api.segmentationapi.com/v1/uploads/presign \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_SEGMENTATION_API_KEY" \
  -d '{
    "contentType": "image/png"
  }'

Response

200 OK

{
  "uploadUrl": "https://segmentation-assets-prod.s3.us-east-2.amazonaws.com/inputs/acct_demo_123/0000_a1b2c3d4?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=300&X-Amz-Signature=example",
  "taskId": "0000_a1b2c3d4",
  "bucket": "segmentation-assets-prod",
  "expiresIn": 300
}

Field	Type	Description
`uploadUrl`	`string`	Presigned S3 PUT URL — expires after `expiresIn` seconds
`taskId`	`string`	Unique identifier for this upload; use in `POST /v1/jobs`
`bucket`	`string`	S3 bucket name (informational)
`expiresIn`	`number`	URL validity in seconds (default 300)

Step 2 — Upload File to S3

Use the uploadUrl from the presign response to PUT the raw file bytes directly to S3. Set the Content-Type header to match the contentType you specified in the presign request.

PUT to S3

curl -X PUT "https://s3.amazonaws.com/...signed-url..." \
  -H "Content-Type: image/png" \
  --data-binary "@frame-0001.png"

Content-Type must match. The Content-Type in your PUT request must match the contentType from the presign request, or S3 will reject the upload with a 403.

Supported Formats

Type	Supported Formats
Images	`image/png`, `image/jpeg`, `image/webp`
Video	`video/mp4`, `video/webm`