Skip to main content

​
Endpoint

POST /v1/extract
Submits a new audio extraction job. The request is processed asynchronously and returns immediately with a job ID.

​
Authentication

This endpoint requires an API key. 
X-API-Key: YOUR_API_KEY
Requests without a valid API key will be rejected.

​
Description

The Create Extraction Job endpoint queues a background job that:
  1. Validates the request
  2. Downloads the video (if source is a URL)
  3. Analyzes video properties
  4. Extracts and converts audio
  5. Stores the output temporarily for download
The job lifecycle can be tracked using the Job Status API or webhooks.

​
Request Body

The request body must be JSON and include source and output objects.

​
Required Fields

FieldTypeDescription
sourceobjectVideo input configuration
outputobjectAudio output configuration

​
Optional Fields

FieldTypeDescription
optionsobjectJob-level options (webhook, filename, priority)

​
Source Object

Defines where the video comes from. 
{
  "type": "url",
  "url": "https://example.com/video.mp4"
}
FieldRequiredDescription
type✅url or upload
url✅ (if type=url)Public video URL
file❌File identifier (upload – future)

​
Output Object

Controls audio format and quality. 
{
  "format": "mp3",
  "quality": "medium",
  "normalize": true
}
FieldRequiredDescription
format✅mp3, aac, flac, wav, ogg, opus
quality❌low, medium, high, extreme
bitrate❌Custom bitrate (e.g. 192k)
normalize❌Loudness normalization
preserveMetadata❌Preserve original metadata
📌 If bitrate is provided, it overrides quality.

​
Options Object

Optional job-level settings. 
{
  "filename": "my-audio-file",
  "webhook": "https://example.com/webhook",
  "priority": "high"
}
FieldDescription
filenameCustom output filename
webhookWebhook URL for job events
prioritylow, normal, high

​
Example Requests

​
Basic MP3 Extraction

{
  "source": {
    "type": "url",
    "url": "https://example.com/video.mp4"
  },
  "output": {
    "format": "mp3",
    "quality": "medium"
  }
}

​
High-Quality FLAC with Metadata

{
  "source": {
    "type": "url",
    "url": "https://example.com/video.mp4"
  },
  "output": {
    "format": "flac",
    "normalize": true,
    "preserveMetadata": true
  },
  "options": {
    "filename": "studio-audio",
    "webhook": "https://example.com/webhook"
  }
}

​
Custom Bitrate MP3

{
  "source": {
    "type": "url",
    "url": "https://example.com/video.mp4"
  },
  "output": {
    "format": "mp3",
    "bitrate": "256k"
  }
}

​
Response

​
Success (202 Accepted)

{
  "success": true,
  "data": {
    "jobId": "job_a1b2c3d4e5f6g7h8",
    "status": "queued",
    "estimatedTime": 45,
    "statusUrl": "/v1/status/job_a1b2c3d4e5f6g7h8"
  },
  "message": "Job queued successfully"
}
FieldDescription
jobIdUnique job identifier
statusInitial job status
estimatedTimeEstimated seconds to completion
statusUrlEndpoint to check progress

​
Error Responses

​
400 – Bad Request

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid output format"
  }
}

​
503 – Service Unavailable

{
  "success": false,
  "error": {
    "code": "QUEUE_FULL",
    "message": "Processing queue is currently full"
  }
}

​
Limits & Constraints

  • Max file size: 5 GB
  • Max URL length: 2048 characters
  • Files retained: 24 hours
  • Upload source: planned (not yet available)

​
Best Practices

  • ✅ Prefer webhooks over polling
  • 🔁 Retry failures with exponential backoff
  • 📦 Use batch API for multiple files
  • 🔐 Keep API keys secure
  • ⏳ Expect longer processing for large videos

​
Next Step

Get Job Status

Track progress and retrieve job details.
© Converso Empire. All rights reserved.