> ## Documentation Index > Fetch the complete documentation index at: https://docs.postclean.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Anexar mídia por URL > Baixa até 10 arquivos públicos e os adiciona ao fim das mídias do post. Cada URL precisa entregar o próprio arquivo: redirecionamentos não são seguidos, e páginas web, hosts de rede privada e arquivos acima do limite do tipo são recusados. Cada download tem até 20 segundos. Só são aceitos os tipos de mídia que todos os canais ativos do post aceitam. As URLs que não puderam ser anexadas aparecem em `failed_urls`, e `failures` traz o motivo de cada uma; a resposta é `200` mesmo quando nenhuma foi anexada. Posts publicando, publicados ou com falha não aceitam mídia: `422` em `post` com `Este post já foi processado e não pode ser republicado. Duplique-o para tentar de novo.` (só quando algum arquivo foi baixado). Arquivos aceitos: imagens JPEG, PNG, GIF e WebP (também HEIC e HEIF quando o servidor consegue convertê-los, e nesse caso são salvos como JPEG), vídeos MP4 e MOV e documentos PDF. Limites de tamanho: 10 MB por imagem (e no máximo 8192 x 8192 pixels, cerca de 67 megapixels), 1 GB por vídeo e 100 MB por PDF. Cada rede aplica seus próprios limites, em geral menores, quando o post é agendado ou publicado (veja `GET /content-types`). No Pinterest e no TikTok o `content_type` de cada destino é escolhido de novo a partir das mídias do post, como na criação. As mensagens de validação seguem o idioma do servidor, português no PostClean. ## OpenAPI ````yaml /openapi.json post /posts/{post}/media/from-url openapi: 3.1.0 info: title: PostClean API version: 2.0.0 description: >- API REST do PostClean. Autentique com uma chave de API do workspace, enviada como token Bearer no cabeçalho `Authorization`. servers: - url: https://post.chatclean.com.br/api description: PostClean security: - bearerAuth: [] tags: - name: Posts description: Criar, ler, atualizar, excluir e pré-visualizar posts. - name: Post notes description: Notas internas de um post, visíveis aos membros do workspace. - name: Approvals description: Aprovar ou rejeitar posts que aguardam aprovação. - name: Recurrence description: Fazer um post se repetir numa frequência. - name: Media and uploads description: Enviar arquivos e anexar mídia aos posts. - name: Social accounts description: Contas sociais conectadas e as opções de cada rede. - name: Channels description: Horários de postagem e fila de um canal. - name: Ideas description: Ideias do quadro Criar. - name: Idea stages description: As colunas (etapas) do quadro de ideias. - name: Analytics description: Métricas do workspace e dos canais. - name: Labels description: Etiquetas para organizar posts e ideias. - name: Signatures description: Textos reutilizáveis para adicionar aos posts. - name: Workspace description: O workspace ao qual a chave de API pertence. - name: API keys description: Chaves de API pessoais deste workspace. - name: Webhooks description: Webhooks de saída e os registros de entrega. - name: Repurposes description: Automações que republicam vídeos postados fora do PostClean. - name: Platform description: Recursos de cada plataforma e tipos de conteúdo. paths: /posts/{post}/media/from-url: parameters: - $ref: '#/components/parameters/PostId' post: tags: - Media and uploads summary: Anexar mídia por URL description: >- Baixa até 10 arquivos públicos e os adiciona ao fim das mídias do post. Cada URL precisa entregar o próprio arquivo: redirecionamentos não são seguidos, e páginas web, hosts de rede privada e arquivos acima do limite do tipo são recusados. Cada download tem até 20 segundos. Só são aceitos os tipos de mídia que todos os canais ativos do post aceitam. As URLs que não puderam ser anexadas aparecem em `failed_urls`, e `failures` traz o motivo de cada uma; a resposta é `200` mesmo quando nenhuma foi anexada. Posts publicando, publicados ou com falha não aceitam mídia: `422` em `post` com `Este post já foi processado e não pode ser republicado. Duplique-o para tentar de novo.` (só quando algum arquivo foi baixado). Arquivos aceitos: imagens JPEG, PNG, GIF e WebP (também HEIC e HEIF quando o servidor consegue convertê-los, e nesse caso são salvos como JPEG), vídeos MP4 e MOV e documentos PDF. Limites de tamanho: 10 MB por imagem (e no máximo 8192 x 8192 pixels, cerca de 67 megapixels), 1 GB por vídeo e 100 MB por PDF. Cada rede aplica seus próprios limites, em geral menores, quando o post é agendado ou publicado (veja `GET /content-types`). No Pinterest e no TikTok o `content_type` de cada destino é escolhido de novo a partir das mídias do post, como na criação. As mensagens de validação seguem o idioma do servidor, português no PostClean. operationId: attachMediaFromUrl requestBody: required: true content: application/json: schema: type: object required: - urls properties: urls: type: array minItems: 1 maxItems: 10 items: type: object required: - url properties: url: type: string format: uri description: >- URL pública `http` ou `https` cujo host resolve no DNS. alt: type: - string - 'null' maxLength: 2000 description: Texto alternativo. Vale só para imagens. description: De 1 a 10 arquivos. example: urls: - url: https://example.com/lancamento.jpg alt: Banner de lançamento do produto - url: https://example.com/teaser.mp4 responses: '200': description: O post e o resultado de cada URL. content: application/json: schema: type: object properties: post: $ref: '#/components/schemas/Post' attached_count: type: integer description: Quantos arquivos foram anexados. failed_urls: type: array items: type: string description: URLs que não foram anexadas. failures: type: array items: type: object properties: url: type: string reason: type: string enum: - unreachable - type_not_allowed - too_large - host_not_allowed description: >- `unreachable`: não foi possível baixar; `type_not_allowed`: tipo não aceito pelo post; `too_large`: acima do limite do tipo; `host_not_allowed`: host privado ou bloqueado. message: type: string description: Mensagem legível do erro. required: - url - reason - message description: Motivo de cada URL que falhou. required: - post - attached_count - failed_urls - failures example: post: id: 9d3c1f2a-6b4e-4c8a-9f1e-2a7b5c8d0e41 post_group_id: 9d3c1f29-e0a1-4b7c-8d2e-5f6a7b8c9d03 author: id: 9b1e2d3c-4f5a-4b6c-8d7e-9f0a1b2c3d4e name: Ana Souza content: Lançamos as sequências agendadas. Veja como funcionam. media: - id: 9d3c1f30-8a9b-4c0d-9e1f-2a3b4c5d6e7f path: medias/9d3c1f30-8a9b-4c0d-9e1f-2a3b4c5d6e7f.jpg url: >- https://example.com/medias/9d3c1f30-8a9b-4c0d-9e1f-2a3b4c5d6e7f.jpg type: image mime_type: image/jpeg original_filename: lancamento.jpg size: 482113 meta: width: 1080 height: 1350 alt_text: Banner de lançamento do produto status: scheduled schedule_mode: custom scheduled_at: '2026-11-12 14:00:00' published_at: null approval_requested_by: null approval_requested_at: null approved_by: null approved_at: null recurrence: null origin: trypost platforms: - id: 9d3c1f2b-1a2b-4c3d-8e4f-5a6b7c8d9e0f platform: x content_type: x_post meta: thread_replies: - text: 2/ As respostas saem logo abaixo do primeiro post. media: [] status: pending enabled: true platform_url: null published_at: null error_message: null display_name: PostClean display_username: postclean display_avatar: >- https://pbs.twimg.com/profile_images/1790000000000000000/avatar_400x400.jpg social_account: id: 9c8b7a65-4d3e-4f2a-8b1c-0d9e8f7a6b54 platform: x display_name: PostClean username: postclean status: connected has_posting_schedule: true timezone: America/Sao_Paulo posting_goal: 5 max_content_length: 280 long_posts: false verified_badge: null labels: - id: 9c0d1e2f-3a4b-4c5d-8e6f-7a8b9c0d1e2f name: Lançamento color: '#2563EB' created_at: '2026-10-01 10:00:00' updated_at: '2026-10-01 10:00:00' created_at: '2026-11-06 13:20:11' updated_at: '2026-11-06 13:20:11' attached_count: 1 failed_urls: - https://example.com/teaser.mp4 failures: - url: https://example.com/teaser.mp4 reason: unreachable message: Could not fetch media from https://example.com/teaser.mp4. '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/ValidationError' '429': $ref: '#/components/responses/TooManyRequests' components: parameters: PostId: name: post in: path required: true description: Id do post. Um post de outro workspace devolve `404`. schema: type: string format: uuid example: 9d3c1f2a-6b4e-4c8a-9f1e-2a7b5c8d0e41 schemas: Post: type: object description: >- Um post em um canal. Posts criados juntos para vários canais são posts independentes que compartilham o mesmo `post_group_id`. O canal, o formato, as configurações da rede e o resultado da publicação ficam em `platforms`. properties: id: type: string format: uuid post_group_id: type: - string - 'null' format: uuid description: Igual em todos os posts criados na mesma requisição. author: oneOf: - $ref: '#/components/schemas/Person' - type: 'null' content: type: - string - 'null' description: >- Texto do post, guardado como foi enviado (posts escritos no app guardam o HTML do editor). media: type: - array - 'null' items: $ref: '#/components/schemas/MediaItem' status: type: string enum: - draft - pending_approval - scheduled - publishing - published - partially_published - failed description: >- Ciclo de vida do post no PostClean. `pending_approval` é um post que um membro que precisa de aprovação pediu para agendar ou publicar. `partially_published` aparece em posts antigos com vários destinos quando só parte deles foi publicada. O resultado em cada rede fica em `platforms[].status`. schedule_mode: type: - string - 'null' enum: - queue - custom - null description: >- `queue`: o post ocupa um horário da grade de postagem do canal. `custom`: está agendado num horário próprio. scheduled_at: type: - string - 'null' description: UTC, no formato `Y-m-d H:i:s`. published_at: type: - string - 'null' description: UTC, no formato `Y-m-d H:i:s`. approval_requested_by: oneOf: - $ref: '#/components/schemas/Person' - type: 'null' description: Quem pediu a aprovação (nem sempre é o autor). approval_requested_at: type: - string - 'null' description: UTC, no formato `Y-m-d H:i:s`. approved_by: oneOf: - $ref: '#/components/schemas/Person' - type: 'null' approved_at: type: - string - 'null' description: UTC, no formato `Y-m-d H:i:s`. recurrence: type: - object - 'null' description: Regra de repetição, ou `null`. properties: interval: type: integer frequency: type: string enum: - day - week - month - year remaining: type: - integer - 'null' description: Quantas repetições ainda faltam depois da ocorrência atual. origin: type: string enum: - trypost - network description: >- `trypost` para posts criados no PostClean. `network` para posts importados da rede (publicados fora do PostClean). platforms: type: array items: $ref: '#/components/schemas/PostPlatform' description: Destinos do post. Posts criados pela API têm exatamente um. labels: type: array items: $ref: '#/components/schemas/Label' created_at: type: string description: UTC, no formato `Y-m-d H:i:s`. updated_at: type: string description: UTC, no formato `Y-m-d H:i:s`. examples: - id: 9d3c1f2a-6b4e-4c8a-9f1e-2a7b5c8d0e41 post_group_id: 9d3c1f29-e0a1-4b7c-8d2e-5f6a7b8c9d03 author: id: 9b1e2d3c-4f5a-4b6c-8d7e-9f0a1b2c3d4e name: Ana Souza content: Agora dá para agendar fios no X. Veja como funciona. media: - id: 9d3c1f30-8a9b-4c0d-9e1f-2a3b4c5d6e7f path: medias/9d3c1f30-8a9b-4c0d-9e1f-2a3b4c5d6e7f.jpg url: >- https://post.chatclean.com.br/storage/medias/9d3c1f30-8a9b-4c0d-9e1f-2a3b4c5d6e7f.jpg type: image mime_type: image/jpeg original_filename: lancamento.jpg size: 482113 meta: width: 1080 height: 1350 alt_text: Banner do lançamento status: scheduled schedule_mode: custom scheduled_at: '2026-11-12 14:00:00' published_at: null approval_requested_by: null approval_requested_at: null approved_by: null approved_at: null recurrence: null origin: trypost platforms: - id: 9d3c1f2b-1a2b-4c3d-8e4f-5a6b7c8d9e0f platform: x content_type: x_post meta: thread_replies: - text: 2/ As respostas saem logo abaixo do primeiro post. media: [] status: pending enabled: true platform_url: null published_at: null error_message: null display_name: PostClean display_username: postclean display_avatar: >- https://pbs.twimg.com/profile_images/1790000000000000000/avatar_400x400.jpg social_account: id: 9c8b7a65-4d3e-4f2a-8b1c-0d9e8f7a6b54 platform: x display_name: PostClean username: postclean status: connected has_posting_schedule: true timezone: America/Sao_Paulo posting_goal: 5 max_content_length: 280 long_posts: false verified_badge: null labels: - id: 9c0d1e2f-3a4b-4c5d-8e6f-7a8b9c0d1e2f name: Lançamento color: '#2563EB' created_at: '2026-09-01 10:00:00' updated_at: '2026-09-01 10:00:00' created_at: '2026-11-06 13:20:11' updated_at: '2026-11-06 13:20:11' Person: type: object description: Um membro do workspace. Só o id e o nome são expostos. properties: id: type: string format: uuid name: type: string MediaItem: type: object description: Um item de mídia como fica salvo no post. properties: id: type: string format: uuid description: >- Id da mídia. Passe como `media[].id` para usar o arquivo em outro post. path: type: string description: Caminho no armazenamento, `medias/{uuid}.{ext}`. url: type: string format: uri description: URL pública do arquivo. type: type: - string - 'null' enum: - image - video - document - null description: '`null` em itens antigos, salvos sem tipo.' mime_type: type: - string - 'null' description: Tipo MIME do arquivo. original_filename: type: - string - 'null' description: Nome original do arquivo. size: type: - integer - 'null' description: Tamanho em bytes. meta: $ref: '#/components/schemas/MediaItemMeta' source: type: - string - 'null' enum: - ai - unsplash - google_drive - google_photos - canva - null description: >- De onde o arquivo veio no app. Só aparece em itens adicionados por uma dessas fontes. source_meta: type: - object - 'null' description: Detalhes dessa fonte. Só aparece quando a fonte informou algum. examples: - id: 9d3c1f30-8a9b-4c0d-9e1f-2a3b4c5d6e7f path: medias/9d3c1f30-8a9b-4c0d-9e1f-2a3b4c5d6e7f.jpg url: https://example.com/medias/9d3c1f30-8a9b-4c0d-9e1f-2a3b4c5d6e7f.jpg type: image mime_type: image/jpeg original_filename: lancamento.jpg size: 482113 meta: width: 1080 height: 1350 alt_text: Banner de lançamento do produto PostPlatform: type: object description: >- O destino de um post: o canal (conta social) onde ele é publicado, com o formato, as configurações da rede e o resultado da publicação. Posts criados pela API têm um único destino; posts antigos, criados antes de os posts ficarem independentes, podem ter vários. properties: id: type: string format: uuid description: Id do destino. É o `platforms[].id` aceito por `PUT /posts/{post}`. platform: oneOf: - $ref: '#/components/schemas/Platform' - type: 'null' description: Rede do canal. content_type: oneOf: - $ref: '#/components/schemas/ContentType' - type: 'null' meta: type: - object - array - 'null' description: >- Configurações da rede salvas para este destino (veja `PlatformMeta`). Sem configurações, pode vir como lista vazia (`[]`). status: type: - string - 'null' enum: - pending - publishing - retrying - pending_review - published - failed - rejected - null description: >- Estado da publicação na rede. `pending` até o post ser enviado; `retrying` aguarda nova tentativa depois de um limite ou de uma falha temporária da rede; `pending_review` e `rejected` vêm de redes que revisam os posts (Google Business). enabled: type: boolean description: Se o destino está ativo. Destinos desativados não são publicados. platform_url: type: - string - 'null' description: Link do post publicado na rede. published_at: type: - string - 'null' description: UTC, no formato `Y-m-d H:i:s`. error_message: type: - string - 'null' description: Motivo da falha na publicação, quando houve. display_name: type: - string - 'null' description: >- Nome da conta. Continua aqui mesmo depois que a conta é desconectada. display_username: type: - string - 'null' display_avatar: type: - string - 'null' social_account: oneOf: - $ref: '#/components/schemas/SocialAccount' - type: 'null' description: >- A conta social, ou `null` quando ela já foi removida (os campos `display_*` guardam o nome). Label: type: object properties: id: type: string format: uuid name: type: string color: type: string description: Cor em hexadecimal, `#RRGGBB`. examples: - '#2563EB' created_at: type: string description: Em UTC, no formato `Y-m-d H:i:s`. examples: - '2026-09-01 10:00:00' updated_at: type: string description: Em UTC, no formato `Y-m-d H:i:s`. examples: - '2026-09-01 10:00:00' ErrorBody: type: object properties: message: type: string description: Corpo de erro com uma mensagem. ValidationErrorBody: type: object properties: message: type: string errors: type: object additionalProperties: type: array items: type: string description: Corpo de erro de validação. `errors` traz as mensagens por campo. RateLimitErrorBody: type: object properties: name: type: string const: rate_limit_exceeded message: type: string examples: - Rate limit exceeded. Please retry after 30 seconds. description: Corpo devolvido quando o limite de requisições é excedido. MediaItemMeta: type: object description: >- Configurações editáveis de um item de mídia. As respostas também podem trazer chaves medidas pelo servidor (por exemplo `width`, `height` e `duration`). properties: alt_text: type: string maxLength: 2000 description: >- Descrição de acessibilidade. Vale para imagens; cada rede corta no próprio limite. user_tags: type: array maxItems: 20 description: Pessoas marcadas numa imagem do Instagram (só `instagram_feed`). items: type: object required: - username - x - 'y' properties: username: type: string pattern: ^@?[A-Za-z0-9._]{1,30}$ description: >- Nome de usuário público do Instagram. Um `@` no início é removido. x: type: number minimum: 0 maximum: 1 description: Distância da borda esquerda, de 0 a 1. 'y': type: number minimum: 0 maximum: 1 description: Distância da borda de cima, de 0 a 1. cover_offset_ms: type: integer minimum: 0 description: >- Quadro do vídeo usado como capa, em milissegundos a partir do início. Não pode passar do fim do vídeo. Platform: type: string enum: - linkedin - linkedin-page - x - tiktok - youtube - facebook - instagram - instagram-facebook - threads - pinterest - bluesky - mastodon - telegram - discord - google_business description: >- Rede de uma conta social. `linkedin-page` é uma página de empresa no LinkedIn, e `instagram-facebook` é uma conta do Instagram conectada por uma Página do Facebook. ContentType: type: string enum: - instagram_feed - instagram_reel - instagram_story - linkedin_post - linkedin_page_post - facebook_post - facebook_reel - facebook_story - tiktok_video - tiktok_photo - youtube_short - x_post - threads_post - threads_ghost_post - pinterest_pin - pinterest_video_pin - pinterest_carousel - bluesky_post - mastodon_post - telegram_post - discord_message - google_business_post description: >- Formato do post numa rede. Precisa pertencer à rede do destino. `GET /content-types` lista os formatos de cada rede com as regras de mídia. Stories do Instagram e do Facebook não publicam texto. SocialAccount: type: object properties: id: type: string format: uuid platform: $ref: '#/components/schemas/Platform' display_name: type: - string - 'null' description: Nome exibido da conta. username: type: - string - 'null' description: Nome de usuário na rede. status: type: string enum: - connected - disconnected - token_expired description: >- Status da conexão. `token_expired` e `disconnected` pedem reconexão no app. has_posting_schedule: type: boolean description: >- Se o canal tem horários de postagem. Colocar um post na fila (`queue`) exige horários. timezone: type: string description: >- Fuso horário IANA do canal. Os horários da fila e a recorrência seguem esse fuso. posting_goal: type: - integer - 'null' description: Meta de posts por semana do canal. max_content_length: type: integer description: >- Limite de texto desta conta, em caracteres. Uma conta do X com posts longos tem 25000. long_posts: type: boolean description: Se esta conta do X pode publicar posts longos. verified_badge: type: - string - 'null' enum: - blue - business - government - null description: >- Selo de verificação do X; `null` em outras redes ou em contas sem verificação. O selo sozinho não garante posts longos: veja `long_posts`. responses: Unauthorized: description: >- Chave de API ausente, inválida, revogada ou expirada. Corpos possíveis: `Unauthenticated.` (sem chave, ou chave inválida ou revogada), `Token expired.` (passou do `expires_at`), `Token not found.` e `No workspace selected.` (a chave não está mais ligada a um workspace). content: application/json: schema: $ref: '#/components/schemas/ErrorBody' example: message: Unauthenticated. PaymentRequired: description: >- A conta do workspace não tem assinatura ativa nem período de teste. Corpo: `{"message": "Active subscription required."}`. content: application/json: schema: $ref: '#/components/schemas/ErrorBody' example: message: Active subscription required. Forbidden: description: >- A requisição não é permitida. Chaves de API só funcionam para administradores do workspace (o dono da conta ou um membro marcado como administrador); fora isso, toda requisição devolve `Insufficient workspace permissions.`. Outros corpos: `Workspace access denied.` (o usuário da chave saiu do workspace), `Personal access token required.` (foi enviado um token OAuth do MCP) e `This action is unauthorized.` (por exemplo, a nota pertence a outro membro). content: application/json: schema: $ref: '#/components/schemas/ErrorBody' NotFound: description: O recurso não existe neste workspace. content: application/json: schema: $ref: '#/components/schemas/ErrorBody' Conflict: description: >- Outra alteração neste post ou na fila do canal está em andamento. Tente de novo. content: application/json: schema: $ref: '#/components/schemas/ErrorBody' ValidationError: description: A validação falhou. Cada campo com erro aparece em `errors`. content: application/json: schema: $ref: '#/components/schemas/ValidationErrorBody' TooManyRequests: description: 'Limite de requisições excedido: 60 por minuto por workspace.' headers: Retry-After: description: Segundos de espera antes de tentar de novo. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/RateLimitErrorBody' example: name: rate_limit_exceeded message: Rate limit exceeded. Please retry after 30 seconds. securitySchemes: bearerAuth: type: http scheme: bearer description: Chave de API do workspace, criada em Configurações > Chaves de API. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.