Upload and Media Handling

Allmine API dosya gönderiminde multipart/form-data kullanır. Upload endpoint'leri endpoint'e göre farklı field adı ve boyut limiti bekler; generic bir upload helper yazarken field adını parametre olarak geçin.

Ortak kurallar

• Content-Type: multipart/form-data header'ını client kütüphanesinin oluşturmasına izin verin; boundary değerini elle yazmayın.
• Protected upload endpoint'lerinde Authorization: Bearer <accessToken> header'ı gönderilir.
• Mobile upload'larda uri, name ve type alanları birlikte gönderilmelidir.
• Başarılı upload response'u da standard wrapper içinde gelir; asıl payload data alanındadır.

Profil fotoğrafı

Profil fotoğrafı endpoint'i public tanımlıdır, fakat auth context varsa kullanıcı akışıyla birlikte kullanılabilir.

POST /api/v1/file/profile-photo
Content-Type: multipart/form-data

const form = new FormData();
form.append("file", {
  uri: image.uri,
  name: "profile.jpg",
  type: "image/jpeg",
} as any);

const response = await fetch(`${API_URL}/api/v1/file/profile-photo`, {
  method: "POST",
  body: form,
});

Response içindeki data.variants farklı boyutlardaki CDN URL'lerini içerir.

Canlı yayın thumbnail

Canlı yayın oluştururken thumbnail aynı request içinde gönderilir.

POST /api/v1/live-stream/create
Authorization: Bearer <accessToken>
Content-Type: multipart/form-data

Backend thumbnail'i WebP'ye çevirir ve live-stream/thumbnails altında saklar. Client'ın response'taki canlı yayın modelini kaynak kabul etmesi gerekir; local dosya path'i kalıcı URL yerine kullanılmamalıdır.

Mesaj fotoğrafı

Mesaj v2 endpoint'i text ve fotoğraf mesajını aynı route üzerinden destekler.

POST /api/v2/messages
Authorization: Bearer <accessToken>
Content-Type: multipart/form-data

type=media için file zorunludur. type=text için file gönderilmemelidir.

const form = new FormData();
form.append("type", "media");
form.append("targetUserId", targetUserId);
form.append("content", caption ?? "");
form.append("file", {
  uri: photo.uri,
  name: "photo.jpg",
  type: "image/jpeg",
} as any);

const payload = await api.postForm<BaseResponse<Message>>("/api/v2/messages", form);

Admin SVG upload

Gift type SVG upload admin endpoint'i ayrı bir upload kuralı kullanır.

POST /api/v1/gifts/admin/gift-types/upload-svg
Authorization: Bearer <adminAccessToken>
Content-Type: multipart/form-data

Hata yönetimi

Upload sırasında 400 validation hatası, 401/403 auth hatası, dosya eksik olduğunda 500 veya ilgili controller hatası dönebilir. Client tarafında dosya seçimi, dosya boyutu ve MIME type upload başlamadan kontrol edilmelidir.