Media Probe

POST /v1/media/probe returns metadata about a remote media URL in a single round-trip. Use it to check audio duration before charging credits, show an ETA on your upload screen, display a preview card, or detect live streams early — without having to start a transcription job first.

When to use it

• Credit gating — compare duration_seconds against the user's remaining credits before starting a potentially expensive transcription.
• ETA display — show "This 2h 13m video will finish in about 4 minutes" on your upload UI.
• Live-stream detection — reject or warn when is_live is true, since live streams transcribe unreliably.
• Preview cards — fetch the title, uploader, and thumbnail to render a confirmation card before the user submits.

Quickstart

Send a JSON body with the URL you want to inspect:

curl "https://asr.lesan.ai/v1/media/probe" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"}'

Example response:

{
  "object": "media_probe",
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "source": "youtube",
  "extractor": "youtube",
  "title": "Rick Astley - Never Gonna Give You Up (Official Music Video)",
  "uploader": "Rick Astley",
  "duration_seconds": 213.0,
  "thumbnail_url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
  "upload_date": "2009-10-25",
  "is_live": false,
  "language": "en",
  "file_size_bytes": null,
  "content_type": null,
  "warnings": [],
  "cached": false,
  "probed_at": "2026-04-23T12:34:56Z",
  "metadata": {
    "view_count": 1500000000,
    "like_count": 16000000,
    "description": "The official video..."
  }
}

Request

Response

Warnings

Probes return a 200 response even when something is non-ideal. Inspect the warnings array and surface matches to the end-user:

• live_stream — is_live is true. Transcription will likely run but the boundary is unstable; warn the user or block if you don't support it.
• duration_unknown — the container did not expose duration. You still receive file_size_bytes and title, so you can gate by size or prompt the user to confirm.
• very_long — duration is unusually large (far above the per-job audio cap). Consider splitting or rejecting.
• age_restricted — the source reports the media requires authentication (sign-in, subscriber-only, premium-only). Our crawler will likely fail to download it when you transcribe; warn the user up front.

Supported sources

yt-dlp platforms — duration, title, uploader, thumbnail, live flag, language, and extractor-specific extras:

• YouTube, Twitter/X, TikTok, Vimeo, SoundCloud
• Facebook, Instagram, Twitch, Reddit
• Anything else yt-dlp's "generic" extractor can resolve

Direct audio/video URLs — probed via HEAD (for size and content-type) plus ffprobe (for duration). Supports the same container formats as file uploads — see the Audio Formats reference.

Caching

Successful probes are cached for 5 minutes (configurable server-side), keyed by normalized URL. A cached response carries cached: true so your client can tell whether values like view_count or is_live may be slightly stale. The probed_at timestamp is re-stamped to the current server time even on cache hits, so it always reflects when the client observed the data.

Errors

The probe endpoint emits the standard Stripe-style error envelope used across the API. See the Error Codes guide for full handling guidance.

Credit-gating example

The canonical pattern: probe → decide → transcribe. The snippets below check duration against the user's remaining credits before enqueuing a job.

import requests


API = "https://asr.lesan.ai"
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}


def submit_if_affordable(url: str, credit_seconds_remaining: float):
    # 1. Probe
    probe = requests.post(
        f"{API}/v1/media/probe", headers=HEADERS, json={"url": url}
    )
    probe.raise_for_status()
    info = probe.json()


    if "live_stream" in info["warnings"]:
        raise ValueError("Live streams are not supported")


    duration = info["duration_seconds"]
    if duration is None:
        # duration_unknown — fall back to size-based heuristic or ask the user
        return {"status": "needs_confirmation", "probe": info}


    if duration > credit_seconds_remaining:
        return {
            "status": "insufficient_credits",
            "needed_seconds": duration,
            "available_seconds": credit_seconds_remaining,
            "probe": info,
        }


    # 2. Transcribe
    job = requests.post(
        f"{API}/v1/transcriptions",
        headers=HEADERS,
        json={"audio_url": url, "language": "auto", "mode": "async"},
    ).json()


    return {"status": "queued", "job_id": job["id"], "probe": info}

See also

• ASR Guide — submit transcription jobs once you've probed.
• Audio Formats — supported containers for direct URL probing.
• Error Codes — full list of error types and retry strategies.
• Rate Limits — probe requests count toward your read-scope quota.