API Documentation

Learn how to use the Y2MD API to convert YouTube videos to Markdown

Quick Start

1. Get API Token

First, login with your email to get your API token:

POST https://api.y2md.com/auth/email
Content-Type: application/json

{
  "email": "your@email.com",
  "password": "your-password"
}

API Reference

Convert YouTube Video

POST /vlm/v1/analyze-video

Request Body:

{
  "youtubeUrl": "https://www.youtube.com/watch?v=VIDEO_ID",
  "prompt": "Convert this video to markdown...",
  "model": "google/gemini-2.5-flash-lite",
  "useCache": true  // Optional, default true
}

Response:

{
  "result": "# Video Title\n\n## Summary\n...",
  "model": "google/gemini-2.5-flash-lite",
  "cost": 17,
  "fromCache": true,  // Cache hit indicator
  "cacheInfo": {
    "cachedAt": "2024-01-15T10:30:00Z",
    "cacheHitCount": 5
  },
  "metadata": {
    "title": "Video Title",
    "duration": "10:30"
  }
}

Authentication

Method 1: JWT Token (Web Login)

For web applications, token is automatically obtained after login.

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Method 2: API Key (Programmatic Access)

For scripts, CLI tools, and backend integrations. Create API Keys in your console.

Header Method (Recommended):

Authorization: Bearer os_ak_YOUR_API_KEY_HERE

Query Parameter Method:

?api_key=os_ak_YOUR_API_KEY_HERE

💡 Tip: Create and manage your API Keys in the "API Keys" page in your console.

Code Examples

Using JWT Token (Web)

const response = await fetch('https://api.opensota.ai/vlm/v1/analyze-video', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${jwtToken}`  // Your JWT token from login
  },
  body: JSON.stringify({
    youtubeUrl: 'https://www.youtube.com/watch?v=VIDEO_ID',
    prompt: 'Convert this video to markdown',
    model: 'google/gemini-2.5-flash-lite',
    useCache: true
  })
});

const data = await response.json();
console.log('Result:', data.result);
console.log('Credits used:', data.cost);
console.log('From cache:', data.fromCache);

Using API Key (Script)

const response = await fetch('https://api.opensota.ai/vlm/v1/analyze-video', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer os_ak_YOUR_API_KEY_HERE'  // Your API key
  },
  body: JSON.stringify({
    youtubeUrl: 'https://www.youtube.com/watch?v=VIDEO_ID',
    prompt: 'Convert this video to markdown',
    model: 'google/gemini-2.5-flash-lite',
    useCache: true
  })
});

const data = await response.json();
console.log('Result:', data.result);
console.log('Credits used:', data.cost);

Python

import requests
import os

API_KEY = os.environ.get('Y2MD_API_KEY')
API_URL = 'https://api.opensota.ai'

response = requests.post(
    f'{API_URL}/vlm/v1/analyze-video',
    headers={
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    },
    json={
        'youtubeUrl': 'https://www.youtube.com/watch?v=VIDEO_ID',
        'prompt': 'Convert this video to markdown',
        'model': 'google/gemini-2.5-flash-lite',
        'useCache': True
    }
)

data = response.json()
print(f"Result: {data['result']}")
print(f"Cost: {data['cost']} credits")

cURL

curl -X POST 'https://api.opensota.ai/vlm/v1/analyze-video' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer os_ak_YOUR_API_KEY_HERE' \
  -d '{
    "youtubeUrl": "https://www.youtube.com/watch?v=VIDEO_ID",
    "prompt": "Convert this video to markdown",
    "model": "google/gemini-2.5-flash-lite",
    "useCache": true
  }'