---
title: "Start a direct upload (large files)"
method: POST
path: "/v1/uploads/init"
tags: ["Transcription"]
---

# Start a direct upload (large files)

`POST /v1/uploads/init`

## Request

- Base URL: `https://whipscribe.com/api`
- URL: `https://whipscribe.com/api/v1/uploads/init`
- Auth: API key in header `X-API-Key`

For large files: get a short-lived upload URL, send the file bytes to it with the returned `method` and `headers`, then call `POST /v1/uploads/{job_id}/commit`. Requires an API key bound to an account.

## Headers

- `Idempotency-Key` string

## Request body

- UploadInit
  - `filename` string, required
  - `content_type` string
  - `size_bytes` integer, required
  - `language` string: ISO 639-1 language code (`en`, `es`, `fr`, ...), or `auto` to detect it.
  - `diarize` boolean: Label who is speaking.
  - `word_timestamps` boolean: Include per-word start and end times.
  - `source` 'upload' | 'url' | 'recording' | 'api': How the transcript was created. Defaults to `upload` for file submits and `url` for link submits.

## Response `200`

Upload ticket.

- UploadTicket
  - `job_id` string, uuid, required
  - `object_key` string, required: Echo this back to the commit call.
  - `upload_url` string, uri, required: Short-lived URL to send the file bytes to.
  - `method` string, required
  - `headers` object: Headers to send with the upload request.
  - `expires_in` integer, required: Seconds until `upload_url` expires.
  - `options` object, required: Echo this back to the commit call unchanged.

## Other responses

- `400`: Malformed request (e.g. `BAD_ID`, `BAD_URL`, `BAD_IDEMPOTENCY_KEY`).
- `401`: Missing or invalid API key, or the job needs an ownership proof (`X-Claim-Token`).
- `402`: Not enough credit (`NO_CREDITS`, `INSUFFICIENT_CREDITS_FOR_DURATION`), or the finished transcript is locked (`transcript_locked`). With your own API key the body also carries `checkout_url`: a card checkout link for your account that a person can open and pay; then repeat the request.
- `415`: File extension not accepted (`BAD_EXT`).
- `422`: A field failed validation (e.g. `BAD_SOURCE`).
- `429`: Too many requests; retry with backoff (`RATE_LIMITED`, `QUOTA_EXCEEDED`).

---

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