> ## 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

> Fájl feltöltése egy beszélgetésbe és állandó CDN URL lekérése

Feltölt egy fájlt egy beszélgetés erőforrásai (Assets) közé, és állandó CDN URL-t ad vissza. Használd képekhez, dokumentumokhoz, hanghoz, videóhoz vagy bármilyen más fájlhoz, amelyre az alkalmazásod vagy a munkafolyamatod URL-lel hivatkozna.

## Kérés

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

### Fejlécek

| Fejléc | Kötelező | Leírás |
| - | - | - |
| `Authorization` | Igen | `Bearer macaly_...` |
| `Content-Type` | Igen | `multipart/form-data` |

### Űrlapadat-paraméterek

| Mező | Típus | Kötelező | Alapérték | Leírás |
| - | - | - | - | - |
| `chatId` | string | Igen | - | A beszélgetés, amelybe a fájl feltöltődik |
| `file` | file | Igen | - | A feltöltendő fájl. Legfeljebb 20 MB |
| `folderPath` | string | Nem | - | Perjellel tagolt mappaútvonal, pl. `images/products` |
| `createFolders` | string | Nem | `false` | A `"true"`, `"1"` vagy `"yes"` érték létrehozza a `folderPath` hiányzó mappáit |
| `folderId` | string | Nem | - | Meglévő mappa azonosítója. Ne küldd el egyszerre a `folderId` és a `folderPath` mezőt |
| `title` | string | Nem | Az eredeti fájlnév | Az asset megjelenített címe |
| `metadata` | string (JSON) | Nem | - | Az assethez mentett JSON-objektum |

<Note>
  A `folderId` és a `folderPath` közül csak az egyiket add meg. Ha mindkettőt elküldöd, 400-as hibát kapsz.
</Note>

### Példa kérés

<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>

### Feltöltés mappába

Az olvasható mappaszerkezethez használd a `folderPath` mezőt, és állítsd a `createFolders=true` értéket, hogy az útvonal hiányzó mappái létrejöjjenek:

```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"
```

## Válasz

```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"
  }
}
```

| Mező | Típus | Leírás |
| - | - | - |
| `asset.assetId` | string | Az asset egyedi azonosítója |
| `asset.url` | string | A feltöltött fájl állandó CDN URL-je |
| `asset.storageKey` | string | Belső tárolási útvonal |
| `asset.contentType` | string | A feltöltött fájl MIME-típusa |
| `asset.fileSize` | number | A fájl mérete bájtban |
| `asset.type` | string | A kikövetkeztetett asset-típus, pl. `image`, `document` |
| `asset.folderId` | string \| null | A mappa, amelybe az asset került, ha van ilyen |

## Állapotkódok

| Állapot | Leírás |
| - | - |
| 200 | Sikeres - az asset feltöltve |
| 400 | Hiányzik a `chatId` vagy a `file`, érvénytelen a `metadata` JSON, vagy a `folderId` és a `folderPath` is meg van adva |
| 401 | Érvénytelen vagy hiányzó API-kulcs |
| 403 | Az API-kulcsnak nincs hozzáférése ehhez a beszélgetéshez |
| 404 | A mappa nem található |
| 413 | A fájl meghaladja a 20 MB-os feltöltési korlátot |
| 500 | Szerverhiba |

## Mappaszabályok

* A mappaútvonalat a rendszer `/` mentén bontja, a szóközöket levágja, az üres szakaszokat pedig figyelmen kívül hagyja.
* A legnagyobb mélység 8 mappa.
* Minden mappanév legfeljebb 255 karakter lehet.
* A mappák egyeztetése ugyanazon a szülőmappán belül nem különbözteti meg a kis- és nagybetűt.
* Ha a `folderPath` nem létezik, és a `createFolders` értéke nem `true`, a feltöltés 404-es hibával meghiúsul.

## Jó tudni

* Ez a végpont ugyanazt a `macaly_...` API-kulcsot használja, mint az API többi része, annak ellenére, hogy az URL `/api/client-app/` résszel kezdődik. Külön tokenre nincs szükség.
* A `chatId` által megadott beszélgetésnek ugyanahhoz a munkaterülethez kell tartoznia, mint az API-kulcsnak.
* A feltöltött assetek állandó CDN URL-t kapnak, amelyet mellékletként megadhatsz a [Create chat](/docs/hu/api/create-chat) vagy a [Publish message](/docs/hu/api/publish-message) hívásban, vagy a Macalyn kívül bárhol felhasználhatsz.


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