UniScribe OpenAPI Documentation (Beta)

⚠️ Beta Version Notice This API is currently in beta. Features and endpoints may change without notice. We recommend testing thoroughly in development environments before production use. Please report any issues or feedback to our support team.

Overview

The UniScribe OpenAPI provides programmatic access to our transcription services, enabling you to integrate audio and video transcription into your workflows, applications, and automation tools like n8n, Zapier, and Make.

Base URL

https://api.uniscribe.co

Authentication

API Key Authentication

Include your API key in the request header:

X-API-Key: your_api_key_here

Getting Your API Key

1. Log in to your UniScribe account
2. Navigate to Settings → API Keys
3. Click "Create New Key"
4. Copy and securely store your API key

Important:

• API access requires an active subscription or LTD plan
• Free users and one-time purchase users cannot access the API
• Keep your API key secure and never share it publicly

File Upload Workflow

The OpenAPI requires users to provide a publicly accessible file URL for transcription.

Requirements:

• File must be publicly accessible via HTTP/HTTPS
• File must be in a supported format
• File size must not exceed 5GB
• File duration must not exceed 10 hours

Endpoints

1. Create Transcription

Endpoint: POST /api/v1/transcriptions

Description: Create a new transcription task from a file URL

Request:

POST /api/v1/transcriptions
Content-Type: application/json
X-API-Key: your_api_key

{
  "file_url": "https://your-storage.com/audio.mp3",
  "filename": "my-audio-file.mp3",
  "language_code": "en",
  "transcription_type": "transcript",
  "enable_speaker_diarization": false,
  "webhook_url": "https://your-webhook-url.com"
}

Parameters:

• file_url (string, required): Public URL to audio/video file. Note: YouTube URLs are not supported here. For YouTube transcription, please use the YouTube Transcription API
• filename (string, optional): Custom filename for the downloaded file. If not provided, filename will be extracted from the URL path
• language_code (string, required): Language code (e.g., "en", "zh", "es"), see Language Support
• transcription_type (string, optional): "transcript" or "subtitle"
• enable_speaker_diarization (boolean, optional): Enable speaker identification
• webhook_url (string, optional): URL to receive completion notifications

Supported File Types:

• Audio: mp3, mpeg, mpga, m4a, wav, aac, ogg, opus, flac
• Video: mp4, webm, mov (audio will be extracted)

Response:

{
  "success": true,
  "data": {
    "id": "1234567890",
    "status": "queued",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Status Values:

• queued: Task is queued for processing
• preprocessing: Media file is being preprocessed (for large files or youtube videos)
• processing: Transcription is in progress
• completed: Transcription is complete
• failed: Transcription failed

2. List Transcriptions

Retrieve a paginated list of your transcriptions.

Endpoint: GET /api/v1/transcriptions

Parameters:

• cursor (integer, optional): Pagination cursor
• limit (integer, optional): Number of items per page (1-20, default: 10)

Example:

GET /api/v1/transcriptions?limit=10&cursor=1234567890
X-API-Key: your_api_key

Response:

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "1234567890",
        "filename": "audio.mp3",
        "status": "completed",
        "duration": 120.5,
        "language_code": "en",
        "transcription_type": "transcript",
        "created_at": "2024-01-15T10:30:00Z",
        "completed_at": "2024-01-15T10:35:00Z",
        "file_size": 1048576,
        "source_type": "upload"
      }
    ],
    "has_more": true,
    "next_cursor": "1234567889"
  },
  "message": "Success",
  "timestamp": "2024-01-15T10:30:00Z"
}

3. Get Transcription Details

Retrieve detailed information and results for a specific transcription.

Endpoint: GET /api/v1/transcriptions/{id}

Example:

GET /api/v1/transcriptions/1234567890
X-API-Key: your_api_key

Response:

{
  "success": true,
  "data": {
    "id": "1234567890",
    "filename": "audio.mp3",
    "status": "completed",
    "duration": 120.5,
    "language_code": "en",
    "transcription_type": "transcript",
    "created_at": "2024-01-15T10:30:00Z",
    "completed_at": "2024-01-15T10:35:00Z",
    "file_size": 1048576,
    "source_type": "upload",
    "source_url": "https://your-storage.com/audio.mp3",
    "result": {
      "text": "Hello, this is a sample transcription...",
      "summary": "This audio discusses...",
      "outline": "# 1. Introduction\n2. Main Points\n3. Conclusion", // in markdown format
      "language": "English",
      "segments": [
        {
          "start": 0.0,
          "end": 5.2,
          "text": "Hello, this is a sample",
          "speaker": "A",
          "words": [
            {
              "start": 0.0,
              "end": 0.8,
              "text": "Hello"
            }
          ]
        }
      ]
    }
  },
  "message": "Success",
  "timestamp": "2024-01-15T10:30:00Z"
}

4. Get Transcription Status

Check the current status of a transcription.

Endpoint: GET /api/v1/transcriptions/{id}/status

Example:

GET /api/v1/transcriptions/1234567890/status
X-API-Key: your_api_key

Response:

{
  "success": true,
  "data": {
    "id": "1234567890",
    "status": "processing",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:33:00Z"
  },
  "message": "Success",
  "timestamp": "2024-01-15T10:30:00Z"
}

5. Create YouTube Transcription

Create a transcription from a YouTube video URL.

Endpoint: POST /api/v1/transcriptions/youtube

Request:

POST /api/v1/transcriptions/youtube
Content-Type: application/json
X-API-Key: your_api_key

{
  "url": "https://www.youtube.com/watch?v=VIDEO_ID",
  "language_code": "en",
  "transcription_type": "transcript",
  "enable_speaker_diarization": false,
  "webhook_url": "https://your-webhook-url.com"
}

Parameters:

• url (string, required): YouTube video URL
• language_code (string, required): Language code (e.g., "en", "zh", "es"), see Language Support
• transcription_type (string, optional): Type of transcription
• enable_speaker_diarization (boolean, optional): Enable speaker identification
• webhook_url (string, optional): Webhook URL for notifications

Note: Video title and duration are automatically extracted from the YouTube URL.

Response: Same format as regular transcription creation - returns task status for async processing.

Status Values

Transcriptions progress through the following statuses:

• queued: Task is queued for processing
• preprocessing: Media file is being preprocessed (for large files or youtube videos)
• processing: Transcription is in progress
• completed: Transcription is complete
• failed: Transcription failed

Webhook Notifications

When you provide a webhook_url, UniScribe will send HTTP POST notifications to your endpoint when transcription completes or fails.

Webhook Events

Transcription Completed

{
  "event": "transcription.completed",
  "data": {
    "id": "1234567890",
    "filename": "audio.mp3",
    "status": "completed",
    "duration": 120.5,
    "language_code": "en",
    "transcription_type": "transcript",
    "created_at": "2024-01-15T10:30:00Z",
    "completed_at": "2024-01-15T10:35:00Z",
    "file_size": 1048576,
    "source_type": "upload"
  },
  "timestamp": "2024-01-15T10:35:00Z"
}

Transcription Failed

{
  "event": "transcription.failed",
  "data": {
    "id": "1234567890",
    "filename": "audio.mp3",
    "status": "failed",
    "created_at": "2024-01-15T10:30:00Z",
    "completed_at": "2024-01-15T10:32:00Z"
  },
  "timestamp": "2024-01-15T10:32:00Z"
}

Webhook Requirements

• Your webhook endpoint must respond with HTTP 2xx status code
• Timeout: 30 seconds
• Include User-Agent: UniScribe-Webhook/1.0 header

Error Handling

Error Response Format

All errors follow a consistent format:

{
  "success": false,
  "error": {
    "message": "Error description",
    "code": 41000,
    "details": "Additional error details (optional)"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

Common Error Codes

Rate Limits

• Default: 10 requests per minute, 1000 requests per day
• Rate limits are per API key
• Exceeded limits return HTTP 429 with retry information

Supported File Formats

• Audio: mp3, mpeg, mpga, m4a, wav, aac, ogg, opus, flac
• Video: mp4, webm, mov (audio will be extracted)

Language Support

UniScribe supports 90+ languages. Complete list of supported language codes:

Integration Examples

n8n Workflow

1. HTTP Request Node:

   • Method: POST
   • URL: https://api.uniscribe.co/api/v1/transcriptions
   • Headers: X-API-Key: your_api_key
   • Body: JSON with file_url, optional filename, and webhook_url

2. Webhook Node:

   • Listen for completion notifications
   • Process transcription results

Python Example

import requests

# Create transcription
response = requests.post(
    'https://api.uniscribe.co/api/v1/transcriptions',
    headers={'X-API-Key': 'your_api_key'},
    json={
        'file_url': 'https://example.com/audio.mp3',
        'filename': 'my-recording.mp3',
        'language_code': 'en',
        'webhook_url': 'https://your-app.com/webhook'
    }
)

transcription = response.json()
transcription_id = transcription['data']['id']

# Check status
status_response = requests.get(
    f'https://api.uniscribe.co/api/v1/transcriptions/{transcription_id}/status',
    headers={'X-API-Key': 'your_api_key'}
)

print(status_response.json())

cURL Examples

# Create transcription from URL
curl -X POST https://api.uniscribe.co/api/v1/transcriptions \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "https://example.com/audio.mp3",
    "filename": "my-audio.mp3",
    "language_code": "en",
    "webhook_url": "https://your-webhook.com"
  }'


# Get transcription results
curl -X GET https://api.uniscribe.co/api/v1/transcriptions/1234567890 \
  -H "X-API-Key: your_api_key"

Best Practices

1. Webhook Reliability: Always implement webhook endpoints with proper error handling and idempotency
2. File Size: Ensure files do not exceed 5GB limit
3. Language Detection: Specify language_code when known for better accuracy
4. Status Polling: If not using webhooks, poll status endpoint every 30-60 seconds
5. Error Handling: Implement retry logic for network errors and rate limits
6. Security: Never expose API keys in client-side code or public repositories

Support

• Support Email: hi@uniscribe.co
• Discord: https://discord.com/invite/RJTaS28UWU

For technical questions or integration assistance, please contact our support team.