Puedes usar la API de publicación de contenido para realizar publicaciones con un único vídeo, reel o imagen (es decir, publicaciones con un único archivo multimedia) o publicaciones con varios vídeos e imágenes (publicaciones por secuencia) en cuentas profesionales de Instagram.
A partir del 1 de julio de 2023, todos los vídeos individuales publicados en el feed mediante la API de publicación de contenido de Instagram se compartirán como reels.
Todas las solicitudes deben incluir el identificador de acceso de usuario de la aplicación.
La publicación se basa en una combinación de los siguientes permisos. La combinación exacta depende de los extremos que utilice tu aplicación. Consulta nuestras referencias de los extremos para determinar los permisos que requiere cada uno de ellos.
Si utilizarán tu aplicación usuarios que no tengan ningún rol en ella ni en una empresa que la haya reclamado, debes solicitar la aprobación para cada permiso mediante la revisión de la aplicación. De este modo, los usuarios de la aplicación sin rol podrán conceder permisos a tu aplicación.
Aplicaremos cURL al contenido multimedia usado en los intentos de publicación. Por esta razón, este contenido debe estar hospedado en un servidor accesible públicamente en el momento que se lleve a cabo el intento.
No se puede publicar en las cuentas profesionales de Instagram conectadas a una página que requiera autorización de publicación en páginas (PPA) hasta que se haya completado la PPA.
Es posible que un usuario de la aplicación pueda realizar tareas en una página que al principio no necesite PPA, pero más adelante, sí. En tal caso, el usuario de la aplicación no podría publicar contenido en su cuenta profesional de Instagram hasta que se completara la PPA. Dado que no es posible determinar si la página de un usuario de la aplicación requiere PPA, recomendamos que aconsejes a los usuarios de la aplicación que completen la PPA de manera preventiva.
Para obtener información sobre otras limitaciones, consulta la referencia de cada extremo.
Las cuentas de Instagram están limitadas a 50 publicaciones de la API por cada periodo renovable de 24 horas. Las secuencias se consideran una única publicación. El límite se aplica en el extremo POST /{ig-user-id}/media_publish
al intentar publicar un contenedor de archivos multimedia. Recomendamos que tu aplicación también aplique el límite de frecuencia de publicación, especialmente si permite que los usuarios programen publicaciones para que se publiquen en el futuro.
Para comprobar el uso del límite de frecuencia actual de una cuenta profesional de Instagram, envía una consulta al extremo GET /{ig-user-id}/content_publishing_limit
.
La API consta de los extremos siguientes. Consulta los requisitos de uso en cada documento de referencia de los extremos.
POST /{ig-user-id}/media
: subir contenido multimedia y crear contenedores de contenido multimedia.POST /{ig-user-id}/media_publish
: publicar contenido multimedia subido mediante sus contenedores de contenido multimedia.GET /{ig-container-id}?fields=status_code
: comprobar la idoneidad y el estado de publicación de los contenedores de contenido multimedia.GET /{ig-user-id}/content_publishing_limit
: comprobar el uso del límite de frecuencia de publicación actual por parte de un usuario de la aplicación.Para publicar un único vídeo, reel, imagen o historia, debes seguir dos pasos:
POST /{ig-user-id}/media
para crear un contenedor a partir de una imagen o un vídeo hospedado en tu servidor público.POST /{ig-user-id}/media_publish
para publicar el contenedor.Paso 1 de 2: Crear el contenedor
Supongamos que tienes una imagen en…
https://www.example.com/images/bronz-fonz.jpg
… y quieres publicarla con el hashtag “#BronzFonz” como subtítulo. Envía una solicitud al extremo POST /{ig-user-id}/media
:
POST https://graph.facebook.com/v21.0
/17841400008460056/media
?image_url=https://www.example.com/images/bronz-fonz.jpg
&caption=#BronzFonz
Esta solicitud devuelve un identificador de contenedor para la imagen.
{ "id": "17889455560051444" // IG Container ID }
Paso 2 de 2: Publicar el contenedor
Utiliza el extremo POST /{ig-user-id}/media_publish
para publicar el identificador de contenedor devuelto en el paso anterior.
POST https://graph.facebook.com/v21.0
/17841400008460056/media_publish ?creation_id=17889455560051444
{ "id": "17920238422030506" // IG Media ID }
Puedes publicar hasta 10 imágenes, vídeos o una combinación de ambos en una única publicación (una publicación por secuencia). La publicación de secuencias es un proceso de tres pasos:
POST /{ig-user-id}/media
a fin de crear contenedores de elementos individuales para cada imagen y vídeo que aparecerá en la secuencia.POST /{ig-user-id}/media
para crear un único contenedor de secuencia para los elementos.POST /{ig-user-id}/media_publish
para publicar el contenedor de la secuencia.Las publicaciones por secuencia se consideran una única publicación con respecto al límite de frecuencia de la cuenta.
Limitaciones
Paso 1 de 3: Crear el contenedor de elementos
Utiliza el extremo POST /{ig-user-id}/media
a fin de crear un contenedor de elementos para la imagen o el vídeo que aparecerá en una secuencia. En total, las secuencias pueden tener hasta diez imágenes, vídeos o una combinación de ambos.
POST /{ig-user-id}/media
Los parámetros siguientes son obligatorios. Puedes consultar los demás parámetros admitidos en la referencia del extremo POST /{ig-user-id}/media
.
is_carousel_item
: definido como true
. Indica que la imagen o el vídeo aparecerá en una secuencia.image_url
: (solo imágenes) ruta de la imagen. Aplicaremos cURL a la imagen mediante la URL pasada, por lo que se debe encontrar en un servidor público.media_type
: (solo vídeos) definido como VIDEO
. Indica que el contenido multimedia es un vídeo.video_url
: (solo vídeos) ruta del vídeo. Aplicaremos cURL al vídeo mediante la URL pasada, por lo que se debe encontrar en un servidor público.Si la operación se realiza correctamente, la API devolverá un identificador de contenedor del elemento que se puede usar al crear el contenedor de la secuencia.
Repite este proceso para cada imagen o vídeo que deba aparecer en la secuencia.
curl -i -X POST \
"https://graph.facebook.com/v21.0
/90010177253934/media?image_url=https%3A%2F%2Fsol...&is_carousel_item=true&access_token=EAAOc..."
{ "id": "17899506308402767" }
Paso 2 de 3: Crear el contenedor de secuencia
Utiliza el extremo POST /{ig-user-id}/media
para crear un contenedor de secuencia.
POST /{ig-user-id}/media
Los parámetros siguientes son obligatorios. Puedes consultar los demás parámetros admitidos en la referencia del extremo POST /{ig-user-id}/media
.
media_type
: definido como CAROUSEL
. Indica que el contenedor es para una secuencia.children
: una matriz de hasta 10 identificadores de contenedor de cada imagen y vídeo que debe aparecer en la secuencia publicada. En total, las secuencias pueden tener hasta 10 imágenes, vídeos o una combinación de ambos.
curl -i -X POST \
"https://graph.facebook.com/v21.0
/90010177253934/media?caption=Fruit%20candies&media_type=CAROUSEL&children=17899506308402767%2C18193870522147812%2C17853844403701904&access_token=EAAOc..."
{ "id": "18000748627392977" }
Paso 3 de 3: Publicar el contenedor de secuencia
Utiliza el extremo POST /{ig-user-id}/media_publish
para publicar el contenedor de secuencia (una publicación por secuencia). Las cuentas están limitadas a 50 publicaciones por cada periodo de 24 horas. La publicación de una secuencia se considera una única publicación.
POST /{ig-user-id}/media_publish
Los parámetros siguientes son obligatorios.
creation_id
: identificador del contenedor de la secuencia.Si la operación se realiza correctamente, la API devolverá un identificador de contenido multimedia de Instagram del álbum de la secuencia.
curl -i -X POST \
"https://graph.facebook.com/v21.0
/90010177253934/media_publish?creation_id=18000748627392977&access_token=EAAOc..."
{ "id": "90010778390276" }
Los reels son vídeos breves que pueden aparecer en la pestaña Reels de la aplicación de Instagram si cumplen determinadas especificaciones y nuestro algoritmo los selecciona. Para publicar un reel, sigue los pasos de publicación de un único archivo multimedia y añade el parámetro media_type=REELS
junto con la ruta del vídeo mediante el parámetro video_url
.
Los reels no son un nuevo tipo de contenido multimedia, a pesar de que defines el parámetro media_type=REELS
cuando publicas un reel. Si publicas un reel y, después, solicitas su campo media_type
, el valor devuelto es VIDEO
. Para determinar si un vídeo publicado se ha designado como reel, solicita el campo media_product_type
en su lugar.
Puedes usar el código de ejemplo disponible en GitHub (insta_reels_publishing_api_sample) para obtener información sobre cómo publicar reels en Instagram.
A fin de que resulte más cómodo para los desarrolladores, Meta ha publicado el conjunto completo de llamadas a la API Graph para Instagram Reels en la plataforma de la API de Postman. Para obtener más información, consulta las colecciones de Postman para Facebook Reels e Instagram Reels.
Para obtener más información sobre reels, consulta la documentación para desarrolladores de reels.
Por el momento, solo las cuentas empresariales pueden publicar historias con la API de publicación de contenido.
Las historias son vídeos e imágenes que se publican como historias de Instagram en esta plataforma. Para publicar una historia, sigue los mismos pasos que para publicar un único archivo multimedia e incluye el parámetro media_type=STORIES
junto con la ruta al vídeo o la imagen mediante el parámetro image_url
o video_url
.
Nota: Las historias no son un nuevo tipo de contenido multimedia a pesar de que defines el parámetro media_type=STORIES
al publicar una historia. Si publicas una historia y, después, solicitas su campo media_type
, el valor se devolverá como IMAGE/VIDEO
. Para determinar si una imagen o vídeo publicado ha sido designado como historia, solicita el campo media_product_type
en su lugar.
El protocolo de subida reanudable es un nuevo proceso para la publicación de contenido en Instagram que admite las subidas de vídeos para los siguientes media_types
: reels, historias de vídeo y elementos de secuencias de vídeos.
Este nuevo protocolo admite la creación de contenido multimedia para Instagram a partir de vídeos locales y vídeos de URL alojadas públicamente. El protocolo te permite reanudar operaciones de subida de archivos locales después de interrupciones en la red u otros fallos en la transmisión, lo que ahorra tiempo y ancho de banda en caso de fallos en la red. Se mantienen las mismas especificaciones del contenido multimedia.
POST https://graph.facebook.com/{api-version}/{ig-user-id}/media
: inicializar los contenedores de creación de vídeos especificando “upload_type=resumable”.POST https://rupload.facebook.com/ig-api-upload/{api-version}/{ig-container-id}
: subir vídeos desde archivos de vídeo locales o de URL hospedadas de forma más fiable mediante el protocolo de subida reanudable. POST https://graph.facebook.com/{api-version}/{ig-user-id}/media_publish
: publicar contenido multimedia subido mediante sus contenedores de contenido multimedia.GET /{ig-container-id}?fields=status_code
: comprobar la idoneidad y el estado de publicación de los contenedores de contenido multimedia.user_tags=[{username:’ig_user_name’}]
está codificado como user_tags=%5B%7Busername:ig_user_name%7D%5D
, donde [
está codificado como %5B
y {
está codificado como %7B
. Para ver más conversiones, consulta las normas de codificación de URL HTML.curl -X POST "https://graph.facebook.com/{api-version}/{ig-user-id}/media" \ -d "media_type=REELS" \ -d "upload_type=resumable" \ -d "caption={caption}"\ -d "collaborators={collaborators-username}" -d "cover_url={cover-url}" \ -d "audio_name={audio-name}" \ -d "user_tags={user-tags}" \ -d "location_id={location-id}" \ -d "thumb_offset={thumb-offset}" \ -H "Authorization: OAuth {access-token}"
curl -X POST "https://graph.facebook.com/{api-version}/{ig-user-id}/media" \ -d "media_type=STORIES" \ -d "upload_type=resumable" \ -H "Authorization: OAuth {access-token}"
curl -X POST "https://graph.facebook.com/{api-version}/{ig-user-id}/media" \ -d "media_type=VIDEO" \ -d "is_carousel_item=true" \ -d "upload_type=resumable" \ -H "Authorization: OAuth {access-token}"
{ "id": "{ig-container-id}", "uri": "https://rupload.facebook.com/ig-api-upload/{api-version}/{ig-container-id}" }
La mayoría de las llamadas a la API Graph utilizan el host graph.facebook.com
. Sin embargo, las llamadas para subir vídeos para reels utilizan rupload.facebook.com
.
Para la subida de archivos de vídeo se admiten los orígenes de archivos siguientes:
Sube el vídeo con el valor de ig-container-id
devuelto en la llamada de la sesión de subida reanudable.
rupload.facebook.com
.media_type
.ig-container-id
es el identificador devuelto en la llamada de la sesión de subida reanudable. access-token
es el mismo que se ha usado en los pasos anteriores.offset
se establece en el primer byte de la subida; normalmente, 0
.file_size
se establece en el tamaño del archivo en bytes.Your_file_local_path
se establece en la ruta de archivo del archivo local. Por ejemplo, si se sube un archivo desde la carpeta de descargas en macOS, la ruta es @Downloads/example.mov.curl -X POST "https://rupload.facebook.com/ig-api-upload/{api-version}/{ig-container-id}" \ -H "Authorization: OAuth {access-token}" \ -H "offset: 0" \ -H "file_size: Your_file_size_in_bytes" \ --data-binary "@my_video_file.mp4"
curl -X POST "https://rupload.facebook.com/ig-api-upload/{api-version}/{ig-container-id}" \ -H "Authorization: OAuth {access-token}" \ -H "file_url: https://example_hosted_video.com"
// Success Response Message { "success":true, "message":"Upload successful." } // Failure Response Message { "debug_info":{ "retriable":false, "type":"ProcessingFailedError", "message":"{\"success\":false,\"error\":{\"message\":\"unauthorized user request\"}}" } }
Puedes volver a realizar los Pasos 1 y 2 para crear varios ig-container-ids
con el parámetro is_carousel_item
establecido en true
. A continuación, crea el contenedor de secuencia para incluir todos los elementos de secuencia, que pueden combinar imágenes y vídeos.
curl -X POST "https://graph.facebook.com/{api-version}/{ig-user-id}/media" \ -d "media_type=CAROUSEL" \ -d "caption={caption}"\ -d "collaborators={collaborator-usernames}" \ -d "location_id={location-id}" \ -d "product_tags={product-tags}" \ -d "children=[{ig-container-id},{ig-container-id}...]" \ -H "Authorization: OAuth {access-token}"
En el caso de los reels y las historias de vídeo, se utiliza el {ig-container-id}
creado en el Paso 1 para publicar el vídeo. Para publicar el contenedor de secuencia, se utiliza el valor de {ig-container-id}
creado en el Paso 3.
curl -X POST "https://graph.facebook.com/{api-version}/{ig-user-id}/media_publish" \ -d "creation_id={ig-container-id}" \ -H "Authorization: OAuth {access-token}"
graph.facebook.com
proporciona un extremo GET
para leer el estado de la subida y el campo video_status
contiene los detalles sobre el proceso de subida local.
uploading_phase
indica si el archivo se ha subido correctamente y cuántos bytes se han transferido. processing_phase
contiene los detalles sobre el estado de procesamiento del vídeo una vez que este se ha subido.// GET status from graph.facebook.com curl -X GET "https://graph.facebook.com/v19.0/{ig-container-id}?fields=id,status,status_code,video_status" \ -H "Authorization: OAuth {access-token}"
graph.facebook.com
// A successfully created ig container { "id": "{ig-container-id}", "status": "Published: Media has been successfully published.", "status_code": "PUBLISHED", "video_status": { "uploading_phase": { "status": "complete", "bytes_transferred": 37006904 }, "processing_phase": { "status": "complete" } } } // An interrupted ig container creation, from here you can resume your upload in step 2 with offset=50002. { "id": "{ig-container-id}", "status": "Published: Media has been successfully published.", "status_code": "PUBLISHED", "video_status": { "uploading_phase": { "status": "in_progress", "bytes_transferred": 50002 }, "processing_phase": { "status": "not_started" } } }
Puedes añadir a usuarios públicos de Instagram a una imagen, una secuencia o un reel como colaboradores y recibirán una invitación para ser colaboradores de ese archivo multimedia específico. Para etiquetar a usuarios en una imagen, sigue los pasos descritos anteriormente en “Publicaciones con un único archivo multimedia”. No obstante, al crear el contenedor de archivos multimedia, incluye el parámetro “collaborators” y una matriz de cadenas en la que se indiquen los nombres de usuario de Instagram de los usuarios que quieres invitar como colaboradores del archivo multimedia.
POST graph.facebook.com/17841400008460056/media ?image_url=https://www.example.com/images/bronzed-fonzes.jpg &caption=#BronzedFonzes! &collaborators= [‘username1’,’username2’]
Puedes usar la API de búsqueda de páginas ; asegúrate de añadir el campo “location” a la consulta para buscar páginas cuyo nombre coincida con una cadena de búsqueda. A continuación, analiza los resultados para identificar las páginas que se hayan creado para una ubicación física. Si incluyes un identificador de página al publicar una imagen o un vídeo, se etiquetará con la ubicación asociada con la página.
Para ser apta para las etiquetas, una página debe tener los datos de ubicación de latitud y longitud.
Verifica si la página que quieres usar tiene datos de latitud y longitud en la respuesta. Si se intenta crear un contenedor con una página que no tiene datos de ubicación, se producirá un error con el código de excepción INSTAGRAM_PLATFORM_API__INVALID_LOCATION_ID
.
Cuando tengas el identificador de página, asígnalo al parámetro location_id
al publicar contenedores de elementos multimedia únicos o por secuencia.
Puedes realizar publicaciones con un único archivo multimedia y publicaciones por secuencia etiquetadas con productos de compras de Instagram. Consulta la guía Etiquetado de productos para obtener más información al respecto.
Puedes etiquetar a usuarios públicos de Instagram en una imagen y recibirán una notificación que indica que los has etiquetado.
Para etiquetar a usuarios en una imagen, sigue los pasos descritos anteriormente en Publicaciones con un único archivo multimedia. No obstante, al crear el contenedor de archivos multimedia, incluye el parámetro user_tags
y una matriz de objetos donde se indiquen los usuarios de Instagram de la imagen, así como sus coordenadas x/y en la imagen.
Nota: Las etiquetas de usuario no son compatibles con el contenido multimedia de vídeo de las secuencias.
POST graph.facebook.com/17841400008460056/media ?image_url=https://www.example.com/images/bronzed-fonzes.jpg &caption=#BronzedFonzes! &user_tags= [ { username:'kevinhart4real', x: 0.5, y: 0.8 }, { username:'therock', x: 0.3, y: 0.2 } ]
Esta solicitud devuelve un identificador de contenedor que, posteriormente, puedes publicar mediante el extremo de publicación de contenido multimedia del usuario de Instagram.
user_tags
debe ser una matriz de objetos con formato JSON.username
, x
y y
) para cada usuario.x
y y
deben ser números de tipo float
desde la esquina superior izquierda de la imagen, con un rango entre 0.0
y 1.0
.Si puedes crear un contenedor para un vídeo, pero el extremo POST /{ig-user-id}/media_publish
no devuelve el identificador del contenido multimedia publicado, puedes enviar una consulta al extremo GET /{ig-container-id}?fields=status_code
para obtener el estado de publicación del contenedor. Este extremo devolverá una de las siguientes opciones:
EXPIRED
: el contenedor no se ha publicado en 24 horas y ha caducado.ERROR
: el contenedor no ha completado el proceso de publicación.FINISHED
: el contenedor y su objeto de contenido multimedia están listos para publicarse.IN_PROGRESS
: el contenedor sigue en el proceso de publicación.PUBLISHED
: el objeto de contenido multimedia del contenedor se ha publicado.Recomendamos enviar una consulta sobre el estado del contenedor por minuto durante un máximo de 5 minutos.
Consulta la referencia de códigos de error.