API Documentation

Integrate Imvido's media extraction capabilities directly into your applications. Access 1000+ supported sites with a single REST API.

Authentication

All API requests require an API key to be passed in the Authorization header. You can generate an API key from your Developer Dashboard.

Authorization: Bearer imv_your_api_key_here

Core Endpoints

Create Extraction Job

Submit a media URL to begin extraction.

POST/api/jobs

Request Body (JSON)

{
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  // Optional: "audio" or "video"
  "format": "video" 
}

Response

{
  "id": "job_123abc",
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "status": "pending",
  "progress": 0,
  "createdAt": "2024-03-20T10:00:00Z"
}

Get Job Status

Poll the status of an existing job.

GET/api/jobs/:id

Response

{
  "id": "job_123abc",
  "status": "complete", // "pending", "extracting", "downloading", "complete", "failed"
  "progress": 100,
  "error": null,
  "assets": [
    {
      "id": "ast_456def",
      "type": "video",
      "sizeBytes": 1420500,
      "downloadUrl": "https://imvido.com/api/jobs/job_123abc/assets/ast_456def/download"
    }
  ]
}

Stream Job Status (SSE)

Receive real-time progress updates via Server-Sent Events.

GET/api/jobs/:id/stream

Connect to this endpoint using an EventSource client. Emits JSON payload events with progress updates from 0 to 100.

Code Example

A simple Node.js example to submit a job and poll for completion.

const API_KEY = "imv_your_api_key_here";
const API_URL = "https://imvido.com/api";

async function downloadVideo(url) {
  // 1. Submit Job
  const createRes = await fetch(`${API_URL}/jobs`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ url })
  });
  
  const job = await createRes.json();
  console.log("Job created:", job.id);

  // 2. Poll for completion
  while (true) {
    await new Promise(r => setTimeout(r, 2000)); // Wait 2s
    
    const statusRes = await fetch(`${API_URL}/jobs/${job.id}`, {
      headers: { "Authorization": `Bearer ${API_KEY}` }
    });
    
    const current = await statusRes.json();
    console.log(`Progress: ${current.progress}%`);
    
    if (current.status === "complete") {
      console.log("Download Ready:", current.assets[0].downloadUrl);
      break;
    }
    
    if (current.status === "failed") {
      console.error("Job failed:", current.error);
      break;
    }
  }
}

downloadVideo("https://www.youtube.com/watch?v=dQw4w9WgXcQ");

Loading…

Core Endpoints

Create Extraction Job

Submit a media URL to begin extraction.

POST/api/jobs

Request Body (JSON)

{
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  // Optional: "audio" or "video"
  "format": "video" 
}

Response

{
  "id": "job_123abc",
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "status": "pending",
  "progress": 0,
  "createdAt": "2024-03-20T10:00:00Z"
}

Get Job Status

Poll the status of an existing job.

GET/api/jobs/:id

Response

{
  "id": "job_123abc",
  "status": "complete", // "pending", "extracting", "downloading", "complete", "failed"
  "progress": 100,
  "error": null,
  "assets": [
    {
      "id": "ast_456def",
      "type": "video",
      "sizeBytes": 1420500,
      "downloadUrl": "https://imvido.com/api/jobs/job_123abc/assets/ast_456def/download"
    }
  ]
}

Stream Job Status (SSE)

Receive real-time progress updates via Server-Sent Events.

GET/api/jobs/:id/stream

Connect to this endpoint using an EventSource client. Emits JSON payload events with progress updates from 0 to 100.

Code Example

A simple Node.js example to submit a job and poll for completion.

const API_KEY = "imv_your_api_key_here";
const API_URL = "https://imvido.com/api";

async function downloadVideo(url) {
  // 1. Submit Job
  const createRes = await fetch(`${API_URL}/jobs`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ url })
  });
  
  const job = await createRes.json();
  console.log("Job created:", job.id);

  // 2. Poll for completion
  while (true) {
    await new Promise(r => setTimeout(r, 2000)); // Wait 2s
    
    const statusRes = await fetch(`${API_URL}/jobs/${job.id}`, {
      headers: { "Authorization": `Bearer ${API_KEY}` }
    });
    
    const current = await statusRes.json();
    console.log(`Progress: ${current.progress}%`);
    
    if (current.status === "complete") {
      console.log("Download Ready:", current.assets[0].downloadUrl);
      break;
    }
    
    if (current.status === "failed") {
      console.error("Job failed:", current.error);
      break;
    }
  }
}

downloadVideo("https://www.youtube.com/watch?v=dQw4w9WgXcQ");