Autori e collaboratori di traccia (API)

Quando crei una traccia tramite l’API pubblica di LabelGrid, descrivi le persone che ci sono dietro con due array separati: uno per i crediti del brano (chi ha fatto cosa) e uno per le ripartizioni editoriali (chi possiede la composizione e la sua percentuale). Questa guida spiega cosa si aspetta ciascun array e le regole che si applicano quando crei una traccia.

Due array per traccia

Ogni traccia comprende due array indipendenti:

• contributors[] — crediti del brano: chi ha fatto cosa nella traccia.
• writers[] — ripartizioni editoriali: chi possiede la composizione e la sua percentuale.

Entrambi gli array fanno riferimento a un profilo autore tramite writerId (camelCase) o writer_id (snake_case). Invia esattamente uno dei due — inviarli entrambi viene rifiutato. L’ID deve corrispondere a un autore che possiedi.

Entrambi gli array puntano allo stesso registro di autori — gli autori che crei tramite l’endpoint Writers. Quindi un collaboratore e un autore di ripartizione editoriale fanno riferimento allo stesso record autore sottostante.

contributors[] — obbligatorio alla creazione

contributors[] è obbligatorio alla creazione, con almeno una voce. Ogni voce ha:

• writerId / writer_id
• roles[] — da 1 a 3 ruoli, presi dall’elenco di riferimento dei Ruoli collaboratore
• ai_contribution — none, partly o all

Regole che si applicano quando fai il POST di una traccia:

• Coprire tutte e tre le categorie di ruolo — tra i tuoi collaboratori deve esserci almeno un ruolo di Interprete (Performer), uno di Composizione e testi (Composition & Lyrics) e uno di Produzione e ingegneria (Production & Engineering).
• Almeno una persona — ai_contribution non può essere all per tutti i collaboratori.
• Nessun ID autore duplicato nell’array dei collaboratori.

writers[] — ripartizioni editoriali (facoltativo, ma deve totalizzare 100% se presente)

writers[] è facoltativo alla creazione. Se lo includi, ogni voce ha:

• writerId / writer_id
• roles[] — almeno un ruolo; gli unici valori consentiti sono Composer e Lyricist
• percentage_share — un numero da 0 a 100

Regole:

• Le ripartizioni devono totalizzare 100% — i valori di percentage_share di tutti gli autori devono sommare a 100.
• Nessun ID autore duplicato.
• Nessun ruolo duplicato per uno stesso autore.

Un esempio minimo

{
  "title": "Track One",
  "contributors": [
    {
      "writerId": "wr_123",
      "roles": ["Vocals", "Composer", "Producer"],
      "ai_contribution": "none"
    }
  ],
  "writers": [
    {
      "writerId": "wr_123",
      "roles": ["Composer", "Lyricist"],
      "percentage_share": 100
    }
  ]
}

Errori comuni

• Usa il plurale roles, non role.
• Usa percentage_share, non share.
• Non inviare writerId e writer_id nella stessa voce.
• Per gli autori di ripartizione editoriale, sono accettati come ruoli solo Composer e Lyricist.
• Se includi writers[], le ripartizioni devono totalizzare esattamente 100%.

Risorse correlate

• Panoramica dell’API — endpoint, autenticazione e il riferimento completo (compresi i dati di riferimento dei Ruoli collaboratore)
• Autori e collaboratori — come funzionano i profili autore nel tuo catalogo