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

# Upload asset

> Nahrání souboru do chatu a získání trvalé CDN URL

Nahraje soubor do assetů daného chatu a vrátí trvalou CDN URL. Použijte tento endpoint pro obrázky, dokumenty, zvuk, video nebo jakýkoli jiný soubor, na který chcete odkazovat pomocí URL ve své aplikaci nebo workflow.

## Požadavek

```
POST /api/client-app/assets/upload
```

### Hlavičky

| Hlavička        | Povinná | Popis                 |
| --------------- | ------- | --------------------- |
| `Authorization` | Ano     | `Bearer macaly_...`   |
| `Content-Type`  | Ano     | `multipart/form-data` |

### Parametry formuláře

| Pole            | Typ           | Povinné | Výchozí hodnota       | Popis                                                                |
| --------------- | ------------- | ------- | --------------------- | -------------------------------------------------------------------- |
| `chatId`        | string        | Ano     | -                     | Chat, do kterého se má asset nahrát                                  |
| `file`          | file          | Ano     | -                     | Soubor k nahrání. Maximální velikost 20 MB                           |
| `folderPath`    | string        | Ne      | -                     | Cesta ke složce oddělená lomítky, např. `images/products`            |
| `createFolders` | string        | Ne      | `false`               | `"true"`, `"1"` nebo `"yes"` vytvoří chybějící složky v `folderPath` |
| `folderId`      | string        | Ne      | -                     | ID existující složky. Neposílejte současně `folderId` a `folderPath` |
| `title`         | string        | Ne      | Původní název souboru | Zobrazovaný název assetu                                             |
| `metadata`      | string (JSON) | Ne      | -                     | JSON objekt uložený spolu s assetem                                  |

<Note>
  Uveďte buď `folderId`, nebo `folderPath`, nikdy obojí. Odeslání obou vrátí chybu 400.
</Note>

### Příklad požadavku

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://www.macaly.com/api/client-app/assets/upload \
    -H "Authorization: Bearer macaly_abc123..." \
    -F "chatId=abc123def456" \
    -F "file=@./logo.png;type=image/png"
  ```

  ```javascript JavaScript theme={null}
  const form = new FormData();
  form.append('chatId', 'abc123def456');
  form.append('file', fileBlob, 'logo.png');

  const response = await fetch('https://www.macaly.com/api/client-app/assets/upload', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer macaly_abc123...',
    },
    body: form,
  });

  const data = await response.json();
  console.log(data.asset.url);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://www.macaly.com/api/client-app/assets/upload',
      headers={'Authorization': 'Bearer macaly_abc123...'},
      data={'chatId': 'abc123def456'},
      files={'file': ('logo.png', open('logo.png', 'rb'), 'image/png')},
  )

  data = response.json()
  print(data['asset']['url'])
  ```
</CodeGroup>

### Nahrání do složky

Použijte `folderPath` pro čitelnou strukturu složek a `createFolders=true` pro vytvoření chybějících složek na dané cestě:

```bash cURL theme={null}
curl -X POST https://www.macaly.com/api/client-app/assets/upload \
  -H "Authorization: Bearer macaly_abc123..." \
  -F "chatId=abc123def456" \
  -F "folderPath=images/products" \
  -F "createFolders=true" \
  -F "title=Product hero image" \
  -F "file=@./hero.png;type=image/png"
```

## Odpověď

```json theme={null}
{
  "success": true,
  "asset": {
    "assetId": "asset_123",
    "url": "https://cdn.macaly.app/user/chat/key/logo.png",
    "storageKey": "user/chat/key/logo.png",
    "contentType": "image/png",
    "fileSize": 12345,
    "type": "image",
    "folderId": "folder_123"
  }
}
```

| Pole                | Typ            | Popis                                            |
| ------------------- | -------------- | ------------------------------------------------ |
| `asset.assetId`     | string         | Unikátní identifikátor assetu                    |
| `asset.url`         | string         | Trvalá CDN URL nahraného souboru                 |
| `asset.storageKey`  | string         | Interní cesta k úložišti                         |
| `asset.contentType` | string         | MIME typ nahraného souboru                       |
| `asset.fileSize`    | number         | Velikost souboru v bajtech                       |
| `asset.type`        | string         | Odvozený typ assetu, např. `image`, `document`   |
| `asset.folderId`    | string \| null | Složka, do které byl asset umístěn, pokud nějaká |

## Stavové kódy

| Kód | Popis                                                                                                       |
| --- | ----------------------------------------------------------------------------------------------------------- |
| 200 | Úspěch – asset nahrán                                                                                       |
| 400 | Chybí `chatId` nebo `file`, neplatný JSON v `metadata`, nebo odeslány obě hodnoty `folderId` i `folderPath` |
| 401 | Neplatný nebo chybějící API klíč                                                                            |
| 403 | API klíč nemá přístup k tomuto chatu                                                                        |
| 404 | Složka nenalezena                                                                                           |
| 413 | Soubor přesahuje limit 20 MB                                                                                |
| 500 | Chyba serveru                                                                                               |

## Pravidla pro složky

* Cesty ke složkám se dělí podle `/`, ořezávají se mezery a prázdné segmenty se ignorují.
* Maximální hloubka je 8 složek.
* Název každé složky může mít až 255 znaků.
* Shoda názvů složek nerozlišuje velikost písmen v rámci stejné nadřazené složky.
* Pokud `folderPath` neexistuje a `createFolders` není `true`, nahrání selže s chybou 404.

## Dobré vědět

* Tento endpoint používá stejný API klíč `macaly_...` jako zbytek API, i když URL začíná na `/api/client-app/`. Žádný samostatný token není potřeba.
* Chat uvedený v `chatId` musí patřit stejnému týmu jako váš API klíč.
* Nahrané assety získají trvalou CDN URL, na kterou můžete odkázat jako přílohu v [Create chat](/docs/cs/api/create-chat) nebo [Publish message](/docs/cs/api/publish-message), případně ji použít kdekoli mimo Macaly.