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

> Lataa tiedosto keskusteluun ja saa pysyvä CDN-osoite

Lataa tiedoston keskustelun aineistoihin ja palauttaa pysyvän CDN-osoitteen. Voit käyttää tätä kuville, asiakirjoille, äänelle, videoille ja muille tiedostoille, joihin haluat sovelluksesi tai työnkulkusi viittaavan URL-osoitteella.

## Pyyntö

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

### Otsakkeet

| Otsake | Pakollinen | Kuvaus |
| - | - | - |
| `Authorization` | Kyllä | `Bearer macaly_...` |
| `Content-Type` | Kyllä | `multipart/form-data` |

### Lomakedatan parametrit

| Kenttä | Tyyppi | Pakollinen | Oletus | Kuvaus |
| - | - | - | - | - |
| `chatId` | string | Kyllä | - | Keskustelu, johon tiedosto ladataan |
| `file` | file | Kyllä | - | Ladattava tiedosto. Enimmäiskoko 20 Mt |
| `folderPath` | string | Ei | - | Vinoviivoilla eroteltu kansiopolku, esim. `images/products` |
| `createFolders` | string | Ei | `false` | Arvot `"true"`, `"1"` ja `"yes"` luovat `folderPath`-polusta puuttuvat kansiot |
| `folderId` | string | Ei | - | Olemassa olevan kansion tunniste. Älä lähetä sekä `folderId`- että `folderPath`-kenttää |
| `title` | string | Ei | Alkuperäinen tiedostonimi | Aineiston näyttönimi |
| `metadata` | string (JSON) | Ei | - | Aineiston mukana tallennettava JSON-objekti |

<Note>
  Anna joko `folderId` tai `folderPath`, älä molempia. Jos lähetät molemmat, vastauksena on 400-virhe.
</Note>

### Esimerkkipyyntö

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

### Lataaminen kansioon

Käytä `folderPath`-kenttää luettavan kansiorakenteen määrittämiseen ja aseta `createFolders=true`, jos haluat luoda polun puuttuvat kansiot:

```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=Tuotteen pääkuva" \
  -F "file=@./hero.png;type=image/png"
```

## Vastaus

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

| Kenttä | Tyyppi | Kuvaus |
| - | - | - |
| `asset.assetId` | string | Aineiston yksilöllinen tunniste |
| `asset.url` | string | Ladatun tiedoston pysyvä CDN-osoite |
| `asset.storageKey` | string | Sisäinen tallennuspolku |
| `asset.contentType` | string | Ladatun tiedoston MIME-tyyppi |
| `asset.fileSize` | number | Tiedoston koko tavuina |
| `asset.type` | string | Päätelty aineistotyyppi, esim. `image`, `document` |
| `asset.folderId` | string \| null | Kansio, johon aineisto sijoitettiin, jos mikään |

## Tilakoodit

| Tila | Kuvaus |
| - | - |
| 200 | Onnistui: aineisto ladattiin |
| 400 | `chatId` tai `file` puuttuu, `metadata`-JSON on virheellinen tai sekä `folderId` että `folderPath` on annettu |
| 401 | Virheellinen tai puuttuva API-avain |
| 403 | API-avaimella ei ole pääsyä tähän keskusteluun |
| 404 | Kansiota ei löytynyt |
| 413 | Tiedosto ylittää 20 Mt:n latausrajan |
| 500 | Palvelinvirhe |

## Kansioiden säännöt

* Kansiopolut jaetaan `/`-merkin kohdalta, välilyönnit poistetaan reunoilta ja tyhjät osat ohitetaan.
* Enimmäissyvyys on 8 kansiota.
* Kansion nimi voi olla enintään 255 merkkiä pitkä.
* Kansioiden vertailussa isot ja pienet kirjaimet katsotaan samoiksi saman yläkansion sisällä.
* Jos `folderPath` ei ole olemassa eikä `createFolders` ole `true`, lataus epäonnistuu 404-virheeseen.

## Hyvä tietää

* Tämä päätepiste käyttää samaa `macaly_...`-API-avainta kuin muu API, vaikka URL-osoite alkaa polulla `/api/client-app/`. Erillistä tunnistetta ei tarvita.
* `chatId`-kentässä viitatun keskustelun on kuuluttava samalle workspacelle kuin API-avaimesi.
* Ladatut aineistot saavat pysyvän CDN-osoitteen, jonka voit liittää liitteenä päätepisteisiin [Create chat](/docs/fi/api/create-chat) tai [Publish message](/docs/fi/api/publish-message) tai käyttää missä tahansa Macalyn ulkopuolella.


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