> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Przewodnik integracji projektu Suno Studio

> Suno Music Generation API guide - Ace Data Cloud

API projektu Suno Studio zarządza wielościeżkowymi projektami muzycznymi przez jeden punkt wejścia:

```http theme={null}
POST /suno/projects
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

`action` w żądaniu określa typ operacji. Klucz główny Project jednolicie używa `id`; `version_id` oznacza aktualną wersję projektu, wszystkie operacje modyfikacji i eksportu muszą przekazywać najnowszą wersję, aby uniknąć nadpisania przy współbieżności.

## Przegląd operacji

| action | Tryb | Zastosowanie |
| - | - | - |
| `create` | Synchroniczny | Tworzenie pustego projektu |
| `retrieve` | Synchroniczny | Odczytywanie projektu i pełnego edytowalnego `state` |
| `save` | Synchroniczny | Zapisywanie pełnego stanu projektu |
| `upload` | Asynchroniczny | Inicjalizowanie materiału, który można dodać do projektu, z adresu audio HTTPS |
| `add_track` | Asynchroniczny | Dodawanie istniejącego audio do projektu |
| `generate_track` | Asynchroniczny | Generowanie kandydatów nowych ścieżek audio dla określonego zakresu |
| `replace_section` | Asynchroniczny | Generowanie kandydatów lokalnego zastąpienia |
| `commit_candidate` | Asynchroniczny | Zatwierdzanie wybranego kandydata do projektu |
| `remove_track` | Synchroniczny | Usuwanie określonej ścieżki |
| `render` | Asynchroniczny | Eksportowanie zapisanej wersji jako pełnej piosenki |

Operacje asynchroniczne natychmiast zwracają `task_id`. Użyj bezpłatnego interfejsu `/suno/tasks` do odpytywania lub przekaż `callback_url`, aby otrzymać wynik końcowego stanu.

## Tworzenie i odczytywanie

```json theme={null}
{"action":"create","title":"My Studio Project"}
```

Wszystkie operacje modyfikacji powinny wysyłać unikalny nagłówek `Idempotency-Key`. Po pomyślnym utworzeniu `data.id` w odpowiedzi jest Project ID. Nowy pusty projekt może nie mieć `version_id` przed pierwszym zapisem.

```json theme={null}
{"action":"retrieve","id":"PROJECT_ID"}
```

Odpowiedź odczytu zawiera pełny `state`. Nowy pusty projekt zwraca `{"tracks":[],"timing":{"bps":2}}`, co można bezpośrednio użyć do pierwszego zapisu. `timing.bps` oznacza liczbę beatów na sekundę, domyślnie 2 (120 BPM), i musi być liczbą dodatnią; `startBeats`, `endBeats` i `readStartBeats` fragmentów używają jednostki beatów projektu, nie można bezpośrednio traktować pozycji taktów z analizy audio jako współrzędnych osi czasu.

## Zapisywanie pełnego stanu

```json theme={null}
{
  "action":"save",
  "id":"PROJECT_ID",
  "version_id":"CURRENT_VERSION_ID",
  "title":"Edited Project",
  "state":{"tracks":[],"timing":{"bps":2}}
}
```

Przy pierwszym zapisie nowego pustego projektu można pominąć `version_id`; po wygenerowaniu wersji przez pierwszy zapis kolejne zapisy muszą przekazywać najnowszą wartość. Jeśli wersja uległa zmianie, interfejs zwraca HTTP 409. W takim przypadku ponownie wykonaj `retrieve`, połącz zmiany, a następnie wyślij je z nowym kluczem idempotencji; nie ponawiaj bezkrytycznie starego żądania.

## Przesyłanie i dodawanie ścieżek

```json theme={null}
{
  "action":"upload",
  "id":"PROJECT_ID",
  "version_id":"CURRENT_VERSION_ID",
  "audio_url":"https://cdn.example.com/reference.mp3",
  "async":true
}
```

Po pomyślnym przesłaniu odczytaj ID audio z `response.data.candidate.audio_id`. Następnie dodaj je do projektu:

```json theme={null}
{
  "action": "add_track",
  "id": "PROJECT_ID",
  "version_id": "CURRENT_VERSION_ID",
  "audio_id": "AUDIO_ID",
  "name": "Backing Vocals"
}
```

Dodanie ścieżki domyślnie zachowuje szybkość odtwarzania audio i przelicza czas trwania audio na beaty na podstawie `timing.bps` projektu. Po każdym `save`, `add_track`, `commit_candidate` lub `remove_track` należy używać nowego `version_id` z odpowiedzi.

## Generowanie i zastępowanie

`generate_track` generuje kandydatów ścieżek audio dla zakresu projektu; `replace_section` zwraca dwóch kandydatów lokalnego zastąpienia. Obie operacje nie wybierają automatycznie rezultatu artystycznego. Model musi używać publicznej nazwy: `chirp-v3-5`, `chirp-v4`, `chirp-v4-5`, `chirp-v4-5-plus`, `chirp-v5`, `chirp-v5-5`, `chirp-v6`, `chirp-v6-wild` lub `chirp-v6-mini`; dostępność konkretnej operacji nadal zależy od końcowego stanu zadania, nieobsługiwane nazwy zwracają 400 przed wysłaniem. Nie następuje automatyczna zmiana na inny model.

```json theme={null}
{
  "action":"replace_section",
  "id":"PROJECT_ID",
  "version_id":"CURRENT_VERSION_ID",
  "source_audio_id":"AUDIO_ID",
  "start_seconds":35.12,
  "end_seconds":48.76,
  "model":"chirp-v6",
  "replacement_lyrics":"新的歌词片段",
  "async":true
}
```

`generate_track` musi również podać `render_audio_id` (ukończone audio eksportu projektu), `stem_control_tags` oraz źródłowe audio `source_audio_id`. `batch_size` wynosi 1–4, domyślnie 2; `start_seconds`, `end_seconds` to sekundy źródłowego audio. Zakres zastępowania z `fixed=true` musi być krótszy niż 26 sekund.

Po wybraniu kandydata zatwierdź go:

```json theme={null}
{
  "action":"commit_candidate",
  "id":"PROJECT_ID",
  "version_id":"CURRENT_VERSION_ID",
  "operation_id":"OPERATION_ID",
  "candidate_id":"CANDIDATE_ID",
  "track_id":"TRACK_ID"
}
```

Kandydat jest powiązany z wersją projektu w chwili generowania. Gdy projekt już się zmienił, starego kandydata nie można bezpośrednio zatwierdzić.

Kandydat lokalnego zastąpienia jest zatwierdzany do oryginalnej ścieżki zawierającej unikalny fragment źródłowy, kandydat pełnego take zachowuje pierwotną pozycję i zastępuje pierwotny fragment; kandydat zakresu zastępuje wyłącznie żądany zakres, zachowując fragmenty przed i po nim. Gdy nie można niezawodnie dopasować czasu trwania, zwracane jest 400 i zachowywany jest pierwotny projekt; w takim przypadku nie przekazuj `start_beats`, `end_beats`. Kandydat nowej ścieżki powinien zostać zatwierdzony do pustej ścieżki zapisanej z wyprzedzeniem, domyślnie z zachowaniem punktu początkowego fragmentu źródłowego, lub jawnie przekaż zakres bez nakładania się; nakładanie się istniejących fragmentów na tej samej ścieżce zwróci 400. Nie generuj najpierw, a następnie nie twórz nowej ścieżki, ponieważ zmiana wersji spowoduje wygaśnięcie kandydata.

## Eksportowanie pełnej piosenki

```json theme={null}
{
  "action":"render",
  "id":"PROJECT_ID",
  "version_id":"CURRENT_VERSION_ID",
  "title":"Final Mix",
  "lyrics":"[Instrumental]",
  "async":true,
  "callback_url":"https://example.com/webhooks/suno"
}
```

Serwer odczytuje autorytatywny stan projektu określonej wersji i składa parametry eksportu. Gdy `start_beats`, `end_beats` są pominięte, domyślnie eksportowany jest zakres od najwcześniejszego początku do najpóźniejszego końca wszystkich słyszalnych fragmentów; wyciszone ścieżki/fragmenty nie są uwzględniane, a gdy istnieją ścieżki solo, wybierane są wyłącznie ścieżki solo. Pusty projekt lub brak prawidłowych słyszalnych ścieżek zwraca 400. Wynik końcowego stanu zawiera `render_id`, `audio_id`, `audio_url` i czas trwania. Projekt jest powiązany ze środowiskiem wykonawczym z chwili utworzenia i nie można go migrować między środowiskami ani automatycznie przełączać awaryjnie.

> Można przesyłać lub przetwarzać wyłącznie audio, do którego posiada się legalne prawa użytkowania. API projektu jest obecnie w fazie Beta; należy trwale przechowywać końcowy URL audio w ważnych wynikach.

## Odpytywanie i odzyskiwanie po błędach

```json theme={null}
{"action":"retrieve","id":"TASK_ID"}
```

Wyślij powyższe żądanie do `/suno/tasks`. Zadanie Projects jest uznawane za udane, gdy istnieje `finished_at` oraz `response.success=true`; `response.success=false` oznacza niepowodzenie. Zwrócenie HTTP 200 lub `task_id` przy przesłaniu oznacza jedynie, że żądanie zostało przyjęte, a nie że audio zostało ukończone.

Ten sam `Idempotency-Key` z tym samym żądaniem odczyta ponownie pierwotny wynik (w tym niepowodzenie), nie wygeneruje automatycznie ponownie ani nie naliczy opłaty ponownie. Aby jawnie ponowić nieudaną operację, najpierw zapytaj o pierwotne zadanie, aby potwierdzić niepowodzenie, a następnie użyj nowego klucza; nie przesyłaj ponownie, gdy pierwotne zadanie jest nadal przetwarzane lub wynik jest niepewny.

Klasyfikacja błędów obejmuje `studio_unavailable` / `studio_model_unavailable` (503, tymczasowo nie można przetworzyć lub model jest niedostępny), `studio_model_unsupported` (400, model nie obsługuje tej operacji), `studio_state_invalid` (400, stan projektu lub zakres eksportu jest nieprawidłowy), `too_many_requests` (429), `studio_audio_unavailable` (403, audio referencyjne nie może zostać użyte do eksportu projektu) oraz `content_rejected` (403). Zachowaj `trace_id` na potrzeby diagnostyki.


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