Migrate from Batch API V1 to V3

This guide helps you migrate from the deprecated Batch API V1 to the current V3 API. V1 will be discontinued, so migrating to V3 is essential for continued service.

Overview

What's Changed

Major Changes:

• New endpoint structure and URLs
• Improved authentication with API keys
• Enhanced response formats with more metadata
• Better error handling and status codes
• Webhook support for job completion
• Support for larger files via TUS protocol

What's Better in V3:

• Faster processing times
• More language options
• Better accuracy
• Improved speaker diarization
• Glossary support
• Custom model support

Timeline

• V1 Deprecated: June 2024
• V1 End of Life: December 2024
• Action Required: Migrate to V3 before December 2024

Breaking Changes

1. Base URL

V1:

https://api.scriptix.io/api/v1/transcribe

V3:

https://api.scriptix.io/api/v3/batch/transcribe

2. Authentication

V1: Basic authentication or API key in query parameter

curl -X POST https://api.scriptix.io/api/v1/transcribe?api_key=YOUR_KEY

V3: Bearer token authentication in header

curl -X POST https://api.scriptix.io/api/v3/batch/transcribe \
  -H "Authorization: Bearer YOUR_API_KEY"

3. File Upload

V1: Direct file upload in request body

curl -X POST https://api.scriptix.io/api/v1/transcribe \
  -F "file=@audio.mp3" \
  -F "language=en"

V3: Two-step process with file upload endpoint

# Step 1: Upload file
curl -X POST https://api.scriptix.io/api/v3/batch/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@audio.mp3"

# Step 2: Create transcription job
curl -X POST https://api.scriptix.io/api/v3/batch/transcribe \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "uploaded_file_id",
    "language": "en"
  }'

4. Response Format

V1 Response:

{
  "status": "processing",
  "id": "12345"
}

V3 Response:

{
  "job_id": "job_abc123",
  "status": "processing",
  "created_at": "2024-12-07T10:00:00Z",
  "language": "en",
  "duration": null,
  "progress": 0,
  "webhook_url": null
}

5. Status Checking

V1:

curl https://api.scriptix.io/api/v1/status/12345?api_key=YOUR_KEY

V3:

curl https://api.scriptix.io/api/v3/batch/jobs/job_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

6. Retrieve Results

V1:

curl https://api.scriptix.io/api/v1/result/12345?api_key=YOUR_KEY

V3:

curl https://api.scriptix.io/api/v3/batch/jobs/job_abc123/result \
  -H "Authorization: Bearer YOUR_API_KEY"

Migration Steps

Step 1: Get V3 API Key

1. Log in to your Scriptix account
2. Go to Account Settings → API Keys
3. Click Generate New Key
4. Copy and securely store your V3 API key

Step 2: Update Base URL

Update all API calls to use the V3 base URL:

Before:

BASE_URL = "https://api.scriptix.io/api/v1"

After:

BASE_URL = "https://api.scriptix.io/api/v3/batch"

Step 3: Update Authentication

Replace query parameter or basic auth with Bearer token:

Before (V1):

import requests

response = requests.post(
    "https://api.scriptix.io/api/v1/transcribe",
    params={"api_key": "YOUR_KEY"},
    files={"file": open("audio.mp3", "rb")}
)

After (V3):

import requests

headers = {
    "Authorization": f"Bearer {API_KEY}"
}

# Upload file first
upload_response = requests.post(
    "https://api.scriptix.io/api/v3/batch/upload",
    headers=headers,
    files={"file": open("audio.mp3", "rb")}
)
file_id = upload_response.json()["file_id"]

# Create transcription job
job_response = requests.post(
    "https://api.scriptix.io/api/v3/batch/transcribe",
    headers=headers,
    json={
        "file_id": file_id,
        "language": "en"
    }
)

Step 4: Update Response Handling

Adapt to new response structure:

Before (V1):

job_id = response.json()["id"]
status = response.json()["status"]

After (V3):

job_id = response.json()["job_id"]
status = response.json()["status"]
created_at = response.json()["created_at"]
progress = response.json()["progress"]

Step 5: Implement Webhooks (Optional)

V3 supports webhooks for job completion:

job_response = requests.post(
    "https://api.scriptix.io/api/v3/batch/transcribe",
    headers=headers,
    json={
        "file_id": file_id,
        "language": "en",
        "webhook_url": "https://yourapp.com/webhook"
    }
)

Step 6: Test Thoroughly

Before deploying to production:

1. Test file upload
2. Test job creation
3. Test status polling
4. Test result retrieval
5. Test error handling
6. Test webhook delivery (if used)

Complete Migration Example

V1 Code (Old)

import requests
import time

API_KEY = "your_v1_api_key"
BASE_URL = "https://api.scriptix.io/api/v1"

def transcribe_file_v1(file_path, language="en"):
    # Upload and transcribe
    response = requests.post(
        f"{BASE_URL}/transcribe",
        params={"api_key": API_KEY},
        files={"file": open(file_path, "rb")},
        data={"language": language}
    )

    job_id = response.json()["id"]

    # Poll for completion
    while True:
        status_response = requests.get(
            f"{BASE_URL}/status/{job_id}",
            params={"api_key": API_KEY}
        )

        status = status_response.json()["status"]

        if status == "completed":
            # Get result
            result_response = requests.get(
                f"{BASE_URL}/result/{job_id}",
                params={"api_key": API_KEY}
            )
            return result_response.json()["transcript"]
        elif status == "failed":
            raise Exception("Transcription failed")

        time.sleep(5)

# Usage
transcript = transcribe_file_v1("audio.mp3", "en")
print(transcript)

V3 Code (New)

import requests
import time

API_KEY = "your_v3_api_key"
BASE_URL = "https://api.scriptix.io/api/v3/batch"

def transcribe_file_v3(file_path, language="en"):
    headers = {"Authorization": f"Bearer {API_KEY}"}

    # Step 1: Upload file
    with open(file_path, "rb") as f:
        upload_response = requests.post(
            f"{BASE_URL}/upload",
            headers=headers,
            files={"file": f}
        )

    if upload_response.status_code != 200:
        raise Exception(f"Upload failed: {upload_response.text}")

    file_id = upload_response.json()["file_id"]

    # Step 2: Create transcription job
    job_response = requests.post(
        f"{BASE_URL}/transcribe",
        headers=headers,
        json={
            "file_id": file_id,
            "language": language,
            "enable_diarization": True  # V3 feature
        }
    )

    if job_response.status_code != 200:
        raise Exception(f"Job creation failed: {job_response.text}")

    job_id = job_response.json()["job_id"]

    # Step 3: Poll for completion
    while True:
        status_response = requests.get(
            f"{BASE_URL}/jobs/{job_id}",
            headers=headers
        )

        job_data = status_response.json()
        status = job_data["status"]
        progress = job_data.get("progress", 0)

        print(f"Progress: {progress}%")

        if status == "completed":
            # Get result
            result_response = requests.get(
                f"{BASE_URL}/jobs/{job_id}/result",
                headers=headers
            )
            return result_response.json()
        elif status == "failed":
            error = job_data.get("error", "Unknown error")
            raise Exception(f"Transcription failed: {error}")

        time.sleep(5)

# Usage
result = transcribe_file_v3("audio.mp3", "en")
print(result["transcript"])

Feature Mapping

Parameters

V1 Parameter	V3 Parameter	Notes
language	language	Same usage
speaker_detection	enable_diarization	Renamed
N/A	glossary_id	New in V3
N/A	custom_model_id	New in V3
N/A	webhook_url	New in V3
N/A	enable_timestamps	New in V3

Status Values

V1 Status	V3 Status	Notes
queued	pending	Renamed
processing	processing	Same
completed	completed	Same
failed	failed	Same
N/A	cancelled	New in V3

Common Issues

Issue 1: 401 Unauthorized

Cause: Using V1 API key or incorrect authentication

Solution:

# Generate new V3 API key from dashboard
headers = {"Authorization": f"Bearer {V3_API_KEY}"}

Issue 2: 404 Not Found

Cause: Using V1 endpoints

Solution:

# Update to V3 endpoints
BASE_URL = "https://api.scriptix.io/api/v3/batch"

Issue 3: File Upload Fails

Cause: Files larger than 2GB

Solution: Use TUS upload protocol for large files

# See docs/api/Batch/TUSUpload.md for TUS implementation

Issue 4: Missing Fields in Response

Cause: Expecting V1 response format

Solution: Update response parsing for V3 structure

# V3 uses "job_id" instead of "id"
job_id = response.json()["job_id"]

New V3 Features

1. Webhooks

Receive notifications when jobs complete:

job_response = requests.post(
    f"{BASE_URL}/transcribe",
    headers=headers,
    json={
        "file_id": file_id,
        "language": "en",
        "webhook_url": "https://yourapp.com/webhook"
    }
)

2. Glossaries

Improve accuracy with custom terms:

job_response = requests.post(
    f"{BASE_URL}/transcribe",
    headers=headers,
    json={
        "file_id": file_id,
        "language": "en",
        "glossary_id": "glossary_123"
    }
)

3. Custom Models

Use trained models for better accuracy:

job_response = requests.post(
    f"{BASE_URL}/transcribe",
    headers=headers,
    json={
        "file_id": file_id,
        "language": "en",
        "custom_model_id": "model_456"
    }
}

4. Progress Tracking

Monitor job progress in real-time:

status_response = requests.get(
    f"{BASE_URL}/jobs/{job_id}",
    headers=headers
)
progress = status_response.json()["progress"]  # 0-100

Testing Your Migration

Test Checklist

• API key generated and tested
• Base URL updated to V3
• Authentication header implemented
• File upload working
• Job creation successful
• Status polling functional
• Result retrieval working
• Error handling updated
• Webhooks configured (if used)
• All file types tested
• All languages tested
• Production deployment plan ready

Sample Test Script

def test_v3_migration():
    """Test V3 API functionality"""

    print("Testing V3 API migration...")

    # Test 1: Upload file
    print("1. Testing file upload...")
    upload_result = upload_file("test_audio.mp3")
    assert upload_result["file_id"], "File upload failed"
    print("✓ File upload successful")

    # Test 2: Create job
    print("2. Testing job creation...")
    job = create_transcription_job(upload_result["file_id"])
    assert job["job_id"], "Job creation failed"
    print("✓ Job creation successful")

    # Test 3: Check status
    print("3. Testing status check...")
    status = get_job_status(job["job_id"])
    assert status["status"] in ["pending", "processing"], "Invalid status"
    print("✓ Status check successful")

    # Test 4: Wait for completion
    print("4. Waiting for job completion...")
    result = wait_for_completion(job["job_id"])
    assert result["transcript"], "No transcript in result"
    print("✓ Job completed successfully")

    print("\nAll tests passed! ✓")

test_v3_migration()

Support

Need help with migration?

• Review Batch API V3 Documentation
• Contact support via dashboard
• Check troubleshooting guide

Next Steps

• Batch API V3 Overview
• Authentication Guide
• Webhooks Setup
• Error Handling