TwitterDown API 文件

TwitterDown API 開發文件

概述

TwitterDown API v1 提供程式化訪問，用於從 Twitter/X 連結中提取影片資訊。此 API 允許開發者將 Twitter 影片解析功能整合到他們的應用程式中。

基礎 URL

https://twitterdown.com/api/v1

身份驗證

所有 API 請求都需要使用 API 密鑰進行身份驗證。您必須在每個請求的 Authorization 標頭中包含您的 API 密鑰。

API 密鑰格式

Authorization: Bearer 您的_API_密鑰

取得 API 密鑰

在 TwitterDown 上建立帳戶。
購買高級訂閱。
導航到儀表板中的 API 密鑰部分。
建立新的 API 密鑰。

注意： API 訪問僅對高級用戶開放。

速率限制

每分鐘請求數： 60
每小時請求數： 1,000
每日請求數： 10,000

所有響應中都包含速率限制標頭：

X-RateLimit-Limit：每個時間窗口的請求限制。
X-RateLimit-Remaining：當前窗口中剩餘的請求數。
X-RateLimit-Reset：速率限制重置時的 Unix 時間戳。

接口

1. 解析 Twitter 影片 URL

從 Twitter/X URL 中提取影片資訊。

接口地址： POST /twitter

請求

請求標頭：

Content-Type: application/json
Authorization: Bearer 您的_API_密鑰

請求體：

{
  "url": "https://x.com/username/status/1234567890123456789"
}

參數：

參數名	類型	必需	描述
`url`	string	是	包含影片的有效 Twitter/X 推文 URL

響應

成功響應 (200 OK)：

{
  "code": 0,
  "message": "ok",
  "data": {
    "thumbnail": "https://pbs.twimg.com/amplify_video_thumb/1234567890123456789/img/ExampleThumbnail.jpg",
    "videos": [
      {
        "resolution": "720p",
        "quality": "HD",
        "url": "https://video.twimg.com/amplify_video/1234567890123456789/vid/avc1/1280x720/ExampleVideoHD.mp4?tag=21"
      },
      {
        "resolution": "360p",
        "quality": "SD",
        "url": "https://video.twimg.com/amplify_video/1234567890123456789/vid/avc1/640x360/ExampleVideoSD.mp4?tag=21"
      },
      {
        "resolution": "270p",
        "quality": "SD",
        "url": "https://video.twimg.com/amplify_video/1234567890123456789/vid/avc1/480x270/ExampleVideoLow.mp4?tag=21"
      }
    ],
    "text": "這是一個範例推文內容，包含影片",
    "username": "username",
    "statusId": "1234567890123456789",
    "processed_at": "2024-01-01T12:00:00.000Z"
  }
}

響應字段：

字段名	類型	描述
`code`	integer	響應代碼 (0 = 成功, -1 = 錯誤)
`message`	string	響應消息
`data`	object	響應數據
`thumbnail`	string	推文縮略圖 URL (可為空)
`videos`	array	可用影片格式陣列
`text`	string	推文文本內容
`username`	string	Twitter 用戶名
`statusId`	string	推文狀態 ID
`processed_at`	string	處理時間的 ISO 8601 時間戳

影片對象字段：

字段名	類型	描述
`resolution`	string	影片解析度 (例如："720p", "360p")
`quality`	string	影片品質 (例如："HD", "SD")
`url`	string	影片的直接下載 URL

2. API 文件

獲取 API 文件和使用資訊。

接口地址： GET /twitter

響應

返回 JSON 格式的完整 API 文件，包括接口資訊、身份驗證要求和範例。

錯誤處理

錯誤響應格式

{
  "code": -1,
  "message": "錯誤描述"
}

HTTP 狀態碼

狀態碼	描述
`200`	成功
`400`	錯誤請求 - 無效參數
`401`	未經授權 - 缺少或無效的 API 密鑰
`403`	禁止訪問 - 需要高級訂閱
`422`	無法處理的實體 - 無法解析 URL
`429`	請求過多 - 超出速率限制
`500`	內部伺服器錯誤

常見錯誤訊息

錯誤訊息	原因
`Missing API key`	未提供 Authorization 標頭
`Invalid API key`	API 密鑰未找到或已失效
`API access is only available for premium users`	非高級用戶嘗試訪問 API
`URL parameter is required`	請求體中缺少 URL
`Invalid Twitter/X URL format`	URL 格式錯誤或不支持
`No video found`	推文不包含影片內容

範例

cURL 範例

curl --location --request POST 'https://twitterdown.com/api/v1/twitter' \
  --header 'Authorization: Bearer sk-1234567890abcdef123456789012345678' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "url": "https://x.com/username/status/1234567890123456789"
  }'

JavaScript 範例

const response = await fetch('https://twitterdown.com/api/v1/twitter', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer sk-1234567890abcdef123456789012345678'
  },
  body: JSON.stringify({
    url: 'https://x.com/username/status/1234567890123456789'
  })
});

const data = await response.json();

if (data.code === 0) {
  console.log('找到影片:', data.data.videos);
} else {
  console.error('錯誤:', data.message);
}

Python 範例

import requests

url = "https://twitterdown.com/api/v1/twitter"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer sk-1234567890abcdef123456789012345678"
}
payload = {
    "url": "https://x.com/username/status/1234567890123456789"
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()

if data["code"] == 0:
    print("找到影片:", data["data"]["videos"])
else:
    print("錯誤:", data["message"])

PHP 範例

<?php
$url = 'https://twitterdown.com/api/v1/twitter';
$headers = [
    'Content-Type: application/json',
    'Authorization: Bearer sk-1234567890abcdef123456789012345678'
];
$payload = json_encode([
    'url' => 'https://x.com/username/status/1234567890123456789'
]);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);

if ($data['code'] === 0) {
    echo "找到影片: " . print_r($data['data']['videos'], true);
} else {
    echo "錯誤: " . $data['message'];
}
?>

最佳實踐

URL 格式支援

API 支援以下 URL 格式：

https://twitter.com/username/status/1234567890
https://x.com/username/status/1234567890
https://mobile.twitter.com/username/status/1234567890

錯誤處理

始終檢查響應中的 code 字段：

code: 0 表示成功
code: -1 表示錯誤

在您的應用程式中實施適當的錯誤處理，以優雅地處理 API 錯誤。

速率限制

監控響應中的速率限制標頭，並在接近限制時實施退避策略。

安全性

保護您的 API 密鑰安全，永遠不要在客戶端程式碼中暴露它們。
使用環境變數儲存 API 密鑰。
定期輪換 API 密鑰。
刪除未使用的 API 密鑰。

支援

如有 API 支援和問題：

電子郵件： support@twitterdown.com
文件： https://twitterdown.com/docs
狀態頁面： https://status.twitterdown.com

更新日誌

版本 1.0.0 (2025-05-27)

初始 API 發布
Twitter/X 影片解析
高級用戶身份驗證
速率限制實現

最後更新：2025-05-27