POST /v1/transcriptions

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.

Open in Claude Open in ChatGPT

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.

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".

Example request

curl -X POST https://aishorty.com/v1/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"
  }'

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 for every code and how to fix it.

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.