> ## 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 do Instagram

> Opções para publicar usando a API do Instagram

<Info>
  Se você tiver problemas para conectar o Instagram, consulte o [guia de
  solução de problemas](/help-center/technical-support/facebook_or_instagram_linking_issues).
</Info>

<Info>
  Se sua mídia estiver hospedada em um servidor ou CDN que você controla, certifique-se de que o crawler de publicação da Meta
  consiga acessá-la. Consulte [Meta Media Crawler Blocked](/help-center/technical-support/meta_media_crawler_blocked)
  se você vir o código de erro 440 do Ayrshare ("social network could not download media from this URL") ou o código de erro 138 com "Restricted by robots.txt" nos detalhes.
</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>

A API do Instagram tem os seguintes requisitos e restrições.

<ul class="custom-bullets">
  <li>
    Conta Business ou Creator do Instagram conectada a uma Facebook Page - [veja
    aqui](/dashboard/connect-social-accounts/instagram).
  </li>

  <li>Apenas 50 publicações no Instagram são permitidas em um período de 24 horas. Veja abaixo `usedQuota`.</li>

  <li>
    O texto de `post` pode conter até *5 hashtags* (por exemplo, #wildtimes) e *3 menções a usuários*
    (por exemplo, @natgeo).
  </li>

  <li>Menções (@mention) a usuários do Instagram receberão uma notificação.</li>
  <li>Máximo de 2.200 caracteres na publicação.</li>

  <li>
    Publicações com múltiplas imagens/vídeos são suportadas e enviadas como carrossel. Você pode enviar até 10 vídeos e
    imagens.
  </li>

  <li>
    O Instagram não suporta exclusões via API. As exclusões devem ocorrer manualmente usando o aplicativo do Instagram.
  </li>

  <li>
    Se seu vídeo de Reel não terminar em uma extensão de vídeo conhecida, como mp4, use o parâmetro `isVideo`.
    Consulte o [endpoint /post](/apis/post/post) para detalhes.
  </li>

  <li>
    O Instagram também suporta envio de mídia sem texto de publicação. Se você não quiser incluir texto na publicação,
    envie uma String vazia `post: ""`.
  </li>

  <li>Consulte as [Diretrizes de mídia do Instagram](/media-guidelines/instagram) e a [Autorização do Instagram](/dashboard/connect-social-accounts/instagram) para mais informações.</li>
</ul>

## Publicando no Instagram

JSON para uma publicação básica com imagem e hashtags no 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"]
}
```

Hashtags são clicáveis em publicações do Instagram, mas links não.

<Note>
  A proporção de aspecto de imagens e vídeos e a duração dos vídeos são muito importantes para publicar com sucesso no Instagram. Se não atenderem aos requisitos, a publicação será rejeitada.

  [Consulte a seção do Instagram nas Diretrizes de imagem e vídeo](/media-guidelines/instagram).
</Note>

## Conta Business ou Creator do Instagram

Sua conta do Instagram deve ser uma Conta Business ou Creator e estar conectada a uma Facebook Page. A configuração é gratuita e fácil.

Consulte aqui as instruções detalhadas:

<Card title="Vinculação do Instagram" icon="link" href="/dashboard/connect-social-accounts/instagram" horizontal />

## Carrossel de imagens e vídeos

Você pode publicar várias imagens ou vídeos de Reel no Instagram como um carrossel; um total combinado de até 10 imagens ou vídeos pode ser usado em um carrossel.
Basta adicionar suas imagens ou vídeos adicionais ao array `mediaUrls`, e o carrossel será criado automaticamente.

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

<Note>
  URLs de vídeo devem terminar em uma extensão conhecida, como `mp4`. O parâmetro `isVideo` não é suportado
  para carrosséis do Instagram.
</Note>

## Instagram Reels

No Instagram, uma publicação de vídeo é chamada de Reel.
Você pode publicar um vídeo na API do Instagram Reels com as seguintes opções opcionais em `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>
    Consulte os [requisitos de vídeo da API do Reels](/media-guidelines/instagram#reels) para detalhes sobre
    os requisitos do vídeo.
  </li>

  <li>
    `shareReelsFeed`: Booleano definido como `true` para indicar que o Reel *pode* aparecer tanto na aba
    **Feed** quanto na **Reels**, ou `false` para indicar que o Reel *só* pode aparecer na aba **Reels**.
    Este valor é uma dica ao Instagram sobre onde você gostaria que o Reel aparecesse, mas nenhum
    valor determina se o Reel *realmente* aparecerá nas abas **Reels** ou **Feed**, pois
    o Reel pode não atender aos requisitos de elegibilidade ou pode não ser selecionado pelo algoritmo do Instagram.
  </li>

  <li>
    `audioName`: String com o nome do áudio/música da sua mídia de Reels. Você só pode renomear uma vez, seja
    ao criar um reel ou depois, na página de áudio. Por exemplo, `"The Weeknd - Blinding
            Lights"`.
  </li>

  <li>
    `thumbNail`: String com a URL da imagem de capa (thumbnail) do Reel. Veja aqui [detalhes sobre
    thumbNail](/apis/post/social-networks/instagram#reels-thumbnails).
  </li>

  <li>
    `thumbNailOffset`: Deslocamento inteiro em milissegundos do frame do thumbnail. Veja aqui
    [detalhes sobre thumbNailOffset.](/apis/post/social-networks/instagram#reels-thumbnails)
  </li>
</ul>

Consulte os [requisitos de vídeo da API do Reels](/media-guidelines/instagram#reels) ou um [exemplo de uso da API do Instagram Reels](https://www.ayrshare.com/blog/instagram-reels-api-how-to-post-videos-to-reels-using-a-social-media-api/).

Você também pode definir uma [URL de capa do Reels](/apis/post/social-networks/instagram#reels-thumbnails) e [tags de localização e usuário](/apis/post/social-networks/instagram#user-tags-and-locations).

## Trial Reels

Um trial reel é um Reel que é publicado apenas para não seguidores quando é postado pela primeira vez, permitindo que você teste como o Reel se comporta com um público novo antes de alcançar seus seguidores existentes. Defina `trialParams.graduationStrategy` em `instagramOptions` para publicar um Reel como um 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"
    }
  }
}
```

O `graduationStrategy` controla como um trial reel posteriormente "gradua" — ou seja, torna-se visível para seus seguidores também. É obrigatório quando `trialParams` é fornecido e deve ser um dos seguintes:

<ul class="custom-bullets">
  <li>
    <code>"MANUAL"</code> — a publicação permanece como trial reel até que você a gradue manualmente
    de dentro do aplicativo do Instagram.
  </li>

  <li>
    <code>"SS\_PERFORMANCE"</code> — a Meta gradua automaticamente o Reel com base no desempenho inicial
    entre não seguidores.
  </li>
</ul>

<Note>
  A graduação em si (promover um trial reel publicado para os seguidores) atualmente não é exposta pela
  API da Meta e deve ser feita manualmente no aplicativo do Instagram. O Ayrshare adicionará um endpoint de graduação
  assim que a Meta expuser um.
</Note>

### Restrições de trial reel

A requisição de trial reel é rejeitada na borda do Ayrshare — antes de qualquer chamada à Meta — quando qualquer uma dessas condições não é atendida:

<ul class="custom-bullets">
  <li>Exatamente uma URL de mídia terminando em <code>.mp4</code> ou <code>.mov</code> (não diferencia maiúsculas de minúsculas). Carrosséis não são suportados.</li>
  <li><code>instagramOptions.stories</code> não pode ser <code>true</code>. Stories não podem ser trial reels.</li>
  <li><code>graduationStrategy</code> deve estar presente e ser exatamente <code>"MANUAL"</code> ou <code>"SS\_PERFORMANCE"</code> (diferencia maiúsculas de minúsculas).</li>
</ul>

Falhas retornam um dos três códigos de erro do Ayrshare — veja [Erros de trial reel do Instagram](/errors/errors-ayrshare#instagram-specific-error-codes) (<code>447</code>, <code>448</code>, <code>449</code>) para os payloads completos.

## Instagram Stories

Você pode publicar uma única imagem ou vídeo como Story do Instagram com as seguintes `instagramOptions`. Os Stories do Instagram desaparecem após 24 horas.

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

Consulte os [requisitos da API de Stories](/media-guidelines/instagram#stories).

<ul class="custom-bullets">
  <li>
    Instagram Stories não suportam texto de publicação — qualquer texto fornecido no campo `post`, incluindo
    menções, será ignorado.
  </li>

  <li>Stories expiram após 24 horas.</li>

  <li>
    O Instagram atualmente suporta a publicação de Stories apenas em contas Business do Instagram e não
    em contas Creator.
  </li>

  <li>Instagram Stories não suportam colaboradores.</li>
  <li>Publicar stickers (por exemplo, link, enquete, localização) não é suportado pelo Instagram.</li>
</ul>

## Thumbnails de Reels

Você pode selecionar um frame do Reel como imagem de thumbnail ou sua própria imagem de capa (thumbnail) a partir de uma 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"
  }
}
```

O offset é a posição em milissegundos do frame do thumbnail do vídeo do Reel. O valor padrão é `0`, que é o primeiro frame do Reel.

Se você especificar tanto uma URL de thumbnail quanto um offset, o offset será ignorado.

A thumbnail do Reel deve seguir os [requisitos de thumbnail do Reels](/media-guidelines/instagram#reels-thumbnails).
URLs assinadas com redirecionamentos não são garantidas como compatíveis com URLs de capa.
Recomendamos uma URL não assinada ou o uso do [endpoint /media](/apis/media/overview).

## Texto alternativo

Adicione texto alternativo (alt text) do Instagram a uma imagem.
O alt text do Instagram é um recurso de acessibilidade usado para fornecer informações adicionais ao usuário e para leitores de tela.

<ul class="custom-bullets">
  <li>O alt text suporta até 1.000 caracteres por imagem.</li>
  <li>O Instagram não suporta alt text para Reels ou Stories.</li>
</ul>

Use `altText` no 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 deve corresponder a uma imagem ou vídeo no array `mediaUrls`.
O alt text será aplicado a cada imagem na ordem.

## Tags de usuário e localização

<Info>
  O usuário do Instagram será notificado quando você usar seu nome de usuário em uma publicação. Tenha cuidado para
  não spammar usuários nem publicar com seu nome de usuário repetidamente. Se fizer isso, o Instagram poderá suspender ou
  desativar sua conta.
</Info>

Uma imagem ou um Reel pode ser marcado com usuários do Instagram, e uma imagem, vídeo ou Reel pode ser marcado com uma localização usando o parâmetro `instagramOptions`.

### Localização

Uma localização é especificada por um `locationId`, que é um ID de Facebook Page ou nome de Facebook Page. Por exemplo, o Page ID do [Guggenheim Museum](https://www.facebook.com/guggenheimmuseum) é `7640348500` ou o nome da Facebook Page `"@guggenheimmuseum"`. As Pages devem estar associadas a uma localização 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 @
    }
}
```

Você pode consultar o `locationId` (Page Id) com o [endpoint brand](/apis/brand/overview). Observe que a Page deve ter uma localização listada, ou o locationId retornará um erro.

<Note>Não suportado em imagens ou vídeos em carrosséis.</Note>

### Tags de usuário

As tags do Instagram permitem marcar outros usuários do Instagram na sua publicação.
Os usuários são especificados por um `userTags` contendo um Array de objetos com um nome de usuário do Instagram e coordenadas x/y (apenas para imagens). As tags de usuário podem ser adicionadas para imagens únicas ou Reels, mas não para vídeos regulares, múltiplas imagens ou Stories.

<ul class="custom-bullets">
  <li>Os nomes de usuário devem ser contas públicas do Instagram. Não inclua o @ do handle do usuário.</li>

  <li>
    Os valores `x` e `y` devem ser números `float` que se originam no canto superior esquerdo da imagem, com um
    intervalo de `0.0`–`1.0`. Imagens únicas. Não inclua com Reels ou ocorrerá um erro.
  </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
      }
    ]
  }
}
```

## Menções no Instagram

Mencione outro usuário do Instagram adicionando @handle no texto da publicação.

Por exemplo, você pode mencionar o handle @ayrshare no texto da publicação:

```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>
  O usuário `@mencionado` será notificado da menção. Revise as [regras
  importantes](/testing/post-verification#mentions) sobre menções.
</Warning>

## Colaboração

A colaboração no Instagram permite que você seja coautor de conteúdo com outras contas do Instagram [marcando outros como colaboradores](https://www.facebook.com/help/instagram/291200585956732).
Isso permite designar outros usuários do Instagram como criadores em sua publicação.
Quando marcados, esses usuários recebem um convite para colaborar no aplicativo móvel.
Se aceitarem, a publicação também aparecerá no feed deles e será visível para seus seguidores, ampliando o alcance e o potencial de engajamento da publicação.

### Colaboradores

O autor público original pode marcar outra conta pública como colaborador do Instagram.
A outra conta receberá uma mensagem, permitindo aceitar ou recusar a solicitação.
Se a outra conta aceitar, a publicação também aparecerá no perfil dela e será distribuída aos seus seguidores no feed do Instagram.
O cabeçalho da publicação atribuirá o conteúdo a ambas as contas.

Você pode adicionar colaboradores a um Reel, imagem ou carrossel.

Marcar um colaborador privado não é permitido via API do Instagram. Embora
essa funcionalidade exista dentro do aplicativo do Instagram, plataformas e suas APIs
frequentemente não estão em [paridade de recursos](/help-center/product/are_social_networks_native_apps_and_the_apis_at_parity).

<Warning>Instagram Stories não suportam colaboradores.</Warning>

<Warning>
  <ul class="custom-bullets">
    <li>**Convide apenas colaboradores que você espera que `aceitem` seu convite**.</li>

    <li>
      Se o [colaborador
      responder](/apis/post/social-networks/instagram#get-collaborator-request-status) com uma
      solicitação de colaboração `declined`, **não os convide novamente** até entrar em contato com eles para
      entender o motivo da recusa.
    </li>

    <li>
      Recusas repetidas do mesmo usuário ou de vários usuários colocarão suas contas do Instagram e do Ayrshare
      em risco de cancelamento.
    </li>

    <li>O autor original pode adicionar ou remover um colaborador a qualquer momento.</li>
  </ul>
</Warning>

Convide *até três* colaboradores com um array de nomes de usuário públicos do Instagram.

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

Esses três colaboradores receberão um convite por mensagem no aplicativo móvel do Instagram e poderão aceitar ou recusar o convite; em seguida, você pode [verificar o status da solicitação do usuário convidado](/apis/post/social-networks/instagram#get-collaborator-request-status).
Convide apenas colaboradores que você sabe que aceitarão seu pedido, caso contrário sua conta do Instagram pode ser afetada negativamente.

<Warning>
  Observação sobre colaboradores convidados: Com poucas exceções, dados sobre mídia coautorada
  só podem ser acessados via API pelo usuário que publicou a mídia; colaboradores não conseguem
  acessar esses dados via API.
</Warning>

### Obter status da solicitação de colaborador

Depois de convidar um colaborador do Instagram, você pode verificar o status da solicitação usando a [API Get Collaborator Request Status](/apis/utils/instagram-get-collaborator).

## Redimensionamento automático de imagem

<Note>Max Pack necessário</Note>

As imagens são redimensionadas automaticamente para 1080 x 1080 px para funcionar com o Instagram com o parâmetro `autoResize`. Observe que isso redimensionará a imagem para todas as plataformas incluídas, portanto recomendamos fazer uma chamada para o Instagram e outra chamada /post para as plataformas adicionais.

```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
      }
    ]
  }
}
```

## Cota utilizada

A resposta do Instagram incluirá o `usedQuota` atual para o número de publicações do Instagram feitas em um período móvel de 24 horas. Apenas 50 publicações no Instagram são permitidas pelo Instagram em um período móvel 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."
}
```

Se a cota tiver sido atingida, uma mensagem de erro será retornada.

## Problemas de conteúdo

O Ayrshare inclui proteção de mídia integrada que pode detectar e resolver certos problemas de entrega de mídia durante a publicação. Quando uma publicação é bem-sucedida, mas um problema de conteúdo foi detectado e resolvido, a resposta inclui um objeto opcional `contentIssues`. Isso permite identificar e corrigir problemas com sua hospedagem de mídia de forma proativa.

O objeto `contentIssues` só está presente quando um problema foi detectado e resolvido — publicações bem-sucedidas normais não o incluem.

| Campo                   | Tipo             | Descrição                                                                                                                                                                                                                                                                                                                                            |
| ----------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `originMediaHostFailed` | boolean          | A rede social não conseguiu recuperar a mídia da URL fornecida. A proteção automatizada de mídia do Ayrshare resolveu o problema e concluiu a publicação com sucesso. Considere revisar a configuração da sua hospedagem de mídia — veja [Meta Media Crawler Blocked](/help-center/technical-support/meta_media_crawler_blocked) para causas comuns. |
| `details`               | array de strings | Descrições legíveis 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>
  Se você vir `originMediaHostFailed` em suas respostas, pode haver um problema com a hospedagem da sua mídia que impede que as redes sociais acessem sua mídia. Veja [Meta Media Crawler Blocked](/help-center/technical-support/meta_media_crawler_blocked) para etapas detalhadas de solução de problemas.
</Tip>

## Detalhes de erro

<Info>
  Quando uma publicação de mídia do Instagram falha, o objeto de erro agora expõe o texto de erro subjacente da Meta no campo `details`, ao lado do `code` e `message` do Ayrshare. Isso permite distinguir entre diferentes causas-raiz (por exemplo, uma rejeição por proporção de aspecto versus uma falha no download da mídia) sem contatar o suporte.
</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."
        }
    ]
}
```

O `message` é o resumo estável e legível do Ayrshare, enquanto `details` reflete o texto bruto retornado pela Meta para a publicação com falha.

## Adicionando quebras de linha ou rich text a uma publicação do Instagram

Quebras de linha do Instagram podem ser adicionadas a uma publicação com um [caractere de nova linha especial](/apis/post/post#line-breaks).

Rich text, como negrito ou itálico, pode ser adicionado a uma publicação do Instagram com alguns [elementos HTML](/apis/post/overview#rich-text-posts).

## Limites de caracteres

Consulte [Limites de caracteres do Instagram](/help-center/technical-support/character_limits#instagram-character-limits) para mais informações.

## Endpoints adicionais

<Card title="Obter status da solicitação de colaborador" icon="code" href="/apis/utils/instagram-get-collaborator" horizontal />