API de X - Ayrshare API Documentation

X BYO API Keys

A partir del 31 de marzo de 2026, todas las operaciones de X/Twitter requerirán tus propias credenciales de API. Después de vincular tu cuenta de X vía OAuth, incluye estos 2 headers en cada solicitud dirigida a X:

Header	Valor
`X-Twitter-OAuth1-Api-Key`	Tu API Key (Consumer Key)
`X-Twitter-OAuth1-Api-Secret`	Tu API Key Secret (Consumer Secret)

¿Aún no la has vinculado? Consulta la Guía de configuración de X BYO Key para conectar tu cuenta de X.

Ayrshare ya no impone sus propios rate limits mensuales o diarios de X/Twitter. Como las solicitudes a X usan tus propias credenciales (BYO), tu uso se rige únicamente por los límites de tu propia X Developer App. Consulta la documentación de rate limits de la API de X para más detalles.

Publicar en X (Twitter)

JSON para una publicación básica con un enlace y una imagen usando la API de X, anteriormente conocida como la API de Twitter:

X Post

{
  "post": "The best Tweet ever #best https://www.twitter.com", // empty string is allowed
  "mediaUrls": ["https://img.ayrshare.com/012/gb.jpg"],
  "platforms": ["twitter"]
}

X mostrará automáticamente una previsualización del enlace en el Tweet a menos que se incluya una imagen o video. En el ejemplo anterior se mostrará la imagen. Al quitar la imagen aparecerá la previsualización del enlace.
Si tu video no termina con una extensión de video conocida como mp4, usa el parámetro isVideo. Consulta el endpoint /post para más detalles.
X también admite el envío de medios sin texto de publicación. Si no quieres incluir texto en la publicación, envía una cadena vacía post: "".
Puedes subir hasta 4 imágenes o videos en un solo Tweet. Consulta las directrices importantes y restricciones para publicar videos en Twitter.
Consulta las Directrices de medios de X y la Autorización de X para más información.

Opciones de X

Puedes establecer opciones adicionales para una publicación usando el parámetro twitterOptions.

X Options

{
  "twitterOptions": {
    "altText": ["This is my best pic", "😃 here is the next one"],
    "blockCountries": ["US", "CA"], // or "allowCountries": ["GB", "IE"]
    "longPost": true,
    "longVideo": true,
    "poll": {
      "duration": 5, // required. Number in minutes
      "options": ["yes", "maybe", "no"] // required
    },
    "quoteTweetId": "651601430669664256",
    "replySettings": "mentioned",
    "subscribersOnly": true,
    "thumbNail": "https://img.ayrshare.com/012/gb.jpg",

    // Video Metadata
    "videoTitle": "My Product Demo",
    "videoDescription": "A short walkthrough of our latest release.",

    // Subtitles / Captions for Videos
    "subTitleUrl": "https://img.ayrshare.com/012/captions.srt",
    "subTitleLanguage": "en",
    "subTitleName": "English",

    // Thread Options
    "thread": true,
    "threadNumber": true,
    "mediaUrls": ["https://img.ayrshare.com/012/gb.jpg"],
  }
}

Las opciones de X son campos opcionales que se pueden usar para controlar la publicación.

altText

array of strings

Texto alternativo de las imágenes para ayudar con la accesibilidad y los lectores de pantalla. Máximo 1000 caracteres por alt text.Consulta Alt Text para más información.

blockCountries

array of strings

Restringe los medios a países específicos bloqueando ciertas regiones. Usa códigos de país.No se puede usar con allowCountries. Consulta Restricciones geográficas para más información.

allowCountries

array of strings

Restringe los medios a países específicos permitiendo ciertas regiones. Usa códigos de país.No se puede usar con blockCountries. Consulta Restricciones geográficas para más información.

longPost

boolean

predeterminado:false

Habilita la publicación de posts más largos, de hasta 25 000 caracteres, para usuarios Premium.Consulta Long Post para más información.

longVideo

boolean

predeterminado:false

Permite publicar videos de más de 2 minutos y 20 segundos para cuentas aprobadas.Consulta Long Video para más información.

poll

object

Realiza encuestas con opciones y duración personalizadas.Campos obligatorios: duration (número en minutos), options (arreglo de strings).Consulta Encuestas para más información.

quoteTweetId

string

Cita otro tweet especificando el Tweet ID.Consulta Quote Tweet para más información.

replySettings

string

Controla quién puede responder a la publicación.Valores: following, mentioned, subscribers o verified.Consulta Reply Settings para más información.

subscribersOnly

boolean

predeterminado:false

Hace que la publicación sea visible solo para los suscriptores.Consulta Subscribers Only para más información.

subTitleUrl

string

Añade subtítulos/captions a los videos usando archivos SRT. Debe ser una URL válida de archivo SRT terminada en .srt.Consulta Subtítulos/captions para videos para más información.

subTitleLanguage

string

predeterminado:"en"

El idioma de los subtítulos. Debe ser un código de idioma válido.

subTitleName

string

El nombre de la pista de subtítulos. Máximo 150 caracteres.

thumbNail

string

Establece una miniatura (imagen de portada) para videos. Debe ser una URL a un archivo de imagen JPEG, PNG, BMP o WebP.Consulta Miniatura de video para más información y las Directrices de medios de X para los requisitos de la imagen.

videoTitle

string

Establece el título de un video. Se corresponde con el campo title en X Media Studio.Consulta Metadatos de video para más información.

videoDescription

string

Establece la descripción de un video. Se corresponde con el campo description en X Media Studio.Consulta Metadatos de video para más información.

thread

boolean

predeterminado:false

Divide publicaciones largas en series de threads conectados con numeración y medios opcionales.Consulta Threads para más información.

threadNumber

boolean

predeterminado:false

Añade automáticamente números al final de cada thread con el formato 1/n.Requiere thread: true.

mediaUrls

array of strings

Añade objetos de medios a los threads. Se agregará un objeto de medio a cada thread en orden.Usa null para omitir el medio de un thread específico. Usa objetos con varias URLs para incluir varios medios en un mismo thread.

Alt Text

Añade texto alternativo, también conocido como alt text, a la imagen de un Tweet. El alt text de X es una función de accesibilidad utilizada para brindar información adicional al usuario y para lectores de pantalla. Usa altText dentro del objeto twitterOptions.

X Alt Text

{
  "twitterOptions": {
    "altText": ["This is my best pic", "😃 here is the next one"] // Array of Alt Texts
  }
}

Cada alt text debe corresponder a una imagen del arreglo mediaUrls. El alt text se aplicará a cada imagen en orden.

El alt text no se puede aplicar a videos. Si se incluye un video en mediaUrls con altText, el video no se publicará. El alt text debe tener 1000 caracteres o menos.

Restricciones geográficas

Puedes restringir los medios de X, como una imagen o video, a países específicos usando los parámetros blockCountries y allowCountries con códigos de país. La publicación seguirá apareciendo en todos los países, pero el medio no estará disponible en los países especificados.

{
  "twitterOptions": {
    "blockCountries": ["US", "CA"]
  }
}

{
  "twitterOptions": {
    "allowCountries": ["GB", "IE"]
  }
}

blockCountries: arreglo de códigos de país a bloquear. Consulta códigos de país.
allowCountries: arreglo de códigos de país a permitir. Consulta códigos de país.

Solo debes usar uno de los parámetros blockCountries o allowCountries a la vez. Si se usan ambos parámetros o un país no es compatible con X, las restricciones geográficas se ignorarán.

Long Post

Los usuarios con cuentas Premium de X, como Premium o Premium Plus, tienen la capacidad de publicar posts más largos de hasta 25 000 caracteres. Ayrshare habilita automáticamente las publicaciones long form para usuarios con cuentas Premium de X. Si el usuario cambia su estado de X Premium, espera 24 horas para que se refleje en Ayrshare. Puedes comprobar el estado de la suscripción Premium de un usuario con los endpoints /user o /analytics. También puedes forzar que se acepte una publicación long form con el parámetro longPost del body. Puedes hacerlo incluyendo el siguiente JSON en tu solicitud:

X Long Post

{
  "twitterOptions": {
    "longPost": true
  }
}

Sin embargo, si un usuario sin cuenta Premium intenta publicar un tweet largo, el sistema devolverá un error code: 111.

Long Video

Requiere Business Plan o Enterprise Plan. X requiere que los videos tengan una duración máxima de 2 minutos y 20 segundos. Sin embargo, si X te ha aprobado para subir videos más largos, por ejemplo si la cuenta de X del usuario es Premium o está en el Amplify Partner Program, puedes publicar videos de más de 10 minutos de duración.

Verifica que la cuenta de X de tu usuario sea Premium o esté en el Amplify Partner Program antes de usar el parámetro longVideo. Si la cuenta de X del usuario no está autorizada para publicar videos largos, el sistema devolverá un error.

Usa el parámetro longVideo en twitterOptions al publicar un video largo:

X Long Video

{
  "twitterOptions": {
    "longVideo": true
  }
}

Menciones

Menciona otro handle de X añadiendo @handle en el texto de la publicación. Por ejemplo:

X Mention

{
  "post": "The best social media API @Ayrshare ever!",
  "platforms": ["twitter"]
}

Consulta las reglas importantes sobre menciones.

Encuestas

Realiza una encuesta de X con el parámetro poll de twitterOptions.

X Poll

{
  "twitterOptions": {
    "poll": {
      "duration": 5, // required. Number in minutes
      "options": ["yes", "maybe", "no"] // required
    }
  }
}

duration: número de minutos que especifica la duración de la encuesta.
options: arreglo de strings con las opciones de la encuesta.

Quote Tweet

Puedes citar otro Tweet especificando el Tweet ID de bajo nivel. El ID se puede obtener desde la respuesta de /post en el campo postIds, mediante get history o directamente desde la URL del Tweet: https://twitter.com/Ayrshare/status/1651601430669664256

X Quote Tweet

{
  "twitterOptions": {
    "quoteTweetId": "651601430669664256" // low-level Tweet Id
  }
}

Reply Settings

Puedes configurar los ajustes de respuesta de una publicación para permitir respuestas solo de ciertos tipos de usuarios.

X Reply Settings

{
  "twitterOptions": {
    "replySettings": "mentioned"
  }
}

El parámetro replySettings puede tener uno de los siguientes valores:

following: solo pueden responder los usuarios a los que la cuenta de X sigue.
mentioned: solo pueden responder los usuarios mencionados en la publicación.
subscribers: solo pueden responder los suscriptores de la cuenta de X que publicó el post.
verified: solo pueden responder los usuarios verificados en X.

Subscribers Only

Puedes hacer que una publicación sea visible solo para los suscriptores usando el parámetro subscribersOnly.

X Subscribers Only

{
  "twitterOptions": {
    "subscribersOnly": true
  }
}

Subtítulos/captions para videos

Puedes añadir subtítulos de X, también conocidos como captions de X, a los videos incluyendo un archivo SRT. Usa el campo subTitleUrl dentro del objeto twitterOptions para especificar la URL a tu archivo SRT.

X Subtitles

{
  "twitterOptions": {
    "subTitleUrl": "https://img.ayrshare.com/012/captions.srt",
    "subTitleLanguage": "en",
    "subTitleName": "English"
  }
}

subTitleUrl: archivo SRT válido. La URL debe comenzar con https://, terminar en .srt y ser un archivo SRT válido.
subTitleLanguage: opcional: idioma de los subtítulos. Debe ser un código de idioma válido. Por defecto: “en”.
subTitleName: opcional: nombre de la pista de subtítulos. El nombre está pensado para ser visible para el usuario como opción durante la reproducción. La longitud máxima admitida es de 150 caracteres. Por defecto: “English”.

Miniatura de video

Establece una miniatura (imagen de portada) para videos de Twitter/X. La miniatura se muestra antes de que el video se reproduzca y ayuda a los usuarios a entender el contenido del video. Usa thumbNail dentro del objeto twitterOptions.

Twitter/X Video Thumbnail

{
  "twitterOptions": {
    "thumbNail": "https://img.ayrshare.com/012/gb.jpg"
  }
}

“thumbNail”: URL a la imagen de miniatura. Los formatos de imagen admitidos son JPEG, PNG, BMP y WebP.
La imagen de miniatura debe representar el contenido del video y ser visualmente atractiva para fomentar la interacción.
Consulta las Directrices de medios de X para los requisitos de la imagen.

Metadatos de video

Establece un título y una descripción para un video publicado en X. Estos se corresponden con los campos title y description en X Media Studio. Usa los campos videoTitle y videoDescription dentro del objeto twitterOptions.

X Video Metadata

{
  "twitterOptions": {
    "videoTitle": "My Product Demo",
    "videoDescription": "A short walkthrough of our latest release."
  }
}

videoTitle: título del video, asociado al campo title de X Media Studio.
videoDescription: descripción del video, asociada al campo description de X Media Studio.

Monetización de video (Pro Media)

Ayrshare admite la monetización de videos de X (Twitter) para cuentas elegibles a través del programa Pro Media de X. Es una capacidad de acceso limitado — contáctanos si te gustaría tener acceso.

Thread

Un X Thread, también conocido como tweetstorm, es una serie conectada de publicaciones en X (antes Twitter) que te permite compartir ideas más largas más allá del límite de caracteres de una sola publicación, apareciendo como una narrativa continua cuando se ven juntas.

Publicar un Thread

Un X Thread se puede publicar mediante la API. Un thread es una publicación dividida en un conjunto de threads de respuesta y asociados en X con una línea. Puedes dividir la publicación automáticamente o especificar los thread breaks en el texto de la publicación.

X Thread

{
    "twitterOptions": {
        "thread": true,        // required for TweetStorm
        "threadNumber": true,  // optional to add numbers to each thread
        "mediaUrls": ["https://site.com/image1.png", "https://site.com/image2.png", ...]  // optional one media object is added to a thread in order
    }
}

thread: true para dividir automáticamente el texto de la publicación en threads basándose en los saltos de línea.
threadNumber: true para añadir automáticamente números al final de los threads con el formato 1/n. Por ejemplo, el 2.º de 5 threads llevará añadido: 2/5
mediaUrls: [array of urls] para añadir cada objeto de medio, imagen o video, a un thread en orden. Solo se añadirá un objeto de medio a cada thread en orden.

Si la publicación se envía como X Thread, las analíticas de publicación devueltas serán un arreglo de Tweets, "twitter": []. Consulta Post Analytics 200 Response para más información.

Medios del thread

Omitir medio

Omite el medio del thread usando null en el arreglo. Por ejemplo: ["https://site.com/image1.png", null, "https://site.com/image2.png"] Esto colocará image1 en el primer Tweet, ningún imagen en el segundo Tweet e image2 en el tercer Tweet.

Múltiples medios

Se pueden añadir varios objetos de medios a un Tweet dentro de un Thread agregando un objeto {} con las URLs de los medios en el arreglo mediaUrls. Se pueden usar cualquier clave única. Por ejemplo:

X Thread with Multiple Media URLs

{
  "twitterOptions": {
    "thread": true,
    "threadNumber": true,
    "mediaUrls": [
      "https://img.ayrshare.com/random/photo-1.jpg",
      {
        "1": "https://img.ayrshare.com/random/photo-2.jpg",
        "2": "https://img.ayrshare.com/random/photo-3.jpg"
      },
      "https://img.ayrshare.com/random/photo-4.jpg"
    ]
  }
}

En este ejemplo, el primer Tweet contendrá photo-1.jpg, el segundo Tweet photo-2.jpg y photo-3.jpg, y el tercer Tweet photo-4.jpg.

Cortes del thread

Ayrshare divide automáticamente el texto de la publicación en tweets de longitud adecuada (> 280 caracteres). Al crear threads, damos prioridad a mantener oraciones completas en una sola publicación cuando es posible. Si una oración no cabe, dividimos entre oraciones. Para oraciones muy largas, dividimos entre palabras. En casos raros en los que una palabra sea demasiado larga, dividimos la palabra en sí. También puedes añadir manualmente párrafos con \n\n al texto de la publicación para indicar que se debe crear un thread único. Si tienes \n\n en el texto de la publicación, no dividiremos automáticamente la publicación en threads. Por ejemplo:

Example X Thread

{
  "post": "This is tweet 1\n\nThis is tweet 2.",
  "platforms": ["twitter"],
  "twitterOptions": {
    "thread": true
  }
}

resultará en dos Tweets en el thread. Si quieres añadir párrafos pero no dividir en Tweets, usa \u2063\n\u2063\n

X Thread with Paragraphs

{
  "post": "This is paragraph 1\u2063\n\u2063\nThis is paragraph 2.",
  "platforms": ["twitter"],
  "twitterOptions": {
    "thread": true
  }
}

resultará en un solo Tweet con dos párrafos, ya que la publicación tiene menos de 280 caracteres.

Eliminar un thread

Para eliminar un Tweet Storm, llama al endpoint /post delete con el ID de la publicación de nivel superior devuelto en la respuesta. Todos los threads se eliminarán.

Límites de caracteres

Consulta Límites de caracteres de X/Twitter para más información.

Compatibilidad de video en X

Algunos programas de video crean archivos MP4 que no son compatibles con X. Por ejemplo, versiones de Camtasia anteriores a 2019.0.9 crean archivos MP4 que X rechaza. Además, tener más de una pista de audio suele causar problemas. Si recibes el siguiente mensaje al publicar, indica que el video no es compatible con Twitter y necesita ser reencodificado. "file is currently unsupported" Revisa la compatibilidad de tu software de video. Por ejemplo, Adobe Media Encoder tiene un preset de exportación para Twitter 1080p Full HD.

Consulta aquí más ejemplos de la API de X.

Subscribers Only

Puedes hacer que una publicación sea visible solo para los suscriptores usando el parámetro subscribersOnly.

X Subscribers Only

{
  "twitterOptions": {
    "subscribersOnly": true
  }
}

Reply Settings

Puedes configurar los ajustes de respuesta de una publicación para permitir respuestas solo de ciertos tipos de usuarios.

X Reply Settings

{
  "twitterOptions": {
    "replySettings": "mentioned"
  }
}

El parámetro replySettings puede tener uno de los siguientes valores:

following: solo pueden responder los usuarios a los que la cuenta de X sigue.
mentioned: solo pueden responder los usuarios mencionados en la publicación.
subscribers: solo pueden responder los suscriptores de la cuenta de X que publicó el post.
verified: solo pueden responder los usuarios verificados en X.

​X BYO API Keys

​Publicar en X (Twitter)

​Opciones de X

​Alt Text

​Restricciones geográficas

​Long Post

​Long Video

​Menciones

​Encuestas

​Quote Tweet

​Reply Settings

​Subscribers Only

​Subtítulos/captions para videos

​Miniatura de video

​Metadatos de video

​Monetización de video (Pro Media)

​Thread

​Publicar un Thread

​Medios del thread

Omitir medio

Múltiples medios

​Cortes del thread

​Eliminar un thread

​Límites de caracteres

​Compatibilidad de video en X

​Subscribers Only

​Reply Settings

X BYO API Keys

Publicar en X (Twitter)

Opciones de X

Alt Text

Restricciones geográficas

Long Post

Long Video

Menciones

Encuestas

Quote Tweet

Reply Settings

Subscribers Only

Subtítulos/captions para videos

Miniatura de video

Metadatos de video

Monetización de video (Pro Media)

Thread

Publicar un Thread

Medios del thread

Cortes del thread

Eliminar un thread

Límites de caracteres

Compatibilidad de video en X

Subscribers Only

Reply Settings