Documentación de Desarrollo de la API TwitterDown

Resumen#

La API TwitterDown v1 proporciona acceso programático para extraer información de video de enlaces de Twitter/X. Esta API permite a los desarrolladores integrar funciones de análisis de videos de Twitter en sus aplicaciones.

URL Base#

https://twitterdown.com/api/v1

Autenticación#

Todas las solicitudes a la API requieren autenticación utilizando una clave de API. Debe incluir su clave de API en el encabezado Authorization de cada solicitud.

Formato de la clave de API#

Authorization: Bearer TU_CLAVE_API

Obtención de una clave de API#

1. Cree una cuenta en TwitterDown.
2. Adquiera una suscripción premium.
3. Navegue a la sección "Clave de API" en su panel de control.
4. Cree una nueva clave de API.

Nota: El acceso a la API solo está disponible para usuarios premium.

Límites de Tasa (Rate Limiting)#

• Solicitudes por minuto: 60
• Solicitudes por hora: 1,000
• Solicitudes por día: 10,000

Los encabezados de límite de tasa se incluyen en todas las respuestas:

• X-RateLimit-Limit: El límite de solicitudes para la ventana de tiempo actual.
• X-RateLimit-Remaining: El número de solicitudes restantes en la ventana actual.
• X-RateLimit-Reset: La marca de tiempo Unix cuando se restablecerá el límite de tasa.

Puntos de Acceso (Endpoints)#

1. Analizar URL de video de Twitter#

Extrae información de video de una URL de Twitter/X.

Dirección del punto de acceso: POST /twitter

Solicitud

Encabezados de Solicitud:

Content-Type: application/json
Authorization: Bearer TU_CLAVE_API

Cuerpo de la Solicitud (Request Body):

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

Parámetros:

Parámetro	Tipo	Requerido	Descripción
url	string	Sí	Una URL de tweet de Twitter/X válida que contenga un video

Respuesta

Respuesta Exitosa (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": "Este es un ejemplo de contenido de tweet con un video",
    "username": "username",
    "statusId": "1234567890123456789",
    "processed_at": "2024-01-01T12:00:00.000Z"
  }
}

Campos de Respuesta:

Nombre del Campo	Tipo	Descripción
code	integer	Código de respuesta (0 = éxito, -1 = error)
message	string	Mensaje de respuesta
data	object	Datos de respuesta
thumbnail	string	URL de la miniatura del tweet (puede ser nulo)
videos	array	Array de formatos de video disponibles
text	string	El contenido de texto del tweet
username	string	Nombre de usuario de Twitter
statusId	string	El ID de estado del tweet
processed_at	string	Marca de tiempo ISO 8601 de cuándo fue procesado

Campos del Objeto Video:

Nombre del Campo	Tipo	Descripción
resolution	string	Resolución del video (ej. "720p", "360p")
quality	string	Calidad del video (ej. "HD", "SD")
url	string	URL de descarga directa para el video

2. Documentación de la API#

Recupera la documentación de la API e información de uso.

Dirección del punto de acceso: GET /twitter

Respuesta

Devuelve la documentación completa de la API en formato JSON, incluyendo información de los puntos de acceso, requisitos de autenticación y ejemplos.

Manejo de Errores#

Formato de Respuesta de Error#

{
  "code": -1,
  "message": "Descripción del error"
}

Códigos de estado HTTP#

Código de Estado	Descripción
200	Éxito
400	Solicitud incorrecta - Parámetros inválidos
401	No autorizado - Clave de API faltante o inválida
403	Prohibido - Suscripción premium requerida
422	Entidad no procesable - No se pudo analizar la URL
429	Demasiadas solicitudes - Límite de tasa excedido
500	Error interno del servidor

Mensajes de error comunes#

Mensaje de Error	Causa
Missing API key	Encabezado Authorization no proporcionado
Invalid API key	Clave de API no encontrada o expirada
API access is only available for premium users	Usuario no premium intentando acceder a la API
URL parameter is required	Falta la URL en el cuerpo de la solicitud
Invalid Twitter/X URL format	Formato de URL incorrecto o no compatible
No video found	El tweet no contiene contenido de video

Ejemplos#

Ejemplo 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"
  }'

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

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

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

Mejores Prácticas#

Soporte de formatos de URL#

La API admite los siguientes formatos de URL:

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

Manejo de errores#

Siempre verifique el campo code en la respuesta:

• code: 0 indica éxito
• code: -1 indica un error

Implemente un manejo de errores adecuado en su aplicación para gestionar los errores de la API de manera elegante.

Límites de Tasa#

Supervise los encabezados de límite de tasa en las respuestas e implemente una estrategia de retroceso (back-off) cuando se acerque a los límites.

Seguridad#

• Mantenga su clave de API segura; nunca la exponga en el código del lado del cliente.
• Almacene las claves de API utilizando variables de entorno.
• Rote las claves de API regularmente.
• Elimine las claves de API no utilizadas.

Soporte#

Para soporte y preguntas sobre la API:

• Correo electrónico: [email protected]
• Documentación: https://twitterdown.com/docs
• Página de estado: https://status.twitterdown.com

Registro de Cambios (Changelog)#

Versión 1.0.0 (27 de mayo de 2025)#

• Lanzamiento inicial de la API
• Análisis de videos de Twitter/X
• Autenticación de usuarios premium
• Implementación de límites de tasa

Última actualización: 27 de mayo de 2025