TwitterDownTwitterDown

TwitterDown API Docs

TwitterDownon 10 days ago

TwitterDown API Development Documentation

Overview

TwitterDown API v1 provides programmatic access to extract video information from Twitter/X links. This API allows developers to integrate Twitter video parsing capabilities into their applications.

Base URL

https://twitterdown.com/api/v1

Authentication

All API requests require authentication using an API key. You must include your API key in the Authorization header of every request.

API Key Format

Authorization: Bearer YOUR_API_KEY

Obtaining an API Key

  1. Create an account on TwitterDown.
  2. Purchase a premium subscription.
  3. Navigate to the API Key section in your dashboard.
  4. Create a new API key.

Note: API access is only available for premium users.

Rate Limiting

  • Requests per minute: 60
  • Requests per hour: 1,000
  • Requests per day: 10,000

Rate limit headers are included in all responses:

  • X-RateLimit-Limit: The request limit for the current time window.
  • X-RateLimit-Remaining: The number of requests remaining in the current window.
  • X-RateLimit-Reset: The Unix timestamp when the rate limit will reset.

Endpoints

1. Parse Twitter Video URL

Extracts video information from a Twitter/X URL.

Endpoint Address: POST /twitter

Request

Request Headers:

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

Request Body:

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

Parameters:

Parameter Type Required Description
url string Yes A valid Twitter/X tweet URL containing a video

Response

Successful Response (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": "This is an example tweet content with a video",
    "username": "username",
    "statusId": "1234567890123456789",
    "processed_at": "2024-01-01T12:00:00.000Z"
  }
}

Response Fields:

Field Name Type Description
code integer Response code (0 = success, -1 = error)
message string Response message
data object Response data
thumbnail string URL of the tweet thumbnail (can be null)
videos array Array of available video formats
text string The text content of the tweet
username string Twitter username
statusId string The tweet's status ID
processed_at string ISO 8601 timestamp of when it was processed

Video Object Fields:

Field Name Type Description
resolution string Video resolution (e.g., "720p", "360p")
quality string Video quality (e.g., "HD", "SD")
url string Direct download URL for the video

2. API Documentation

Retrieves API documentation and usage information.

Endpoint Address: GET /twitter

Response

Returns the complete API documentation in JSON format, including endpoint information, authentication requirements, and examples.

Error Handling

Error Response Format

{
  "code": -1,
  "message": "Error description"
}

HTTP Status Codes

Status Code Description
200 Success
400 Bad Request - Invalid parameters
401 Unauthorized - Missing or invalid API key
403 Forbidden - Premium subscription required
422 Unprocessable Entity - Unable to parse URL
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error

Common Error Messages

Error Message Cause
Missing API key Authorization header not provided
Invalid API key API key not found or expired
API access is only available for premium users Non-premium user attempting to access the API
URL parameter is required URL missing in the request body
Invalid Twitter/X URL format Incorrect or unsupported URL format
No video found The tweet does not contain video content

Examples

cURL Example

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 Example

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('Video found:', data.data.videos);
} else {
  console.error('Error:', data.message);
}

Python Example

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("Video found:", data["data"]["videos"])
else:
    print("Error:", data["message"])

PHP Example

<?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 "Video found: " . print_r($data['data']['videos'], true);
} else {
    echo "Error: " . $data['message'];
}
?>

Best Practices

URL Format Support

The API supports the following URL formats:

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

Error Handling

Always check the code field in the response:

  • code: 0 indicates success
  • code: -1 indicates an error

Implement proper error handling in your application to gracefully manage API errors.

Rate Limiting

Monitor the rate limit headers in responses and implement a back-off strategy when approaching limits.

Security

  • Keep your API key secure; never expose it in client-side code.
  • Store API keys using environment variables.
  • Rotate API keys regularly.
  • Delete unused API keys.

Support

For API support and questions:

  • Email: support@twitterdown.com
  • Documentation: https://twitterdown.com/docs
  • Status Page: https://status.twitterdown.com

Changelog

Version 1.0.0 (2025-05-27)

  • Initial API release
  • Twitter/X video parsing
  • Premium user authentication
  • Rate limit implementation

Last updated: 2025-05-27