---
title: "Create a media convert session"
method: POST
path: "/api/convert/session"
tags: ["Convert"]
---

# Create a media convert session

`POST /api/convert/session`

## Request

- Base URL: `https://snapwonders.com`
- URL: `https://snapwonders.com/api/convert/session`
- Auth: API key in header `X-Api-Key`

Creates a new upload session for a media **convert** job. Returns the `upload_uid` you must include in every TUS upload request for this session. **Authentication:** `X-Api-Key` header required.

## Request body

- object

## Response `201`

Session created

- object
  - `upload_uid` string, uuid: UUID to include in every TUS upload for this session
  - `status` string
  - `created_at` string, date-time
  - `tus_endpoint` string: TUS root endpoint — append the upload ID for PATCH/HEAD requests
  - `instructions` string: Human-readable upload instructions

## Other responses

- `401`: Not authenticated. `error` names the exact cause: `missing_api_key`, `malformed_api_key`, `invalid_api_key` (key unknown/revoked/expired), or — when the key itself is valid — `account_not_verified` / `account_inactive`.
- `429`: Too many upload sessions created for this API key inside the sliding window (`api.session_create_hard_limit` per `api.session_create_window_seconds`, default 120 per hour). Body is the same `throttled` shape as job start, with `sessions_created`, `limit` and `window_seconds` in place of `active_jobs`. Wait for the window to pass, then retry.

---

[API](https://skmtc.dev/snapwonders/apis/snapwonders-api-mcp.md) · [All operations](https://skmtc.dev/snapwonders/apis/snapwonders-api-mcp/llms.txt) · [OpenAPI document](https://skmtc.dev/snapwonders/apis/snapwonders-api-mcp/revisions/645bbccc9550?raw)