API Endpoints

Complete reference for all Voxmin API endpoints — jobs, downloads, pricing, and account.

API Endpoints

Jobs

Create a Job

POST /auth/jobs/me

Create an asynchronous job. The job is queued and processed in the background.

Request Body

Field	Type	Required	Description
`type`	`JobType`	Yes	The type of job to create (see Job Types)
`payload`	object	Yes	Job-specific parameters
`metadata`	object	No	Arbitrary metadata stored with the job

Example: YouTube to Karaoke Video

{
    "type": "YOUTUBE_VIDEO_TO_KARAOKE_VIDEO",
    "payload": {
        "videoId": "dQw4w9WgXcQ"
    }
}

Example: YouTube to Lyrical Karaoke (with AI lyrics + translation)

{
    "type": "YOUTUBE_VIDEO_TO_LYRICAL_KARAOKE_VIDEO",
    "payload": {
        "videoId": "dQw4w9WgXcQ",
        "enable_lyrics": true,
        "enable_karaoke": true,
        "translate": true,
        "translate_to": "spanish",
        "font_name": "Arial",
        "font_size": 50,
        "base_color": "#ffffff",
        "highlight_color": "#ffff00",
        "outline_size": 3.0,
        "shadow_size": 1.0,
        "overlay_color": "#000000",
        "overlay_opacity": 0.7,
        "use_video": true
    }
}

Response 201 Created

{
    "id": 142,
    "userId": 5,
    "type": "YOUTUBE_VIDEO_TO_KARAOKE_VIDEO",
    "status": "PENDING",
    "estimatedDebitAmount": "40",
    "payload": { "videoId": "dQw4w9WgXcQ" },
    "createdAt": "2026-06-07T00:00:00.000Z",
    "updatedAt": "2026-06-07T00:00:00.000Z"
}

Upload a File Job

POST /auth/jobs/me/upload
Content-Type: multipart/form-data

Upload a media file and create a karaoke or lyrical video job.

Form Fields

Field	Type	Required	Description
`type`	`JobType`	Yes	Upload job type
`file`	binary	Yes	The media file (video/audio)
`background`	binary	No	Background image for lyrical videos
`enable_lyrics`	bool	No	Generate AI lyrics
`enable_karaoke`	bool	No	Perform vocal removal
`translate`	bool	No	Translate lyrics
`translate_to`	string	No	Target language (e.g. "spanish")
`font_name`	string	No	Font family for lyrics
`font_size`	int	No	Font size in pixels
`base_color`	string	No	Un-sung lyric color (hex recommended, e.g. `0xFFFFFF`)
`highlight_color`	string	No	Active lyric color (hex recommended, e.g. `0xFFFF00`)
`outline_size`	float	No	Text outline thickness
`shadow_size`	float	No	Drop shadow depth
`overlay_color`	string	No	Background tint color (hex recommended, e.g. `0x000000`)
`overlay_opacity`	float	No	Tint transparency (0–1)
`use_video`	bool	No	Use original video as background

Example

curl -X POST https://api.voxmin.com/auth/jobs/me/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "type=UPLOAD_VIDEO_TO_KARAOKE_VIDEO" \
  -F "[email protected]"

List Your Jobs

GET /auth/jobs/me

Returns a paginated list of your jobs, newest first.

Query Parameters

Param	Type	Default	Description
`skip`	int	`0`	Number of records to skip
`limit`	int	`25`	Max records to return (1–100)
`status`	`JobStatus`	—	Filter by status
`type`	`JobType`	—	Filter by job type

Response

{
    "items": [
        {
            "id": 142,
            "type": "YOUTUBE_VIDEO_TO_KARAOKE_VIDEO",
            "status": "SUCCEEDED",
            "createdAt": "2026-06-07T00:00:00.000Z",
            "completedAt": "2026-06-07T00:02:00.000Z"
        }
    ],
    "total": 47
}

Get Job Detail

GET /auth/jobs/me/:id

Returns full details for a single job including payload, result, and error information.

Response

{
    "id": 142,
    "type": "YOUTUBE_VIDEO_TO_KARAOKE_VIDEO",
    "status": "SUCCEEDED",
    "payload": { "videoId": "dQw4w9WgXcQ" },
    "result": { "storageKey": "jobs/142/output.mp4", "mimeType": "video/mp4" },
    "error": null,
    "createdAt": "2026-06-07T00:00:00.000Z",
    "startedAt": "2026-06-07T00:00:05.000Z",
    "completedAt": "2026-06-07T00:02:00.000Z"
}

Get Download Link

GET /auth/jobs/me/:id/download-link

Generate a temporary download URL for a completed job's output file.

Response

{
    "jobId": 142,
    "downloadUrl": "https://storage.voxmin.com/jobs/142/output.mp4?token=...",
    "expiresAt": "2026-06-07T00:17:00.000Z",
    "expiresInSeconds": 900,
    "mimeType": "video/mp4",
    "size": 48210492
}

The download URL is valid for 15 minutes.

Account

Get Credit Balance

GET /auth/users/credits/balance

Response

{
    "balance": "2080"
}

Get Job Pricing

GET /auth/job-pricing-configs/prices

Response

{
    "YOUTUBE_VIDEO_TO_KARAOKE_VIDEO": 40,
    "YOUTUBE_VIDEO_TO_KARAOKE_AUDIO": 30,
    "YOUTUBE_VIDEO_TO_LYRICAL_KARAOKE_VIDEO": 55,
    "UPLOAD_VIDEO_TO_KARAOKE_VIDEO": 30,
    "UPLOAD_AUDIO_TO_LYRICAL_VIDEO": 25
}

Polling for Job Completion

Jobs are asynchronous. Poll the job detail endpoint until the status is terminal:

async function waitForJob(jobId, apiKey, pollIntervalMs = 3000) {
    while (true) {
        const res = await fetch(`https://api.voxmin.com/auth/jobs/me/${jobId}`, {
            headers: { Authorization: `Bearer ${apiKey}` }
        });
        const job = await res.json();

        if (['SUCCEEDED', 'FAILED', 'CANCELLED'].includes(job.status)) {
            return job;
        }
        await new Promise((r) => setTimeout(r, pollIntervalMs));
    }
}

// Usage
const job = await createKaraokeJob('dQw4w9WgXcQ');
const result = await waitForJob(job.id, apiKey);

if (result.status === 'SUCCEEDED') {
    const link = await getDownloadLink(result.id, apiKey);
    console.log('Download:', link.downloadUrl);
}

Job Statuses

Status	Meaning
`PENDING`	Job created, waiting to be queued
`QUEUED`	In the processing queue
`RUNNING`	Currently being processed
`SUCCEEDED`	Completed successfully — download available
`FAILED`	Processing failed — check `error` field
`CANCELLED`	Cancelled by user or system
`PAUSED`	Paused, eligible for retry

Authentication

How to authenticate requests to the Voxmin API using API keys.

Job Types

Complete reference of all Voxmin job type enums, their categories, credit costs, and payload requirements.

What developers say about us

From developers integrating the Voxmin API into their applications.

“The REST API is well-documented. We built a batch processor that handles 500+ tracks overnight for our venue clients.”

Marcus K.

Backend engineer, SingAlong Pro

“The translation API is surprisingly accurate for technical terms in song lyrics. We use it to generate multilingual lyric videos at scale.”

David C.

Full-stack developer, GlobalKaraoke

“API rate limits are generous. We process 10,000+ jobs monthly without hitting caps. The async job model fits our architecture perfectly.”

Jennifer M.

API integration specialist, MusicTech

“Integrated the API into our karaoke app — job polling is straightforward and the webhook support saved us from building our own queue system.”

Alex R.

Lead developer, KaraokeFlow