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

# Téléverser un asset

> Téléversez un fichier dans un chat et obtenez une URL CDN permanente

Téléverse un fichier dans les assets d'un chat et renvoie une URL CDN permanente. Utilisez cet endpoint pour des images, documents, fichiers audio, vidéo ou tout autre fichier que vous voulez référencer par URL dans votre application ou votre workflow.

## Requête

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

### En-têtes

| En-tête | Requis | Description |
| - | - | - |
| `Authorization` | Oui | `Bearer macaly_...` |
| `Content-Type` | Oui | `multipart/form-data` |

### Paramètres du formulaire

| Champ | Type | Requis | Défaut | Description |
| - | - | - | - | - |
| `chatId` | string | Oui | - | Le chat dans lequel téléverser l'asset |
| `file` | file | Oui | - | Le fichier à téléverser. Taille maximale 20 Mo |
| `folderPath` | string | Non | - | Chemin de dossier séparé par des barres obliques, ex. `images/products` |
| `createFolders` | string | Non | `false` | `"true"`, `"1"` ou `"yes"` crée les dossiers manquants dans `folderPath` |
| `folderId` | string | Non | - | ID d'un dossier existant. N'envoyez pas `folderId` et `folderPath` en même temps |
| `title` | string | Non | Nom du fichier d'origine | Titre affiché pour l'asset |
| `metadata` | string (JSON) | Non | - | Objet JSON stocké avec l'asset |

<Note>
  Indiquez soit `folderId`, soit `folderPath`, jamais les deux. L'envoi des deux renvoie une erreur 400.
</Note>

### Exemple de requête

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

### Téléverser dans un dossier

Utilisez `folderPath` pour une structure de dossiers lisible, et `createFolders=true` pour créer les dossiers manquants sur le chemin indiqué :

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

## Réponse

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

| Champ | Type | Description |
| - | - | - |
| `asset.assetId` | string | Identifiant unique de l'asset |
| `asset.url` | string | URL CDN permanente du fichier téléversé |
| `asset.storageKey` | string | Chemin de stockage interne |
| `asset.contentType` | string | Type MIME du fichier téléversé |
| `asset.fileSize` | number | Taille du fichier en octets |
| `asset.type` | string | Type d'asset déduit, ex. `image`, `document` |
| `asset.folderId` | string \| null | Dossier dans lequel l'asset a été placé, le cas échéant |

## Codes de statut

| Statut | Description |
| - | - |
| 200 | Succès - Asset téléversé |
| 400 | `chatId` ou `file` manquant, JSON `metadata` invalide, ou `folderId` et `folderPath` envoyés ensemble |
| 401 | Clé API invalide ou manquante |
| 403 | La clé API n'a pas accès à ce chat |
| 404 | Dossier introuvable |
| 413 | Le fichier dépasse la limite de 20 Mo |
| 500 | Erreur serveur |

## Règles des dossiers

* Les chemins de dossiers sont découpés sur `/`, les espaces sont supprimés et les segments vides ignorés.
* La profondeur maximale est de 8 dossiers.
* Chaque nom de dossier peut compter jusqu'à 255 caractères.
* La correspondance des dossiers ne tient pas compte de la casse au sein d'un même parent.
* Si `folderPath` n'existe pas et que `createFolders` n'est pas `true`, le téléversement échoue avec une erreur 404.

## Bon à savoir

* Cet endpoint utilise la même clé API `macaly_...` que le reste de l'API, même si l'URL commence par `/api/client-app/`. Aucun token séparé n'est nécessaire.
* Le chat référencé par `chatId` doit appartenir à la même équipe que votre clé API.
* Les assets téléversés obtiennent une URL CDN permanente que vous pouvez référencer comme pièce jointe dans [Créer un chat](/docs/fr/api/create-chat) ou [Publier un message](/docs/fr/api/publish-message), ou utiliser n'importe où en dehors de Macaly.


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