Müzik Dağıtım API Dokümantasyonu

Overview

Track Create API, ThePreis altyapısında yeni bir müzik parçası (track) oluşturmak için kullanılır.

API, REST prensiplerine uygun olarak çalışır ve tüm veri alışverişi JSON formatındadır.

Important

SongLink ve CoverArt alanları kaldırılmıştır.
Dosya yükleme işlemi ayrı endpoint üzerinden yapılır.

Origin & Security

Tüm API isteklerinde Origin header zorunludur.

Rules

• Origin header olmayan istekler reddedilir
• Sadece whitelist edilen domainler ve IP adreslerinden gelen istekler kabul edilir
• Host kontrolü yapılır

Allowed Origins

Sisteme kayıt etmeniz gerekir.

Example Header

{
  "Authorization": "Bearer API_KEY",
  "Content-Type": "application/json",
  "Origin": "https://stagepublish.com"
}

Server Usage Pricing

Sunucu kullanımına bağlı olarak işlem süresine göre ücretlendirme yapılır. Bu ücretlendirme sadece bilgilendirme amaçlıdır ve sistem tarafından otomatik hesaplanır.

Calculation Logic

Cost = (process_seconds / 3600) * 0.21

Example

10 saniye işlem:

Cost = (10 / 3600) * 0.21
Cost ≈ 0.000583 USD

Notes

• Ücretlendirme sadece işlem süresine göre yapılır
• Yetersiz bakiye durumunda API key otomatik olarak kapatılır

Endpoint

POST https://api.thepreis.com/track/create

Authentication

Tüm isteklerde Bearer Token zorunludur.

{
  "Authorization": "Bearer API_KEY",
  "Content-Type": "application/json",
  "Origin": "https://stagepublish.com"
}

Request Format

İstek gövdesi JSON formatında gönderilmelidir.

Required Fields

Optional Fields

• DuetArtist
• Producer
• Version
• ISRC
• Preview

Validation Rules

Allowed Genres

African, Alternative, Arabic, Asian, Blues, Brazilian, Children,
Christian, Classical, Country, Dance, Easy Listening, Electronic,
Folk, Hip Hop, Indian, Instrumental, Jazz, Latin, Metal, Pop,
R&B, Reggae, Relaxation, Rock, Various, World

Allowed Languages

Afrikaans, Albanian, Arabic, Armenian, Azerbaijani, Basque,
Bengali, Bulgarian, Catalan, Cambodian, Chinese (Mandarin),
Croatian, Czech, Danish, Dutch, English, Estonian, Fiji,
Finnish, French, Georgian, German, Greek, Gujarati, Hebrew,
Hindi, Hungarian, Icelandic, Indonesian, Irish, Italian,
Japanese, Javanese, Korean, Kurdish, Latin, Latvian,
Lithuanian, Macedonian, Malay, Malayalam, Maltese, Maori,
Marathi, Mongolian, Nepali, Norwegian, Persian, Polish,
Portuguese, Punjabi, Quechua, Romanian, Russian, Samoan,
Serbian, Slovak, Slovenian, Spanish, Swahili, Swedish,
Tamil, Tatar, Telugu, Thai, Tibetan, Tonga, Turkish,
Ukrainian, Urdu, Uzbek, Vietnamese, Welsh, Xhosa

Warning Field

Yes | No | Edited

ArtistMapping

• ArtistMapping zorunludur
• Sadece MainArtist desteklenir
• ArtistName alanında sanatçılar virgül ile ayrılmalıdır
• Minimum 1, maksimum 3 ana sanatçı kabul edilir
• Sanatçı sayısı kadar Spotify eşleşmesi gönderilmelidir
• Eksik link gönderilirse hata döner
• Fazla link gönderilirse hata döner
• Her link sadece şu iki formattan biri olabilir:
  • NEW
  • https://open.spotify.com/artist/...

Artist Mapping

ArtistMapping alanı, ana sanatçıların Spotify profil eşleşmelerini belirtmek için kullanılır.

Kurallar

• ArtistName alanındaki sanatçılar virgül ile ayrılır
• Maksimum 3 ana sanatçı desteklenir
• Her sanatçı için sıraya göre bir Spotify değeri gönderilmelidir
• Sadece şu iki değer kabul edilir:
  • NEW
  • https://open.spotify.com/artist/...

Örnek Yapı

{
  "ArtistName": "Ahmet,Mehmet",
  "ArtistMapping": {
    "MainArtist": {
      "1": {
        "Spotify": "https://open.spotify.com/artist/XXXXXXXXXXXXXXXXXXXXX"
      },
      "2": {
        "Spotify": "NEW"
      }
    }
  }
}

Önemli Notlar

• 1 sanatçı varsa sadece MainArtist[1] gönderilmelidir
• 2 sanatçı varsa sadece MainArtist[1] ve MainArtist[2] gönderilmelidir
• 3 sanatçı varsa sadece MainArtist[1], MainArtist[2], MainArtist[3] gönderilmelidir
• Sanatçı sayısı ile mapping sayısı birebir eşleşmelidir

Example Request

{
  "ArtistName": "Sanatçı Adı,İkinci Sanatçı",
  "TrackName": "Yeni Parça",
  "Genre": "Pop",
  "ReleaseDate": "2025-01-01",
  "UPC": "123456789012",
  "Copyright": "Copyright",
  "PLine": "Phonogram Copyright",
  "Lyricist": "Sarp Deniz",
  "Warning": "No",
  "Company": "Company Records",
  "PartName": "Yeni Parça",
  "Composer": "Sarp Deniz",
  "TitleLang": "Turkish",
  "LyricLang": "Turkish",
  "ArtistMapping": {
    "MainArtist": {
      "1": {
        "Spotify": "https://open.spotify.com/artist/XXXXXXXXXXXXXX"
      },
      "2": {
        "Spotify": "NEW"
      }
    }
  }
}

Successful Response

{
  "success": "true",
  "data": {
    "CatalogUnique": "unique-value",
    "Message": "Track başarıyla oluşturuldu"
  }
}

Error Responses

Validation Error

{
  "success": "false",
  "error_code": "VALIDATION_ERROR",
  "fields": ["UPC", "Genre"]
}

Invalid Genre

{
  "success": "false",
  "error_code": "INVALID_GENRE"
}

Invalid Song File

{
  "success": "false",
  "error_code": "INVALID_SONG_LINK_EXT"
}

Invalid Artist Count

{
  "success": "false",
  "error_code": "INVALID_ARTIST_COUNT",
  "message": "ArtistName must contain between 1 and 3 main artists separated by commas"
}

Invalid Artist Mapping

{
  "success": "false",
  "error_code": "INVALID_ARTIST_MAPPING",
  "message": "ArtistMapping.MainArtist is required"
}

Artist / Link Count Mismatch

{
  "success": "false",
  "error_code": "ARTIST_LINK_COUNT_MISMATCH",
  "message": "Artist count and ArtistMapping.MainArtist count must match exactly"
}

Missing Spotify Link

{
  "success": "false",
  "error_code": "MISSING_SPOTIFY_LINK",
  "message": "MainArtist[1].Spotify is required"
}

Invalid Spotify Link

{
  "success": "false",
  "error_code": "INVALID_SPOTIFY_LINK",
  "message": "MainArtist[1].Spotify must be either NEW or a valid Spotify artist profile URL"
}

Extra Spotify Link

{
  "success": "false",
  "error_code": "EXTRA_SPOTIFY_LINK",
  "message": "MainArtist[2].Spotify should not be sent because ArtistName contains only 1 artist(s)"
}

Invalid Language

{
  "success": "false",
  "error_code": "INVALID_TITLE_LANG"
}

{
  "success": "false",
  "error_code": "INVALID_LYRIC_LANG"
}

Track List API

Kullanıcıya ait onaylı (approved) ve kaldırma (takedown) durumundaki eserlerin listesini döndürür.

Endpoint

POST https://api.thepreis.com/track/list

Authentication

{
  "Authorization": "Bearer API_KEY",
  "Content-Type": "application/json",
  "Origin": "https://stagepublish.com"
}

Request Body

Boş gönderilebilir.

Successful Response

{
  "success": "true",

  "APPROVED": [
    {
      "CatalogUnique": "unique-value",
      "UPC": "123456789012"
    }
  ],

  "TAKEDOWN": [
    {
      "CatalogUnique": "unique-value",
      "UPC": "123456789012"
    }
  ],

  "counts": {
    "approved": 1,
    "takedown": 1,
    "total": 2
  }
}

Status Meaning

• APPROVED: Onaylanan
• TAKEDOWN: Yayından Kaldırılan

Track Takedown API

Kullanıcıya ait bir eserin kaldırılması (takedown request) için kullanılır.

Endpoint

POST https://api.thepreis.com/track/takedown

Authentication

{
  "Authorization": "Bearer API_KEY",
  "Content-Type": "application/json",
  "Origin": "https://stagepublish.com"
}

Request Body

{
  "CatalogUnique": "unique-value"
}

Requirements

• Eser kullanıcıya ait olmalıdır
• Onaylanmış olmalıdır
• Başarılı olursa → TAKEDOWN sırasına alınır

Successful Response

{
  "success": "true",
  "message": "Takedown request received",
  "CatalogUnique": "unique-value"
}

Error Responses

Invalid CatalogUnique

{
  "success": "false",
  "error_code": "INVALID_CATALOG_UNIQUE",
  "message": "Geçersiz veya size ait olmayan CatalogUnique"
}

Invalid Status

{
  "success": "false",
  "error_code": "INVALID_STATUS",
  "message": "Bu eser takedown için uygun durumda değil"
}

Missing CatalogUnique

{
  "success": "false",
  "error_code": "MISSING_CATALOG_UNIQUE"
}

Track Status API

Bir eserin dağıtım durumunu (Delivery Status) ve platform listesini döndürür.

Endpoint

POST https://api.thepreis.com/track/status

Authentication

{
  "Authorization": "Bearer API_KEY",
  "Content-Type": "application/json",
  "Origin": "https://stagepublish.com"
}

Request Body

{
  "CatalogUnique": "unique-value"
}

Requirements

• Eser kullanıcıya ait olmalıdır
• Status değeri APPROVED veya TAKEDOWN olmalıdır
• Geçersiz CatalogUnique hata döndürür

Successful Response

{
  "success": "true",
  "CatalogUnique": "unique-value",
  "Status": "APPROVED",
  "Platforms": [
    "Spotify",
    "Apple Music",
    "YouTube Art Tracks",
    "Deezer"
  ]
}

Status Meaning

• APPROVED: Yayında ve onaylı
• TAKEDOWN: Kaldırma sürecinde

Error Responses

Invalid CatalogUnique

{
  "success": "false",
  "error_code": "INVALID_CATALOG_UNIQUE"
}

Invalid Status

{
  "success": "false",
  "error_code": "INVALID_STATUS"
}

Missing CatalogUnique

{
  "success": "false",
  "error_code": "MISSING_CATALOG_UNIQUE"
}

Provider Error

{
  "success": "false",
  "error_code": "PROVIDER_ERROR"
}

Track Edit API

Mevcut bir eseri güncellemek (edit) için kullanılır. Edit işlemi sadece size ait ve Düzenleme durumundaki eserlerde yapılabilir. Başarılı olursa eser tekrar işlenmek üzere Sırada durumuna alınır.

Endpoint

POST https://api.thepreis.com/track/edit

Authentication

{
  "Authorization": "Bearer API_KEY",
  "Content-Type": "application/json",
  "Origin": "https://stagepublish.com"
}

Request Body

İstek gövdesi JSON formatında gönderilmelidir.

Required Fields

Optional Fields

• DuetArtist
• Producer
• Version
• ISRC
• Preview

Validation Rules

• CatalogUnique zorunludur ve size ait olmalıdır
• Düzenleme değilse edit yapılamaz
• ReleaseDate formatı: YYYY-MM-DD
• UPC sadece rakam
• Genre, TitleLang, LyricLang allowed list içinde olmalı

Example Request

{
  "CatalogUnique": "unique-value",
  "ArtistName": "Sanatçı Adı,İkinci Sanatçı",
  "DuetArtist": "Düet Sanatçı",
  "TrackName": "Güncellenmiş Parça",
  "Genre": "Pop",
  "ReleaseDate": "2025-01-01",
  "UPC": "123456789012",
  "Copyright": "Copyright",
  "PLine": "Phonogram Copyright",
  "Lyricist": "Sarp Deniz",
  "Composer": "Sarp Deniz",
  "Warning": "No",
  "Company": "Company Records",
  "PartName": "Güncellenmiş Parça",
  "TitleLang": "Turkish",
  "LyricLang": "Turkish"
}

Successful Response

{
  "success": "true",
  "data": {
    "CatalogUnique": "unique-value",
    "Message": "Track edit received."
  }
}

Error Responses

Missing CatalogUnique

{
  "success": "false",
  "error_code": "MISSING_CATALOG_UNIQUE"
}

Invalid CatalogUnique

{
  "success": "false",
  "error_code": "INVALID_CATALOG_UNIQUE"
}

Forbidden

{
  "success": "false",
  "error_code": "FORBIDDEN"
}

Invalid Status

{
  "success": "false",
  "error_code": "INVALID_STATUS"
}

Validation Error

{
  "success": "false",
  "error_code": "VALIDATION_ERROR",
  "fields": ["ArtistName","TrackName"]
}

Track Edit İnfo API

Bir eserin düzenlemeye uygun olup olmadığını ve düzenleme sebebini (edit reason) öğrenmek için kullanılır.

Endpoint

POST https://api.thepreis.com/track/edit-info

Authentication

{
  "Authorization": "Bearer API_KEY",
  "Content-Type": "application/json",
  "Origin": "https://stagepublish.com"
}

Request Body

{
  "CatalogUnique": "unique-value"
}

Requirements

• Eser kullanıcıya ait olmalıdır
• Eser Düzenleme durumunda olmalıdır
• Geçersiz CatalogUnique hata döndürür

Successful Response

{
  "success": "true",
  "data": {
    "CatalogUnique": "unique-value",
    "edit_info": "Edit reason"
  }
}

Error Responses

Missing CatalogUnique

{
  "success": "false",
  "error_code": "MISSING_CATALOG_UNIQUE"
}

Invalid CatalogUnique

{
  "success": "false",
  "error_code": "INVALID_CATALOG_UNIQUE"
}

Invalid Status

{
  "success": "false",
  "error_code": "INVALID_STATUS",
  "message": "Track is not eligible for status check"
}

Artwork & Audio Upload

Ses dosyası ve kapak görseli yükleme işlemi ayrı endpoint üzerinden yapılır.

Endpoint

POST https://api.thepreis.com/artwork/upload

Headers

Authorization: Bearer API_KEY
Content-Type: application/json
Origin: required

Request Body

{
  "CatalogUnique": "unique-value",
  "SongLink": "https://...wav",
  "CoverArt": "https://...jpg"
}

Rules

• SongLink: .wav / .flac
• CoverArt: .jpg
• Max audio: 100MB
• Max image: 10MB
• Sadece S3 ve Google Drive

Artwork Quality Check API

Kapak görselinin teknik kurallarını kontrol eder (URL, uzantı, MIME, çözünürlük, dosya boyutu) ve ayrıca görselin bulanık/pixelli (LOW/HIGH) olup olmadığını ölçer. Görsel HIGH ise ayrıca %50+ beyazlık (Apple uygunluğu) sonucu döner.

Endpoint

POST https://api.thepreis.com/artwork/quality

Authentication

{
  "Authorization": "Bearer API_KEY",
  "Content-Type": "application/json",
  "Origin": "https://stagepublish.com"
}

Request Body

{
  "CoverArt": "https://...jpg"
}

Rules

• CoverArt zorunlu
• Sadece izinli hostlar (S3 / Drive)
• URL uzantısı .jpg / .jpeg
• MIME: image/jpeg
• Çözünürlük: 3000x3000
• Dosya boyutu limiti: 10MB (aşarsa hata döner)
• Kalite sonucu: quality.grade = HIGH / LOW
• white_ratio ve apple_music_eligible sadece HIGH ise döner

Successful Response

{
  "success": "true",
  "data": {
    "message": "Cover art passed quality checks.",
    "url_checked": "https://....jpg",
    "bytes": 8666025,
    "detected_mime": "image/jpeg",
    "width": 3000,
    "height": 3000,
    "quality": {
      "grade": "HIGH",
      "focus": 245.12,
      "entropy": 6.88,
      "blockiness_ratio": 1.03,
      "nonwhite_ratio": 0.91
    },
    "white_ratio": 0.044,
    "apple_music_eligible": true
  }
}

Error Responses

Missing CoverArt

{
  "success": "false",
  "error_code": "COVER_ART_REQUIRED",
  "message": "CoverArt field is required."
}

Host Not Allowed

{
  "success": "false",
  "error_code": "HOST_NOT_ALLOWED",
  "message": "Only Amazon S3 and Google Drive URLs are allowed."
}

Invalid Extension

{
  "success": "false",
  "error_code": "INVALID_EXTENSION",
  "message": "Cover art must have a .jpg or .jpeg URL extension."
}

File Too Large

{
  "success": "false",
  "error_code": "FILE_TOO_LARGE",
  "message": "Files over 10MB are not accepted."
}

Invalid MIME

{
  "success": "false",
  "error_code": "INVALID_MIMETYPE",
  "message": "File MIME type must be image/jpeg."
}

Invalid Resolution

{
  "success": "false",
  "error_code": "INVALID_RESOLUTION",
  "message": "Cover art resolution must be exactly 3000x3000.",
  "details": { "width": 1200, "height": 1200 }
}

Download Failed

{
  "success": "false",
  "error_code": "DOWNLOAD_FAILED",
  "message": "Could not fetch the file for validation."
}