# Create a transcription — Shorty API

> Starts an async transcription of media at the given URL. Responds 202 with a `Location` header and a `job_id` you can poll at GET /v1/jobs/{id}. Send an `Idempotency-Key` header to make retries safe. If the transcription service cannot start the job, responds 503.

```http
POST /v1/transcriptions
```

Starts an async transcription of media at the given URL. Responds 202 with a `Location` header and a `job_id` you can poll at GET /v1/jobs/{id}. Send an `Idempotency-Key` header to make retries safe. If the transcription service cannot start the job, responds 503.

## Authentication

Requires a Bearer credential — a `shk_live_` API key or an OAuth 2.1 access token with the scope for this resource. See [Authentication](/docs/api).

## Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `Idempotency-Key` | header | No | Optional client-generated key (1–255 visible ASCII chars) that makes this POST replay-safe: a retry with the SAME key and body returns the original response (with `Idempotency-Replayed: true`) instead of creating a duplicate. Reusing a key with a different body is rejected (422). |

## Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | `string<uri>` | Yes | A URL to audio/video media to transcribe. |
| `language` | `string` | No | Language name ("english") or ISO-639-1 code ("en"). Defaults to english. (2–20 chars) Default: "english". |
| `output_language` | `"en" \| "ar" \| "bn" \| "cs" \| "da" \| "de" \| "el" \| "es" \| "fi" \| "fr" \| "he" \| "hi" \| "hu" \| "id" \| "it" \| "ja" \| "ko" \| "ms" \| "nl" \| "no" \| "pl" \| "pt" \| "ro" \| "ru" \| "sv" \| "th" \| "tr" \| "uk" \| "vi" \| "zh"` | No | Language to deliver the transcript in, as an ISO 639-1 code. "en" is produced by the speech model itself and is free; every other language is a translation of the finished transcript and requires Shorty Premium. |

## Example request

curl:

```bash
curl -X POST https://aishorty.com/v1/transcriptions \
  -H "Authorization: Bearer shk_live_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "url": "https://example.com/podcast.mp3"
  }'
```

TypeScript (@aishorty/sdk):

```typescript
import { Shorty } from '@aishorty/sdk'

const shorty = new Shorty({ apiKey: process.env.SHORTY_API_KEY })

const job = await shorty.transcriptions.create({
    url: 'https://example.com/audio.mp3',
})
const done = await shorty.jobs.waitFor(job.job_id)
```

## Response · 202

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `job_id` | `string` | Yes | The id of the accepted async job. |
| `status` | `string` | Yes | Initial job status (typically "queued"). |
| `tracking_url` | `string` | Yes | Relative path to poll this job’s status (GET /v1/jobs/{id}). |

## Errors

On failure this endpoint returns an RFC 9457 problem body. Possible statuses:

- `400`
- `401`
- `403`
- `409`
- `422`
- `429`
- `500`
- `503`

Switch on the problem `code`, not the status. See the [error reference](/docs/api/errors) for every code and how to fix it.

> **Note:** This endpoint honors an `Idempotency-Key` header: a retry with the same key and body replays the original response for 24 hours instead of creating a duplicate job.