Skip to main content
Pull public YouTube videos into Horizon, producing transcripts, captions, and structural context without downloading the file yourself. Perfect for analyzing talks, tutorials, or marketing content published on YouTube.

​
Request body

  • sourceUrl — Canonical YouTube video URL or share link. Required if file is not provided.
  • file — Optional uploaded video file corresponding to the YouTube content (multipart/form-data).
  • sourceName — Optional label stored with the transcript.
  • options — Optional object. Supported keys:
    • transcriptionModel — Preferred transcription backend (whisper-large-v3, etc.).
    • includeCaptions — Boolean; merge official closed captions when available (default true).
    • captureChapters — Boolean; capture YouTube chapter markers in the output (default true).
    • segmentLength — Target characters per chunk (default 800).
  • webhookUrl — Optional HTTPS URL Horizon should call when the extraction finishes.

​
Sample request

curl https://api.worklet.cloud/v1/extract/youtube \
  -H "Content-Type: application/json" \
  -d '{
    "sourceUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "sourceName": "Horizon Launch Keynote",
    "options": {
      "transcriptionModel": "whisper-large-v3",
      "includeCaptions": true,
      "captureChapters": true,
      "segmentLength": 750
    }
  }'

# or upload the video manually

curl https://api.worklet.cloud/v1/extract/youtube \
  -H "Content-Type: application/json" \
  -d '{
    "file": "data:video/mp4;base64,AAAAIGZ0eX...",
    "sourceName": "Horizon Launch Keynote",
    "options": {
      "transcriptionModel": "whisper-large-v3",
      "includeCaptions": true,
      "captureChapters": true,
      "segmentLength": 750
    }
  }'

​
Response

Returns 202 Accepted with jobId, status, statusUrl, and optional etaSeconds. When complete, result includes transcript chunks, YouTube details (title, channel, publish date), and chapter markers when enabled.

​
Notes

  • Only public or unlisted videos are supported; private videos require exporting and using the /extract/video endpoint instead.
  • Horizon downloads the video in the background; no additional hosting required.
  • Captions are merged with the transcription by default; disable via includeCaptions: false if you want raw ASR output.
  • Poll GET /jobs/{jobId} (same as the statusUrl) to monitor progress or fetch transcripts and accompanying details later.
  • To upload a video file manually, send multipart/form-data with a file field instead of sourceUrl.

​
x402 flow

YouTube extraction is billed through Coinbase’s x402 protocol. When payment is required, expect: 
HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "network": "base-sepolia",
      "maxAmountRequired": "240000",
      "resource": "POST /extract/youtube",
      "description": "Horizon YouTube extraction",
      "mimeType": "application/json",
      "payTo": "0xYourReceivingWallet",
      "maxTimeoutSeconds": 900,
      "asset": "0xYourUSDCContract",
      "extra": {
        "name": "USDC",
        "version": "1"
      }
    }
  ],
  "error": null
}
Forward the challenge to your facilitator, complete /verify and /settle, then replay the request with the facilitator-issued Base64 token inside X-PAYMENT. Horizon resumes processing and returns settlement details in X-PAYMENT-RESPONSE.