# Media

Fonte: https://lunahia.com.br/en/docs/reference/media

Upload a file to Meta and download the media that arrived in a message.

### Get a message's media

`GET /v1/messages/{id}/media`

Returns a signed URL, issued by Luna, to download media that has already been persisted.

Authentication: API key. Required scope: `messages:read`

Topic guide: https://lunahia.com.br/en/docs/send-messages#rota-get-v1-messages-id-media

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | O identificador da mensagem na Luna, como GET /v1/messages o devolve. |

#### Code examples

```bash
curl -X GET "https://api.lunahia.com.br/v1/messages/YOUR_ID/media" \
  -H "Authorization: Bearer $LUNA_API_KEY"
```

#### Responses

**200**: Success.

```json
{
  "url": "https://c1b129d42065073c6f8b203801c44b2d.r2.cloudflarestorage.com/lunabucket/midia/ae60f288-7565-4315-a440-3663e9c231e1?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=300&X-Amz-Signature=EXEMPLO",
  "expiraEm": "2026-08-24T12:29:02.085Z"
}
```

**400**: The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.

```json
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
```

**401**: The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.

```json
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
```

**403**: The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.

```json
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
```

**404**: The resource does not exist, or is not yours. The two answers are identical, byte for byte.

```json
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
```

**409**: The request is well formed, but the resource state does not allow it. The error field says which case it is.

```json
{
  "error": "media_not_ready",
  "docsUrl": "https://lunahia.com.br/docs/enviar-mensagens",
  "message": "A mídia desta mensagem ainda não está disponível.",
  "estado": "pendente"
}
```

**429**: Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.

```json
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}
```

### Download media through the notice link

`GET /v1/media/{token}`

The link that comes in media.url on the message.received and message.echo notices. It asks for no API key: the token in the address is the credential. Ready media answers 302 to a short-lived signed URL; media still being downloaded from Meta, 409 with Retry-After; a token that does not exist or has expired, 404.

Authentication: Public, no key

Topic guide: https://lunahia.com.br/en/docs/send-messages#rota-get-v1-media-token

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | `string` | yes | O token do link, como veio em media.url. |

#### Code examples

```bash
curl -X GET "https://api.lunahia.com.br/v1/media/YOUR_TOKEN"
```

#### Responses

**302**: Redirect: follow the Location header, which leads to the signed URL of the file.

**400**: The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.

```json
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
```

**404**: The resource does not exist, or is not yours. The two answers are identical, byte for byte.

```json
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
```

**409**: The request is well formed, but the resource state does not allow it. The error field says which case it is.

```json
{
  "error": "media_not_ready",
  "docsUrl": "https://lunahia.com.br/docs/enviar-mensagens",
  "message": "A mídia desta mensagem ainda não está disponível.",
  "estado": "pendente"
}
```

**429**: Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.

```json
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}
```

### Upload a file and get its media identifier

`POST /v1/numbers/{id}/media`

Takes a file in multipart/form-data under the field file, uploads it to Meta and returns its identifier.

Authentication: API key. Required scope: `messages:write`

Topic guide: https://lunahia.com.br/en/docs/send-messages#rota-post-v1-numbers-id-media

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | O identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. |

#### Request body

`multipart/form-data`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `file` | `string (binary)` | yes | The file to upload, in the file field. |

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/numbers/YOUR_ID/media" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -F "file=@./pedido.jpg;type=image/jpeg"
```

#### Responses

**200**: Success.

```json
{
  "mediaId": "1425835918205946"
}
```

**400**: The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.

```json
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
```

**401**: The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.

```json
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
```

**403**: The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.

```json
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
```

**404**: The resource does not exist, or is not yours. The two answers are identical, byte for byte.

```json
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
```

**413**: The file is over the size ceiling, which is the same for every customer.

```json
{
  "error": "file_too_large",
  "docsUrl": "https://lunahia.com.br/docs/enviar-mensagens",
  "message": "O arquivo passa do tamanho que a plataforma aceita. O limite é o mesmo para todos os clientes: ele existe por capacidade de infraestrutura."
}
```

**415**: The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.

```json
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
```

**429**: Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.

```json
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}
```
