> ## Documentation Index
> Fetch the complete documentation index at: https://developer.omni.z-api.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Subir multimedia

> Obtén el header_handle para plantillas con HEADER de imagen, vídeo o documento

## Conceptos

Meta **no acepta el archivo directamente** al crear la plantilla. Exige un `header_handle` producido por la Resumable Upload API, que depende del token de la aplicación; por eso la subida pasa por aquí y no por tu frontend.

Este endpoint recibe el archivo y devuelve el handle listo para usar.

## Cuándo lo necesitas

Solo cuando la plantilla tiene un componente `HEADER` de tipo `IMAGE`, `VIDEO` o `DOCUMENT`. Las plantillas con header de texto, o sin header, no necesitan subida.

## Flujo

<Steps>
  <Step title="Sube el archivo">
    `POST /whatsapp/businesses/{wabaId}/templates/media` con `multipart/form-data`, campos `file` y `type`.
  </Step>

  <Step title="Guarda el handle">
    La respuesta trae el handle en el campo `h`.
  </Step>

  <Step title="Úsalo en el componente HEADER">
    Pasa el handle como `example` del HEADER en [Crear plantilla](/es/templates/create-template):

    ```json theme={null}
    {
      "type": "HEADER",
      "format": "IMAGE",
      "example": { "header_handle": ["4::aW1hZ2UvanBlZw==:ARZ..."] }
    }
    ```
  </Step>
</Steps>

<Warning>
  El handle caduca. Sube el archivo y crea la plantilla en la misma sesión: no guardes el handle para usarlo días después.
</Warning>

<Note>
  Además de `h`, la API acepta el handle en las claves `handle`, `header_handle`, `headerHandle` y `mediaHandle`. Usa `h`, que es la forma canónica.
</Note>

## Requisito de configuración

La subida depende del **App ID** y el **App Secret** de Meta registrados en la cuenta. Sin ellos, la llamada devuelve `422` con `MISSING_APP_CREDENTIALS`.

Esto se configura en el panel, en **Seguridad**: no hay endpoint público para registrar las credenciales del app. Consulta también [Orígenes del SDK](/es/channels/sdk-info), que cubre el otro requisito del flujo con SDK.

## Límites

| Elemento            | Valor          |
| ------------------- | -------------- |
| Tamaño máximo       | 100 MB         |
| Campos obligatorios | `file`, `type` |


## OpenAPI

````yaml es/templates/openapi.json POST /whatsapp/businesses/{wabaId}/templates/media
openapi: 3.1.0
info:
  title: Omni Z-API - API de plantillas
  description: API para gestionar las plantillas de mensaje de WhatsApp Business
  version: 1.0.0
servers:
  - url: https://api.omni.z-api.io
security:
  - bearerAuth: []
paths:
  /whatsapp/businesses/{wabaId}/templates/media:
    post:
      tags:
        - Plantillas
      summary: Subir multimedia para plantilla
      description: >-
        Sube el archivo del HEADER multimedia y devuelve el `header_handle` que
        exige Meta.


        Meta no acepta el archivo directamente al crear la plantilla: exige el
        handle de la Resumable Upload API, que depende del token de la
        aplicación. Este endpoint hace ese puente.
      operationId: uploadTemplateMedia
      parameters:
        - name: wabaId
          in: path
          required: true
          description: ID de la WABA (obtenido con Listar WABAs)
          schema:
            type: string
            example: '428083093730937'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
                - type
              properties:
                file:
                  type: string
                  format: binary
                  description: >-
                    Archivo del header (imagen, vídeo o documento). Límite de
                    100 MB
                type:
                  type: string
                  description: >-
                    MIME type del archivo (p. ej.: `image/jpeg`, `video/mp4`,
                    `application/pdf`)
                  example: image/jpeg
      responses:
        '200':
          description: Subida completada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateMediaResponse'
              example:
                h: 4::aW1hZ2UvanBlZw==:ARZ...:e:1770000000:...
        '400':
          description: 'Petición no válida: archivo vacío o falta `type`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Token no válido o ausente.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: Archivo de más de 100 MB
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: >-
            La cuenta no tiene App ID ni App Secret de Meta configurados
            (`MISSING_APP_CREDENTIALS`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: >-
            Meta rechazó la subida (`META_REFUSED`) o no se pudo leer la
            configuración del app (`CONFIG_UNREACHABLE`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    TemplateMediaResponse:
      type: object
      properties:
        h:
          type: string
          description: >-
            Handle que se usa como `example` del componente HEADER al crear la
            plantilla
    Error:
      type: object
      properties:
        error:
          type: integer
          description: Código del error
        message:
          type: string
          description: Descripción del error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Secret Key generada en el panel de Seguridad de Omni Z-API

````