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

> Bir sohbete dosya yükleyin ve kalıcı bir CDN URL'si alın

Bir sohbetin Varlıklar bölümüne dosya yükler ve kalıcı bir CDN URL'si döndürür. Görseller, belgeler, ses, video veya uygulamanızın ya da sürecinizin URL üzerinden referans vermesini istediğiniz diğer dosyalar için bunu kullanın.

## İstek

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

### Başlıklar

| Header | Zorunlu | Açıklama |
| - | - | - |
| `Authorization` | Evet | `Bearer macaly_...` |
| `Content-Type` | Evet | `multipart/form-data` |

### Form verisi parametreleri

| Alan | Tür | Zorunlu | Varsayılan | Açıklama |
| - | - | - | - | - |
| `chatId` | string | Evet | - | Varlığın yükleneceği sohbet |
| `file` | file | Evet | - | Yüklenecek dosya. En fazla 20 MB |
| `folderPath` | string | Hayır | - | Eğik çizgiyle ayrılmış klasör yolu, örneğin `images/products` |
| `createFolders` | string | Hayır | `false` | `"true"`, `"1"` veya `"yes"` değeri, `folderPath` içindeki eksik klasörleri oluşturur |
| `folderId` | string | Hayır | - | Mevcut klasör kimliği. `folderId` ve `folderPath` alanlarını birlikte göndermeyin |
| `title` | string | Hayır | Orijinal dosya adı | Varlık için görüntülenecek başlık |
| `metadata` | string (JSON) | Hayır | - | Varlıkla birlikte saklanan JSON nesnesi |

<Note>
  `folderId` veya `folderPath` alanlarından yalnızca birini gönderin, ikisini birden değil. İkisini birden göndermek 400 hatası döndürür.
</Note>

### Örnek istek

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

### Klasöre yükleme

Okunabilir bir klasör yapısı için `folderPath` kullanın ve yol üzerindeki eksik klasörlerin oluşturulması için `createFolders=true` ayarlayın:

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

## Yanıt

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

| Alan | Tür | Açıklama |
| - | - | - |
| `asset.assetId` | string | Varlığın benzersiz kimliği |
| `asset.url` | string | Yüklenen dosyanın kalıcı CDN URL'si |
| `asset.storageKey` | string | Dahili depolama yolu |
| `asset.contentType` | string | Yüklenen dosyanın MIME türü |
| `asset.fileSize` | number | Dosya boyutu (bayt cinsinden) |
| `asset.type` | string | Çıkarsanan varlık türü, örneğin `image`, `document` |
| `asset.folderId` | string \| null | Varsa, varlığın yerleştirildiği klasör |

## Durum kodları

| Durum | Açıklama |
| - | - |
| 200 | Başarılı - Varlık yüklendi |
| 400 | `chatId` veya `file` eksik, `metadata` JSON'ı geçersiz ya da `folderId` ve `folderPath` birlikte gönderilmiş |
| 401 | Geçersiz veya eksik API anahtarı |
| 403 | API anahtarının bu sohbete erişimi yok |
| 404 | Klasör bulunamadı |
| 413 | Dosya 20 MB yükleme sınırını aşıyor |
| 500 | Sunucu hatası |

## Klasör kuralları

* Klasör yolları `/` karakterinden bölünür, baştaki ve sondaki boşluklar kırpılır ve boş bölümler yok sayılır.
* En fazla 8 klasör derinliği desteklenir.
* Her klasör adı en fazla 255 karakter olabilir.
* Aynı üst klasör içinde klasör eşleştirmesi büyük/küçük harfe duyarsızdır.
* `folderPath` mevcut değilse ve `createFolders` `true` değilse, yükleme 404 hatasıyla başarısız olur.

## Bilmeniz gerekenler

* URL `/api/client-app/` ile başlasa da bu endpoint, API'nin geri kalanıyla aynı `macaly_...` API anahtarını kullanır. Ayrı bir token gerekmez.
* `chatId` ile belirtilen sohbet, API anahtarınızla aynı ekibe ait olmalıdır.
* Yüklenen varlıklar kalıcı bir CDN URL'si alır; bu URL'yi [Create chat](/docs/tr/api/create-chat) veya [Publish message](/docs/tr/api/publish-message) isteklerinde ek olarak kullanabilir ya da Macaly dışında herhangi bir yerde kullanabilirsiniz.


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