Transcribe Audio

Transcribe audio files using OpenAI Whisper. The API saves both the original audio file and the generated markdown transcript to the customer's files in Supabase Storage.

Endpoint

POST https://recoup-api.vercel.app/api/transcribe

Request Body

Name	Type	Required	Description
audio_url	string	Yes	Public URL to the audio file (mp3, wav, m4a, webm)
account_id	string	Yes	Owner account ID for file storage
artist_account_id	string	Yes	Artist account ID for file storage
title	string	No	Optional title for the audio and transcription files
include_timestamps	boolean	No	Whether to include timestamps in the markdown transcript

Request Examples

cURL

curl -X POST "https://recoup-api.vercel.app/api/transcribe" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://example.com/song.mp3",
    "account_id": "YOUR_ACCOUNT_ID",
    "artist_account_id": "YOUR_ARTIST_ACCOUNT_ID",
    "title": "My Song",
    "include_timestamps": true
  }'

Response Format

The API returns a JSON response with information about the saved files and the transcription text.

{
  "success": true,
  "audioFile": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "fileName": "My_Song-1704567890123.mp3",
    "storageKey": "files/account-id/artist-id/My_Song-1704567890123.mp3"
  },
  "transcriptFile": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "fileName": "My_Song-1704567890123-transcript.md",
    "storageKey": "files/account-id/artist-id/My_Song-1704567890123-transcript.md"
  },
  "text": "These are the transcribed lyrics or spoken words from the audio file...",
  "language": "en"
}

Response Properties

Property	Type	Description
success	boolean	Whether the transcription was successful
audioFile	object	Information about the saved audio file
audioFile.id	string	UUID of the file record in the database
audioFile.fileName	string	Name of the saved audio file
audioFile.storageKey	string	Storage path in Supabase Storage
transcriptFile	object	Information about the saved transcript file
transcriptFile.id	string	UUID of the file record in the database
transcriptFile.fileName	string	Name of the saved markdown transcript file
transcriptFile.storageKey	string	Storage path in Supabase Storage
text	string	The full transcription text
language	string	Detected language code (e.g., "en", "es", "fr")

Error Responses

Status	Error Message	Description
400	Missing required field: audio_url	The audio_url field is required
400	Missing required field: account_id	The account_id field is required
400	Missing required field: artist_account_id	The artist_account_id field is required
400	Could not fetch the audio file	The audio URL is not accessible
413	Audio file exceeds the 25MB limit	OpenAI Whisper has a 25MB file size limit
429	Rate limit exceeded	Too many requests, try again later
500	OpenAI API key is not configured	Server configuration error

Notes

Supported audio formats: MP3, WAV, M4A, WebM
Maximum file size: 25MB (OpenAI Whisper limit)
The audio file must be publicly accessible via the provided URL
Both the original audio and the markdown transcript are saved to customer files
Files are stored in Supabase Storage under the path files/{account_id}/{artist_id}/
File names include a timestamp to ensure uniqueness
The transcript markdown includes optional timestamps when include_timestamps is true
Language is automatically detected by OpenAI Whisper