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

# Download media

> Download received media in a unified way.

Downloads the media of a received message. WhatsApp delivers encrypted media;
this endpoint decrypts it using the metadata that arrives in the webhook
(`media_key`, `mimetype`, `direct_path` or `url`, and the hashes).

Set `base64: true` to receive the content embedded in the response, or use
`async` for large downloads in the background.

> [!TIP]
>
> The required fields (`media_key`, `mimetype`, `file_sha256` etc.) come in the
> received message webhook payload — pass them straight through to this endpoint.

## Official API (Cloud API)

On Official API connections, media is stored at Meta and identified by the
`media_id`, which arrives in the webhook in `media_data.media_id`. Send `media_id` and
`mimetype` instead of `media_key`, `direct_path` and hashes. The response is
always synchronous — `async` is not accepted on these connections.

```json theme={null}
{
  "sessionId": "cloud-...",
  "media_id": "1234567890",
  "mimetype": "image/jpeg",
  "base64": true
}
```

## Accounts with "Do not store media"

With the **Do not store media** option enabled under **My Account → Privacy**, D-API
does not keep any of the account's media: nothing goes to storage, Redis, queues or
the database. Received message webhooks carry only the metadata
(`media_key`, `direct_path`, hashes or `media_id`), with no `media_url` and no
base64, and the file is retrieved through this endpoint. On these accounts:

* the response is always base64, even without `base64: true`;
* `async` is rejected — download is synchronous only;
* base64 media sends with `async` are also rejected; use synchronous
  sending or a URL.

> [!WARNING]
>
> Enabling or disabling the option restarts the account's unofficial connections,
> which go offline for a few seconds.


## OpenAPI

````yaml api-reference/openapi.en.json POST /api/v1/media/download
openapi: 3.1.0
info:
  title: D-API - Complete WhatsApp Infrastructure
  description: >-
    A scalable, robust solution for automation managers, SaaS products and end
    users who need a reliable WhatsApp integration. It offers multiple
    simultaneous instances, real-time webhooks, an intuitive dashboard and a
    documented REST API with 99.9% uptime and latency under 30ms.
  version: 1.2.1
  contact:
    name: Suporte D-API
    email: suporte@d-api.cloud
    url: https://d-api.cloud
servers:
  - url: https://api.d-api.cloud
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Home
    description: Base endpoints
  - name: Sessions
    description: Endpoints for managing sessions
  - name: Messages
    description: Endpoints for sending messages
  - name: Cloud API
    description: >-
      WhatsApp Official API (Meta Cloud API): manual connection, template
      management (list/create/delete) and template sending.
  - name: IVR Calls
    description: 'Voice call dispatch (IVR): single or bulk, with audio or an IVR flow.'
  - name: SMS
    description: 'SMS sending: single or bulk.'
  - name: Commands
    description: >-
      Look up asynchronous commands (async: true) by the commandId returned when
      enqueued.
paths:
  /api/v1/media/download:
    post:
      tags:
        - Media
      summary: Download media (unified)
      description: >-
        Downloads any type of media (image, video, audio, document) using the
        media information from the webhook. Unofficial connection: requires
        media_key and url or direct_path. Official connection (Cloud API):
        requires media_id. If 'base64: true', returns base64 data. Otherwise,
        uploads to S3 and returns 'media_url'. Accounts with media storage
        disabled always receive base64, in synchronous mode only.
      operationId: postApiV1MediaDownload
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                sessionId:
                  minLength: 1
                  type: string
                url:
                  type: string
                direct_path:
                  type: string
                media_key:
                  minLength: 1
                  type: string
                media_id:
                  minLength: 1
                  type: string
                media_type:
                  description: >-
                    Media type. Optional: when omitted, it is inferred from the
                    mimetype.
                  anyOf:
                    - const: image
                      type: string
                    - const: video
                      type: string
                    - const: audio
                      type: string
                    - const: document
                      type: string
                    - const: sticker
                      type: string
                mimetype:
                  minLength: 1
                  type: string
                file_enc_sha256:
                  type: string
                file_sha256:
                  type: string
                file_length:
                  type: number
                async:
                  anyOf:
                    - type: boolean
                    - type: string
                base64:
                  type: boolean
              required:
                - sessionId
                - mimetype
              additionalProperties: false
          multipart/form-data:
            schema:
              type: object
              properties:
                sessionId:
                  minLength: 1
                  type: string
                url:
                  type: string
                direct_path:
                  type: string
                media_key:
                  minLength: 1
                  type: string
                media_id:
                  minLength: 1
                  type: string
                media_type:
                  description: >-
                    Media type. Optional: when omitted, it is inferred from the
                    mimetype.
                  anyOf:
                    - const: image
                      type: string
                    - const: video
                      type: string
                    - const: audio
                      type: string
                    - const: document
                      type: string
                    - const: sticker
                      type: string
                mimetype:
                  minLength: 1
                  type: string
                file_enc_sha256:
                  type: string
                file_sha256:
                  type: string
                file_length:
                  type: number
                async:
                  anyOf:
                    - type: boolean
                    - type: string
                base64:
                  type: boolean
              required:
                - sessionId
                - mimetype
              additionalProperties: false
          text/plain:
            schema:
              type: object
              properties:
                sessionId:
                  minLength: 1
                  type: string
                url:
                  type: string
                direct_path:
                  type: string
                media_key:
                  minLength: 1
                  type: string
                media_id:
                  minLength: 1
                  type: string
                media_type:
                  description: >-
                    Media type. Optional: when omitted, it is inferred from the
                    mimetype.
                  anyOf:
                    - const: image
                      type: string
                    - const: video
                      type: string
                    - const: audio
                      type: string
                    - const: document
                      type: string
                    - const: sticker
                      type: string
                mimetype:
                  minLength: 1
                  type: string
                file_enc_sha256:
                  type: string
                file_sha256:
                  type: string
                file_length:
                  type: number
                async:
                  anyOf:
                    - type: boolean
                    - type: string
                base64:
                  type: boolean
              required:
                - sessionId
                - mimetype
              additionalProperties: false
      responses:
        '200':
          description: Successful response
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'API Key for authentication. Format: <API_KEY>'

````

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