Transcription API

The Transcription API uses AI to transcribe audio and video content. It converts spoken content into text that you can use for captions, subtitles, repurposing into text posts, or any other text-based workflow.

Transcribe Media

Submit an audio or video file for AI transcription.

POST /v1/ai/transcribe

Transcription consumes AI credits from your account balance. The number of credits debited depends on the duration of the media. Check your credit balance in the Soku dashboard under Account > Credits.

Headers

Header	Required	Description
`Content-Type`	Yes	Must be `application/json`
`soku-api-key`	Yes	Your Soku API key
`Idempotency-Key`	No	A unique string to prevent duplicate transcription jobs. If you send the same `Idempotency-Key` within a reasonable time window, the API returns the original result instead of creating a new job.

Request Body

Field	Type	Required	Description
`mediaId`	string	Yes	The ID of the media file to transcribe. This must be a media file already uploaded to the Soku media library.
`language`	string	No	The language of the audio content as an ISO 639-1 code (for example, `"en"`, `"es"`, `"fr"`). Defaults to auto-detection if omitted.
`model`	string	No	The transcription model to use. Currently supported: `"whisper-1"`. Defaults to `"whisper-1"`.
`durationSeconds`	number	No	The duration of the media in seconds. Providing this helps the API estimate credit cost before processing.

Response

Field	Type	Description
`jobId`	string	A unique identifier for the transcription job
`transcript`	string	The transcribed text content
`creditsDebited`	number	The number of AI credits consumed by this transcription
`likelyLyrics`	boolean	Whether the AI detected that the audio content is likely song lyrics rather than speech

{
  "jobId": "tj_a1b2c3d4-e5f6-7890",
  "transcript": "Welcome to today's episode. We are going to talk about building an audience on social media from scratch.",
  "creditsDebited": 10,
  "likelyLyrics": false
}

Examples

Basic transcription

curl -X POST https://api.mysoku.io/v1/ai/transcribe \
  -H "Content-Type: application/json" \
  -H "soku-api-key: sk_live_your_api_key_here" \
  -d '{
    "mediaId": "media_f7e8d9c0b3c4",
    "language": "en",
    "model": "whisper-1"
  }'

Response:

{
  "jobId": "tj_d4e5f6a7-b8c9-0123",
  "transcript": "Welcome to today's episode. We are going to talk about building an audience on social media from scratch.",
  "creditsDebited": 10,
  "likelyLyrics": false
}

Transcription with idempotency

Use the Idempotency-Key header to prevent duplicate charges if you need to retry a request:

curl -X POST https://api.mysoku.io/v1/ai/transcribe \
  -H "Content-Type: application/json" \
  -H "soku-api-key: sk_live_your_api_key_here" \
  -H "Idempotency-Key: unique-request-id-abc123" \
  -d '{
    "mediaId": "media_f7e8d9c0b3c4",
    "language": "en",
    "model": "whisper-1",
    "durationSeconds": 120
  }'

If you send the same request with the same Idempotency-Key, you receive the original result without being charged again.

Transcription with duration estimate

Providing durationSeconds helps the API estimate the credit cost:

curl -X POST https://api.mysoku.io/v1/ai/transcribe \
  -H "Content-Type: application/json" \
  -H "soku-api-key: sk_live_your_api_key_here" \
  -d '{
    "mediaId": "media_a1b2c3d4e5f6",
    "language": "es",
    "model": "whisper-1",
    "durationSeconds": 300
  }'

Transcribe and publish as a text post

A common workflow is to transcribe a video, then publish the transcript as a text post:

# Step 1: Transcribe the video
TRANSCRIPT=$(curl -s -X POST https://api.mysoku.io/v1/ai/transcribe \
  -H "Content-Type: application/json" \
  -H "soku-api-key: sk_live_your_api_key_here" \
  -d '{
    "mediaId": "media_f7e8d9c0b3c4",
    "language": "en"
  }' | jq -r '.transcript')

# Step 2: Publish the transcript as a text post
curl -X POST https://api.mysoku.io/v1/posts \
  -H "Content-Type: application/json" \
  -H "soku-api-key: sk_live_your_api_key_here" \
  -d "{
    \"post\": {
      \"content\": {
        \"text\": \"$TRANSCRIPT\",
        \"mediaType\": \"text\",
        \"platform\": [\"threads\", \"linkedin\"]
      }
    }
  }"

Credit Costs

Transcription costs vary based on the duration of the media file. Credits are debited from your account balance when the transcription completes. The creditsDebited field in the response tells you exactly how many credits were consumed.

Monitor your credit balance in the Soku dashboard under Account > Credits. For information on credit pricing and how to purchase more credits, see Credits System.

Idempotency

The Idempotency-Key header is strongly recommended for transcription requests. Because transcription consumes credits, accidental duplicate requests can result in unnecessary charges. How it works:

Include an Idempotency-Key header with a unique value (for example, a UUID) on your first request.
If the request succeeds, the API caches the result keyed by your idempotency key.
If you retry with the same Idempotency-Key, the API returns the cached result without processing the transcription again or charging additional credits.

# Both requests return the same result; credits are only charged once
curl -X POST https://api.mysoku.io/v1/ai/transcribe \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  ...

curl -X POST https://api.mysoku.io/v1/ai/transcribe \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  ...

Error Responses

HTTP Status	Error Code	Description
400	`validation_error`	Missing or invalid `mediaId` or other fields
401	`unauthorized`	Missing or invalid API key
402	`insufficient_credits`	Your account does not have enough AI credits for this transcription
403	`forbidden`	Subscription is not active
404	`not_found`	The specified `mediaId` does not exist in your media library
429	`rate_limit_exceeded`	Too many requests. See Rate Limits.
500	`internal_error`	An error occurred during transcription processing

Example error response (insufficient credits):

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your account does not have enough AI credits to complete this transcription. Estimated cost: 15 credits. Current balance: 3 credits.",
    "timestamp": "2026-02-28T12:00:00.000Z",
    "requestId": "req_abc123def456",
    "details": {
      "estimatedCost": 15,
      "currentBalance": 3
    }
  }
}

Next Steps

Topic	Description
Posts API	Publish transcribed content as posts
Media API	Upload media for transcription
Credits System	Manage your AI credit balance
AI Transcription	Using transcription in the dashboard

API Reference

Transcription api

Transcription API

Transcribe Media

Headers

Request Body

Response

Examples

Basic transcription

Transcription with idempotency

Transcription with duration estimate

Transcribe and publish as a text post

Credit Costs

Idempotency

Error Responses

Next Steps

API Reference

​Transcription API

​Transcribe Media

​Headers

​Request Body

​Response

​Examples

​Basic transcription

​Transcription with idempotency

​Transcription with duration estimate

​Transcribe and publish as a text post

​Credit Costs

​Idempotency

​Error Responses

​Next Steps

Transcription API

Transcribe Media

Headers

Request Body

Response

Examples

Basic transcription

Transcription with idempotency

Transcription with duration estimate

Transcribe and publish as a text post

Credit Costs

Idempotency

Error Responses

Next Steps