Yoinku API

ベースURL

https://yoinku.com/api/v1

認証

すべてのリクエストに x-api-key ヘッダーでAPIキーが必要です。キーは無料で、アカウント登録後にアカウントページから発行できます。APIでのダウンロードはWebと共通で、アカウントごとに1日5回までです。

curl -H "x-api-key: yk_..." "https://yoinku.com/api/v1/info?url=https://youtu.be/dQw4w9WgXcQ"

エンドポイント

curl -H "x-api-key: yk_..." \
  "https://yoinku.com/api/v1/info?url=https://youtu.be/dQw4w9WgXcQ"

{
  "ok": true,
  "data": {
    "id": "dQw4w9WgXcQ",
    "platform": "youtube",
    "title": "Example video",
    "durationSeconds": 213,
    "thumbnailUrl": "https://i.ytimg.com/...",
    "formats": [
      { "id": "v-1080", "kind": "video", "container": "mp4",
        "quality": "1080p", "height": 1080,
        "hasVideo": true, "hasAudio": true },
      { "id": "a-mp3", "kind": "audio", "container": "mp3",
        "quality": "MP3", "hasVideo": false, "hasAudio": true }
    ]
  }
}

curl -H "x-api-key: yk_..." \
  "https://yoinku.com/api/v1/meta?url=https://youtu.be/dQw4w9WgXcQ"

{
  "ok": true,
  "data": {
    "id": "dQw4w9WgXcQ",
    "platform": "youtube",
    "title": "Example video",
    "description": "…",
    "author": "Example channel",
    "durationSeconds": 213,
    "uploadDate": "2009-10-25",
    "viewCount": 1234567,
    "likeCount": 45678,
    "tags": ["example"],
    "chapters": [
      { "title": "Intro", "startSeconds": 0, "endSeconds": 42 }
    ],
    "subtitleLanguages": { "manual": ["en"], "auto": ["en-orig", "ja"] }
  }
}

curl -H "x-api-key: yk_..." \
  "https://yoinku.com/api/v1/transcript?url=https://youtu.be/dQw4w9WgXcQ&lang=en"

{
  "ok": true,
  "data": {
    "id": "dQw4w9WgXcQ",
    "lang": "en",
    "source": "manual",
    "text": "We're no strangers to love …",
    "chunks": [
      { "startSeconds": 18.6, "durationSeconds": 3.4,
        "text": "We're no strangers to love" }
    ],
    "availableLanguages": { "manual": ["en"], "auto": ["en-orig", "ja"] }
  }
}

# Get a short-lived download URL (JSON)
curl -H "x-api-key: yk_..." \
  "https://yoinku.com/api/v1/download?url=https://youtu.be/dQw4w9WgXcQ&format=v-720"

# …or download the file directly
curl -L -o video.mp4 -H "x-api-key: yk_..." \
  "https://yoinku.com/api/v1/download?url=https://youtu.be/dQw4w9WgXcQ&format=v-720&redirect=1"

{
  "ok": true,
  "url": "https://<bucket>.r2.cloudflarestorage.com/...",
  "filename": "Example video.mp4",
  "expiresInSeconds": 3600
}

フォーマットID

info レスポンスの formats 配列からIDを選びます。動画IDは v-1080・v-720・v-360（高さ基準）、音声IDは a-mp3・a-m4a です。

フェアユース

リクエストはIPごとに1分あたり5回まで、ダウンロードはアカウントごとに1日5回まで（Webでのダウンロードと共通）です。超過するとRetry-Afterヘッダー付きのHTTP 429を返します。可能な範囲でレスポンスをキャッシュし、節度あるご利用をお願いします。

エラー

失敗時は { "ok": false, "error": { "code", "message" } } の形で、対応するHTTPステータスを返します: 400（入力不正）・401（APIキーなし/無効）・404（見つからない）・422（非対応または失敗）・429（レート制限または1日上限超過）。