> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API de Instagram

> Opciones para publicar usando la API de Instagram

<Info>
  Si tienes problemas para conectar Instagram, consulta la [guía de solución de
  problemas](/help-center/technical-support/facebook_or_instagram_linking_issues).
</Info>

<Info>
  Si tu contenido está alojado en un servidor o CDN que tú controlas, asegúrate de que el crawler de publicación de Meta
  pueda descargarlo. Consulta [Meta Media Crawler Blocked](/help-center/technical-support/meta_media_crawler_blocked)
  si ves el código de error 440 de Ayrshare ("social network could not download media from this URL") o el código 138 con "Restricted by robots.txt" en los detalles.
</Info>

<div class="video-container">
  <iframe width="380" height="200" src="https://www.youtube.com/embed/3F7mbVN0qrw" title="Posting to Instagram API" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" />
</div>

La API de Instagram tiene los siguientes requisitos y restricciones.

<ul class="custom-bullets">
  <li>
    Cuenta de Instagram Business o Creator conectada con una Página de Facebook: [consulta
    aquí](/dashboard/connect-social-accounts/instagram).
  </li>

  <li>Solo se permiten 50 publicaciones de Instagram en un período de 24 horas. Consulta a continuación `usedQuota`.</li>

  <li>
    El texto de `post` puede contener hasta *5 hashtags* (p. ej. #wildtimes) y *3 menciones de nombre de usuario*
    (p. ej. @natgeo).
  </li>

  <li>Los usuarios de Instagram @mencionados recibirán una notificación.</li>
  <li>Máximo 2200 caracteres por publicación.</li>

  <li>
    Las publicaciones con varias imágenes/videos son compatibles y se envían como carrusel. Puedes enviar hasta 10 videos
    e imágenes.
  </li>

  <li>
    Instagram no admite eliminaciones a través de una API. Las eliminaciones deben realizarse manualmente en la app de
    Instagram.
  </li>

  <li>
    Si tu video de Reel no termina con una extensión de video conocida como mp4, usa el parámetro `isVideo`.
    Consulta el [endpoint /post](/apis/post/post) para más detalles.
  </li>

  <li>
    Instagram 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: ""`.
  </li>

  <li>Consulta las [Directrices de medios de Instagram](/media-guidelines/instagram) y la [Autorización de Instagram](/dashboard/connect-social-accounts/instagram) para más información.</li>
</ul>

## Publicar en Instagram

JSON para una publicación básica con imagen y hashtags en Instagram:

```json Instagram Post theme={"system"}
{
  "post": "The best IG ever #best #awesome https://www.instagram.com",
  "mediaUrls": ["https://img.ayrshare.com/012/gb.jpg"],
  "platforms": ["instagram"]
}
```

Los hashtags son clicables en las publicaciones de Instagram, pero los enlaces no.

<Note>
  La relación de aspecto de las imágenes y videos y la duración del video son muy importantes para publicar correctamente en Instagram. Si no cumplen con los requisitos, la publicación será rechazada.

  [Consulta la sección de Instagram en las Directrices de imagen y video](/media-guidelines/instagram).
</Note>

## Cuenta de Instagram Business o Creator

Tu cuenta de Instagram debe ser Business o Creator y estar conectada con una Página de Facebook. La configuración es gratuita y sencilla.

Consulta aquí las instrucciones detalladas:

<Card title="Vinculación de Instagram" icon="link" href="/dashboard/connect-social-accounts/instagram" horizontal />

## Carrusel de imágenes y videos

Puedes publicar varias imágenes o videos de Reel en Instagram como un carrusel; hasta un total combinado de 10 imágenes o videos en un carrusel.
Simplemente agrega tus imágenes o videos adicionales al arreglo `mediaUrls` y el carrusel se creará automáticamente.

```json Instagram Carousel Post theme={"system"}
{
  // Max 10 images or videos
  "mediaUrls": ["https://url.com/image.jpg", "https://url.com/video.mp4"]
}
```

<Note>
  Las URLs de video deben terminar con una extensión conocida como `mp4`. El parámetro `isVideo` no es compatible
  con los carruseles de Instagram.
</Note>

## Instagram Reels

En Instagram, una publicación de video se llama Reel.
Puedes publicar un video en la API de Instagram Reels con las siguientes opciones opcionales en `instagramOptions`.

```json Instagram Reels Options theme={"system"}
{
  "instagramOptions": {
    "shareReelsFeed": true,
    "audioName": "The Weeknd - Blinding Lights",
    "thumbNail": "https://img.ayrshare.com/012/gb.jpg", // if used, thumbNailOffset will be ignored.
    "thumbNailOffset": 30000
  }
}
```

<ul class="custom-bullets">
  <li>
    Consulta los [requisitos de video de la API de Reels](/media-guidelines/instagram#reels) para más detalles sobre
    los requisitos de video.
  </li>

  <li>
    `shareReelsFeed`: Boolean con valor `true` para indicar que el Reel *puede* aparecer en las pestañas
    **Feed** y **Reels**, o `false` para indicar que el Reel *solo puede* aparecer en la pestaña **Reels**.
    Este valor es una sugerencia para Instagram sobre dónde te gustaría que apareciera el Reel, pero ninguno
    de los valores determina si el Reel *realmente* aparece en la pestaña **Reels** o **Feed** porque
    puede que el Reel no cumpla con los requisitos de elegibilidad o no sea seleccionado por el algoritmo de Instagram.
  </li>

  <li>
    `audioName`: nombre en String del audio o música de tu Reel. Solo puedes renombrarlo una vez, ya sea
    al crear el reel o después desde la página de audio. Por ejemplo, `"The Weeknd - Blinding
            Lights"`.
  </li>

  <li>
    `thumbNail`: URL en String de la imagen de portada (thumbnail) del Reel. Consulta aquí los [detalles sobre
    thumbNail](/apis/post/social-networks/instagram#reels-thumbnails).
  </li>

  <li>
    `thumbNailOffset`: desplazamiento entero en milisegundos del frame de la miniatura. Consulta aquí los
    [detalles sobre thumbNailOffset.](/apis/post/social-networks/instagram#reels-thumbnails)
  </li>
</ul>

Consulta los [requisitos de video de la API de Reels](/media-guidelines/instagram#reels) o un [ejemplo de uso de la API de Instagram Reels](https://www.ayrshare.com/blog/instagram-reels-api-how-to-post-videos-to-reels-using-a-social-media-api/).

También puedes establecer una [URL de portada de Reels](/apis/post/social-networks/instagram#reels-thumbnails) y [etiquetas de ubicación y usuarios](/apis/post/social-networks/instagram#user-tags-and-locations).

## Trial Reels

Un trial reel es un Reel que se publica únicamente para no seguidores cuando se publica por primera vez, lo que te permite probar cómo funciona un Reel con una audiencia nueva antes de que llegue a tus seguidores existentes. Establece `trialParams.graduationStrategy` en `instagramOptions` para publicar un Reel como trial.

```json Instagram Trial Reel theme={"system"}
{
  "post": "Testing this with a fresh audience first",
  "mediaUrls": ["https://img.ayrshare.com/random/portrait1.mp4"],
  "platforms": ["instagram"],
  "instagramOptions": {
    "trialParams": {
      "graduationStrategy": "MANUAL"
    }
  }
}
```

`graduationStrategy` controla cómo un trial reel más tarde "gradúa" — es decir, se vuelve visible también para tus seguidores. Es obligatorio cuando se proporciona `trialParams` y debe ser uno de:

<ul class="custom-bullets">
  <li>
    <code>"MANUAL"</code> — la publicación permanece como trial reel hasta que la gradúes manualmente
    desde la app de Instagram.
  </li>

  <li>
    <code>"SS\_PERFORMANCE"</code> — Meta gradúa automáticamente el Reel según el rendimiento inicial
    frente a no seguidores.
  </li>
</ul>

<Note>
  La graduación en sí (promover un trial reel publicado a los seguidores) no está expuesta actualmente
  por la API de Meta y debe realizarse manualmente en la app de Instagram. Ayrshare añadirá un endpoint
  de graduación una vez que Meta lo exponga.
</Note>

### Restricciones de trial reels

La solicitud de trial reel se rechaza en el borde de Ayrshare — antes de cualquier llamada a Meta — cuando no se cumple alguna de estas condiciones:

<ul class="custom-bullets">
  <li>Exactamente una URL de medio que termine en <code>.mp4</code> o <code>.mov</code> (sin distinguir mayúsculas/minúsculas). Los carruseles no están admitidos.</li>
  <li><code>instagramOptions.stories</code> no debe ser <code>true</code>. Las Stories no pueden ser trial reels.</li>
  <li><code>graduationStrategy</code> debe estar presente y ser exactamente <code>"MANUAL"</code> o <code>"SS\_PERFORMANCE"</code> (distingue mayúsculas/minúsculas).</li>
</ul>

Los fallos devuelven uno de tres códigos de error de Ayrshare — consulta [Errores de Trial Reels de Instagram](/errors/errors-ayrshare#instagram-specific-error-codes) (<code>447</code>, <code>448</code>, <code>449</code>) para ver los payloads completos.

## Instagram Stories

Puedes publicar una sola imagen o video como Story de Instagram con las siguientes `instagramOptions`. Las Stories de Instagram desaparecen después de 24 horas.

```json Stories Post theme={"system"}
{
  "post": "The description of the video",
  "mediaUrls": ["https://img.ayrshare.com/random/portrait1.mp4"],
  "instagramOptions": {
    "stories": true
  }
}
```

Consulta los [requisitos de la API de Stories](/media-guidelines/instagram#stories).

<ul class="custom-bullets">
  <li>
    Las Stories de Instagram no admiten texto de publicación: cualquier texto proporcionado en el campo `post`, incluidas
    las menciones, será ignorado.
  </li>

  <li>Las Stories expiran después de 24 horas.</li>

  <li>
    Instagram actualmente solo admite la publicación de Stories en cuentas de Instagram Business y no en
    cuentas Creator.
  </li>

  <li>Las Stories de Instagram no admiten colaboradores.</li>
  <li>Instagram no admite la publicación de stickers (por ejemplo, enlace, encuesta, ubicación).</li>
</ul>

## Miniaturas de Reels

Puedes seleccionar un frame del Reel como imagen de miniatura o tu propia imagen de portada (thumbnail) desde una URL externa.

```json Instagram Thumbnail theme={"system"}
{
  "instagramOptions": {
    // milliseconds
    "thumbNailOffset": 30000,
    // If both thumbNail and thumbNailOffset includes, thumbNail will be used.
    "thumbNail": "https://img.ayrshare.com/012/gb.jpg"
  }
}
```

El offset es la ubicación en milisegundos del frame de miniatura del video del Reel. El valor por defecto es `0`, que corresponde al primer frame del Reel.

Si especificas tanto una URL de miniatura como un offset de miniatura, el offset será ignorado.

La miniatura del Reel debe cumplir con los [requisitos de miniatura de Reels](/media-guidelines/instagram#reels-thumbnails).
No se garantiza que las URLs firmadas con redirecciones sean compatibles con URLs de portada.
Recomendamos usar una URL no firmada o el [endpoint /media](/apis/media/overview).

## Texto alternativo

Añade texto alternativo de Instagram, también conocido como alt text, a una imagen.
El alt text de Instagram es una función de accesibilidad utilizada para brindar información adicional al usuario y para lectores de pantalla.

<ul class="custom-bullets">
  <li>El alt text admite hasta 1000 caracteres por imagen.</li>
  <li>Instagram no admite alt text para Reels o Stories.</li>
</ul>

Usa `altText` dentro del objeto `instagramOptions`.

```json Instagram Alt Text theme={"system"}
{
  "instagramOptions": {
    // Array of Alt Texts
    "altText": ["This is my best pic", "😃 here is the next one"]
  }
}
```

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

## Etiquetas de usuario y ubicaciones

<Info>
  El usuario de Instagram será notificado cuando uses su nombre de usuario en una publicación. Ten cuidado de
  no hacer spam a los usuarios ni publicar su nombre de usuario repetidamente. Si lo haces, Instagram podría suspender o
  desactivar tu cuenta.
</Info>

Se puede etiquetar una imagen o un Reel con usuarios de Instagram, y una imagen, video o Reel con una ubicación usando el parámetro `instagramOptions`.

### Ubicación

Una ubicación se especifica mediante un `locationId`, que es un ID de Página de Facebook o un nombre de Página de Facebook. Por ejemplo, el ID de página de Facebook del [Museo Guggenheim](https://www.facebook.com/guggenheimmuseum) es `7640348500` o el nombre de página de Facebook `"@guggenheimmuseum"`. Las páginas deben estar asociadas con una ubicación física.

```json Instagram Location theme={"system"}
// Using the Facebook Page Id - must be associated with a location
{
    "instagramOptions": {
        "locationId": 7640348500 // Guggenheim Museum Page Id
    }
}

// Using the Facebook Page name - must be associated with a location
{
    "instagramOptions": {
        "locationId": "@guggenheimmuseum" // Guggenheim Museum Page name. Must begin with @
    }
}
```

Puedes buscar el `locationId` (Page Id) con el [endpoint brand](/apis/brand/overview). Ten en cuenta que la Página debe tener una ubicación listada o el locationId devolverá un error.

<Note>No admitido en imágenes o videos dentro de carruseles.</Note>

### Etiquetas de usuario

Las etiquetas de Instagram te permiten etiquetar a otros usuarios de Instagram en tu publicación.
Los usuarios se especifican mediante `userTags`, que contiene un arreglo de objetos con un nombre de usuario de Instagram y coordenadas x/y (solo imagen). Las etiquetas de usuario se pueden agregar a imágenes individuales o Reels, pero no a videos normales, imágenes múltiples o Stories.

<ul class="custom-bullets">
  <li>Los nombres de usuario deben ser cuentas públicas de Instagram. No incluyas el @ del handle del usuario.</li>

  <li>
    Los valores `x` e `y` deben ser números `float` que se originen desde la esquina superior izquierda de la imagen, con un
    rango de `0.0`–`1.0`. Solo para imágenes individuales. No incluyas con Reels o se producirá un error.
  </li>
</ul>

```json Instagram User Tags theme={"system"}
{
  "instagramOptions": {
    "userTags": [
      {
        "username": "ayrshare", // Required: Instagram username
        "x": 0.5, // Required for Images, cannot be used with Reels
        "y": 1.0 // Required for Images, cannot be used with Reels
      },
      {
        "username": "johnboy", // Required: Instagram username
        "x": 0.1, // Required for Images, cannot be used with Reels
        "y": 0.9 // Required for Images, cannot be used with Reels
      }
    ]
  }
}
```

## Menciones en Instagram

Menciona a otro handle de Instagram agregando @handle en el texto de la publicación.

Por ejemplo, puedes mencionar al handle @ayrshare en el texto de la publicación:

```json Instagram Mentions theme={"system"}
{
  "post": "The best social media API @Ayrshare ever!", // empty string is allowed
  "mediaUrls": ["https://images.com/image.jpg"],
  "platforms": ["instagram"]
}
```

<Warning>
  El usuario `@mencionado` será notificado de la mención. Consulta las [reglas
  importantes](/testing/post-verification#mentions) sobre menciones.
</Warning>

## Colaboración

La colaboración de Instagram te permite ser coautor de contenido con otras cuentas de Instagram [etiquetando a otros como colaboradores](https://www.facebook.com/help/instagram/291200585956732).
Esto te permite designar a otros usuarios de Instagram como creadores en tu publicación.
Al ser etiquetados, estos usuarios reciben una invitación para colaborar en la app móvil.
Si aceptan, la publicación también aparecerá en su feed y será visible para sus seguidores, ampliando el alcance y el potencial de interacción de la publicación.

### Colaboradores

El autor original público puede etiquetar a otra cuenta pública como colaborador de Instagram.
La otra cuenta recibirá un mensaje que le permitirá aceptar o rechazar la solicitud.
Si la otra cuenta acepta, la publicación también aparecerá en su perfil y se distribuirá a sus seguidores en el feed de Instagram.
El encabezado de la publicación atribuirá el contenido a ambas cuentas.

Puedes añadir colaboradores a un Reel, imagen o carrusel.

Etiquetar a un colaborador privado no está permitido a través de la API de Instagram. Aunque
esta funcionalidad existe dentro de la app de Instagram, las plataformas y sus APIs
a menudo no están a la [paridad de funciones](/help-center/product/are_social_networks_native_apps_and_the_apis_at_parity).

<Warning>Las Stories de Instagram no admiten colaboradores.</Warning>

<Warning>
  <ul class="custom-bullets">
    <li>**Solo invita a colaboradores que esperes que `acepten` tu invitación**.</li>

    <li>
      Si el [colaborador
      responde](/apis/post/social-networks/instagram#get-collaborator-request-status) con una
      solicitud de colaboración `declined`, **no lo invites de nuevo** hasta que contactes con él para
      entender la razón del rechazo.
    </li>

    <li>
      Los rechazos repetidos del mismo usuario o de varios pondrán tu cuenta de Instagram y de Ayrshare
      en riesgo de cancelación.
    </li>

    <li>El autor original puede añadir o quitar un colaborador en cualquier momento.</li>
  </ul>
</Warning>

Invita a *hasta tres* colaboradores usando un arreglo de nombres de usuario públicos de Instagram.

```json Instagram Collaborators theme={"system"}
{
  "instagramOptions": {
    "collaborators": ["ayrshare", "therock", "taylorswift"] // Up to three
  }
}
```

Estos tres colaboradores recibirán una invitación por mensaje en su app móvil de Instagram y podrán aceptar o rechazar la invitación; luego podrás [comprobar el estado de la solicitud del usuario invitado](/apis/post/social-networks/instagram#get-collaborator-request-status).
Invita solo a colaboradores que sepas que aceptarán tu solicitud o tu cuenta de Instagram podría verse afectada negativamente.

<Warning>
  Nota sobre los colaboradores invitados: con algunas excepciones, los datos sobre el contenido coautorado solo
  pueden ser accedidos a través de la API por el usuario que publicó el contenido; los colaboradores no pueden
  acceder a estos datos a través de la API.
</Warning>

### Obtener el estado de la solicitud de colaborador

Después de invitar a un colaborador de Instagram, puedes verificar el estado de la solicitud usando la [API para obtener el estado de la solicitud de colaborador](/apis/utils/instagram-get-collaborator).

## Redimensionamiento automático de imagen

<Note>Se requiere Max Pack</Note>

Las imágenes se redimensionan automáticamente a 1080 x 1080 px para funcionar con Instagram usando el parámetro `autoResize`. Ten en cuenta que esto redimensionará la imagen para todas las plataformas incluidas, por lo que recomendamos hacer una llamada para Instagram y una llamada /post diferente para otras plataformas.

```json Instagram Auto Image Resize theme={"system"}
{
  "post": "Let it go!",
  "platforms": ["instagram"],
  "mediaUrls": ["https://images.ayrshare.com/imgs/GhostBusters.jpg"],
  "instagramOptions": {
    "autoResize": true, // Max Pack
    "locationId": 7640348500,
    "userTags": [
      {
        "username": "ayrshare",
        "x": 0.5,
        "y": 0.5
      },
      {
        "username": "ayrshare",
        "x": 0.3,
        "y": 0.2
      }
    ]
  }
}
```

## Cuota utilizada

La respuesta de Instagram incluirá el `usedQuota` actual con el número de publicaciones de Instagram realizadas durante un período móvil de 24 horas. Instagram solo permite 50 publicaciones de Instagram en un período móvil de 24 horas.

```json Instagram Used Quota theme={"system"}
{
    "status": "success",
    "errors": [],
    "postIds": [
        {
            "status": "success",
            "id": "17823977408036085",
            "postUrl": "https://www.instagram.com/p/CeBrkQuN1Kv/",
            "usedQuota": 15,
            "platform": "instagram"
        }
    ],
    "id": "l4FaPHSXWJNdmMfm3dIE",
    "refId": "65806e8d9efd78a58c05566a887043329dcdc76b",
    "post": "Luckily for Alice, the little magic bottle had now had its full effect."
}
```

Si se ha alcanzado la cuota, se devolverá un mensaje de error.

## Problemas de contenido

Ayrshare incluye protección de medios integrada que puede detectar y resolver ciertos problemas de entrega de medios durante la publicación. Cuando una publicación tiene éxito pero se detectó y resolvió un problema de contenido, la respuesta incluye un objeto opcional `contentIssues`. Esto te permite identificar y solucionar de forma proactiva los problemas con el hosting de tus medios.

El objeto `contentIssues` solo está presente cuando se detectó y resolvió un problema — las publicaciones exitosas normales no lo incluyen.

| Campo                   | Tipo             | Descripción                                                                                                                                                                                                                                                                                                                                                   |
| ----------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `originMediaHostFailed` | boolean          | La red social no pudo obtener el medio desde la URL proporcionada. La protección automatizada de medios de Ayrshare resolvió el problema y completó la publicación con éxito. Considera revisar tu configuración de hosting de medios — consulta [Meta Media Crawler Blocked](/help-center/technical-support/meta_media_crawler_blocked) para causas comunes. |
| `details`               | array of strings | Descripciones legibles por humanos de cada problema detectado.                                                                                                                                                                                                                                                                                                |

```json Content Issues Response Example theme={"system"}
{
    "status": "success",
    "errors": [],
    "postIds": [
        {
            "status": "success",
            "id": "17878176260289172",
            "postUrl": "https://www.instagram.com/p/CP1dI9Hp_WO/",
            "usedQuota": 12,
            "platform": "instagram",
            "contentIssues": {
                "originMediaHostFailed": true,
                "details": [
                    "Media URL could not be retrieved by the social network. Successfully posted using Ayrshare automated media protection."
                ]
            }
        }
    ],
    "id": "abc123",
    "refId": "65806e8d9efd78a58c05566a887043329dcdc76b",
    "post": "Your post text here"
}
```

<Tip>
  Si ves `originMediaHostFailed` en tus respuestas, puede haber un problema con el hosting de tus medios que impide que las redes sociales accedan a ellos. Consulta [Meta Media Crawler Blocked](/help-center/technical-support/meta_media_crawler_blocked) para los pasos detallados de solución de problemas.
</Tip>

## Detalles de errores

<Info>
  Cuando falla una publicación de medios en Instagram, el objeto de error ahora expone el texto de error subyacente de Meta en el campo `details`, junto con el `code` y `message` de Ayrshare. Esto te permite distinguir entre distintas causas raíz (por ejemplo, un rechazo por relación de aspecto frente a un fallo de descarga de medios) sin tener que contactar con soporte.
</Info>

```json Instagram Publish Error theme={"system"}
{
    "status": "error",
    "errors": [
        {
            "action": "post",
            "status": "error",
            "platform": "instagram",
            "code": 156,
            "message": "An error occurred while posting to Instagram.",
            "details": "The submitted image was not found. The aspect ratio is not supported. Please see https://developers.facebook.com/docs/instagram-api for more information."
        }
    ]
}
```

El `message` es el resumen estable y legible por humanos de Ayrshare, mientras que `details` refleja el texto sin procesar devuelto por Meta para la publicación fallida.

## Agregar saltos de línea o texto enriquecido a una publicación de Instagram

Se pueden agregar saltos de línea de Instagram a una publicación con un [carácter especial de nueva línea](/apis/post/post#line-breaks).

Se puede añadir texto enriquecido, como letras en negrita o cursiva, a una publicación de Instagram con algunos [elementos HTML](/apis/post/overview#rich-text-posts).

## Límites de caracteres

Consulta [Límites de caracteres de Instagram](/help-center/technical-support/character_limits#instagram-character-limits) para más información.

## Endpoints adicionales

<Card title="Obtener el estado de la solicitud de colaborador" icon="code" href="/apis/utils/instagram-get-collaborator" horizontal />