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

# Enviar mídia de cabeçalho

> Envia uma imagem, um vídeo ou um documento para usar como cabeçalho de um template. Envie os bytes do arquivo **diretamente no corpo**, com o `Content-Type` do arquivo. O formato é deduzido do tipo.

| Formato | Tipos aceitos | Tamanho máximo |
| --- | --- | --- |
| `image` | `image/jpeg`, `image/png` | 5 MB |
| `video` | `video/mp4` | 16 MB |
| `document` | `application/pdf` | 100 MB |

Use o `id` retornado em `components.header.media_id` ao submeter o template.



## OpenAPI

````yaml openapi.json POST /v1/templates/media
openapi: 3.0.3
info:
  title: API da Routa
  description: >-
    API REST para enviar e receber mensagens de WhatsApp, acompanhar a entrega e
    receber eventos normalizados por webhook.
  version: '1'
servers:
  - url: https://api.routa.chat
    description: Produção
security:
  - bearerAuth: []
tags:
  - name: Mensagens
    description: Envie, consulte e liste mensagens.
  - name: Eventos
    description: Consulte o log de eventos normalizados.
  - name: Webhooks
    description: Gerencie endpoints de webhook, segredos e entregas.
  - name: Templates
    description: Submeta e consulte templates de WhatsApp.
  - name: Mídia
    description: Envie e obtenha arquivos de mídia.
  - name: Uso
    description: Consulte o uso medido do projeto.
  - name: Identidade
    description: Identifique a chave de API em uso.
paths:
  /v1/templates/media:
    post:
      tags:
        - Templates
      summary: Enviar mídia de cabeçalho
      description: >-
        Envia uma imagem, um vídeo ou um documento para usar como cabeçalho de
        um template. Envie os bytes do arquivo **diretamente no corpo**, com o
        `Content-Type` do arquivo. O formato é deduzido do tipo.


        | Formato | Tipos aceitos | Tamanho máximo |

        | --- | --- | --- |

        | `image` | `image/jpeg`, `image/png` | 5 MB |

        | `video` | `video/mp4` | 16 MB |

        | `document` | `application/pdf` | 100 MB |


        Use o `id` retornado em `components.header.media_id` ao submeter o
        template.
      operationId: uploadTemplateMedia
      requestBody:
        required: true
        description: >-
          Os bytes do arquivo, com o `Content-Type` do arquivo (por exemplo
          `image/png`).
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '201':
          description: Recurso criado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateMedia'
        '401':
          description: >-
            Chave de API ausente, inválida, revogada ou expirada
            (`api_key_invalid`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: A chave não tem o escopo necessário (`insufficient_scope`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Requisição inválida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Limite de taxa excedido. Veja o header `Retry-After`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth:
            - templates:write
components:
  schemas:
    TemplateMedia:
      type: object
      properties:
        id:
          type: string
          description: >-
            Identificador da mídia de cabeçalho. Use-o em
            `components.header.media_id`.
          example: tmedia_01J8ZK9M3Q7XABCDEFGHJKMNPQ
        format:
          type: string
          enum:
            - image
            - video
            - document
          description: 'Formato: `image`, `video` ou `document`.'
        size_bytes:
          type: number
          description: Tamanho do arquivo, em bytes.
        content_type:
          type: string
          description: Tipo MIME do arquivo.
          example: image/png
        created_at:
          format: date-time
          type: string
          description: Quando o arquivo foi enviado.
          example: '2026-09-04T13:22:41.031Z'
      required:
        - id
        - format
        - size_bytes
        - content_type
        - created_at
    Error:
      type: object
      properties:
        error:
          type: object
          required:
            - type
            - code
            - message
            - request_id
          properties:
            type:
              type: string
              description: >-
                Categoria do erro: `invalid_request_error`,
                `authentication_error`, `permission_error`, `not_found_error`,
                `conflict_error`, `rate_limit_error`, `billing_error` ou
                `api_error`.
              example: invalid_request_error
            code:
              type: string
              description: >-
                Código estável e legível por máquina. Veja [Códigos de
                erro](/errors/error-codes).
              example: channel_inactive
            message:
              type: string
              description: >-
                Texto para humanos, em inglês. Pode mudar, então não faça parse
                dele.
              example: Channel chan_01J8... is not active and cannot send messages.
            param:
              type: string
              description: O campo da requisição com problema, quando se aplica.
            doc_url:
              type: string
              description: Link para a documentação do código, quando disponível.
            details:
              type: object
              additionalProperties:
                oneOf:
                  - type: string
                  - type: number
              description: >-
                Valores acionáveis, como `limit`, `used` e `resets_at` em
                `message_quota_exceeded`.
            request_id:
              type: string
              description: Identificador da requisição. Informe-o ao falar com o suporte.
              example: req_01J8ZK9M3Q7XABCDEFGHJKMNPQ
          description: Detalhes do erro.
      required:
        - error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Chave de API do projeto, no formato `rt_live_...` ou `rt_test_...`,
        enviada como `Authorization: Bearer <chave>`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.