suno API-Modellleitfaden
Kurzfassung
- suno unterstützt Text-to-Video, Image-to-Video, R2V und Video Edit in einem Workflow.
- Nutzen Sie diese Modellleitfaden-Seite, um Parameter mit minimalen Anfrage- und Antwortbeispielen zu validieren.
- Stabilisieren Sie die Prompts zuerst hier und wechseln Sie dann in die Produktions-API-Integration.
Kernfähigkeiten
- Einheitliches Testen mehrerer Modi:Wechseln Sie an einer Stelle zwischen Text-to-Video, Image-to-Video, R2V und Video Edit.
- Paramaterorientierte Validierung:Iterieren Sie schnell über Prompts, Dauern und Referenzen, bevor Sie in Produktion gehen.
- Produktionsreife Übergabe:Eine minimale Anfrage- und Antwortstruktur hilft Ihnen, stabile Konfigurationen in API-Workflows zu überführen.
Wann verwenden
- Wenn Sie schnelle Iterationen über mehrere Generierungsmodi hinweg benötigen.
- Wenn Sie Parameter und Fehlerbehandlung vor der Integration validieren müssen.
Wann nicht verwenden
- Für asynchrone Batch-Produktion in großem Umfang nutzen Sie direkt die serverseitige API-Pipeline.
- Bei strengen Authentifizierungs- und Audit-Anforderungen bevorzugen Sie die Orchestrierung im Backend.
Laufzeitverhalten
- Diese Modellleitfaden-Seite ist auf Interaktion und Parameter-Probeläufe ausgelegt.
- Das Ausgabefeld zeigt die Ergebnisstruktur der Aufgabe als Integrationshilfe.
Minimale Anfrage
{
"model": "suno",
"mode": "text-to-video",
"input": {
"prompt": "A cinematic city sunrise with soft fog and moving traffic.",
"duration": 5
}
}
Minimale Antwort
{
"task_id": "task_xxxxxxxx",
"model": "suno",
"mode": "text-to-video",
"status": "queued",
"created_at": "2026-04-15T00:00:00.000Z"
}
Zentrale Parameter
| Parameter | Typ | Erforderlich | Standardwert | Bereich | Beschreibung |
|---|
| model | string | Ja | suno | - | Modell-ID. Verwenden Sie den festen Wert suno. |
| prompt | string | Ja | - | - | Hauptanweisung, die Motiv, Aktion, Szene und Stil beschreibt. |
| aspect_ratio | string | Nein | 16:9 | 16:9 | 9:16 |
| duration | integer | Nein | 6 | 5 | 10 |
| resolution | string | Nein | 720P | 720P | Ausgabeauflösung. Standardwert 720P; unterstützt 720P. |
Häufige Fehler
| HTTP | Code | Auslöser | Korrekturmaßnahme | Retry-Richtlinie |
|---|
| 400 | invalid_request_error | Im Anfrage-Payload fehlen Pflichtfelder oder die Feldtypen sind ungültig. | Prüfen Sie model, mode und das input-Schema vor dem Senden. | Erst nach Korrektur des Payload erneut versuchen; vermeiden Sie blinde Wiederholungen. |
| 401 | authentication_error | Authorization-Header fehlt oder der API-Schlüssel ist ungültig. | Prüfen Sie das Format des Bearer-Tokens und den Gültigkeitsbereich des API-Schlüssels. | Nach Korrektur der Authentifizierung erneut versuchen; bei wiederholten Fehlern den Schlüssel rotieren. |
| 429 | rate_limit_exceeded | Anfragefrequenz, Parallelität oder das aktuelle Kontingent lösen das Upstream-Ratenlimit aus. | Wenden Sie zuerst exponentielle Backoff-Wiederholungen an und prüfen Sie dann Anfragefrequenz, Parallelität und Kontingentnutzung. | Nutzen Sie exponentielles Backoff (z. B. 1s/2s/4s) mit Jitter; bei anhaltendem Problem den Anfragetakt senken. |
| 500 | internal_error | Kurzzeitiger Upstream-Fehler oder interne Verarbeitungsstörung. | Erfassen Sie die request id und starten Sie den Retry-Workflow. | 2-3 Wiederholungen mit kurzen Abständen; bei anhaltendem Problem eskalieren. |
FAQ
- Wann sollte ich suno verwenden?
Nutzen Sie es, um Videokonzepte schnell zu validieren, Modusverhalten zu vergleichen und Prompts vor dem API-Rollout zu stabilisieren.
- Wie wähle ich zwischen Text-to-Video und Image-to-Video?
Nutzen Sie Text-to-Video, wenn Sie nur Anweisungen haben; nutzen Sie Image-to-Video, wenn bereits Keyframes oder eine Komposition vorliegen.
- Worin unterscheiden sich R2V und Video Edit?
R2V fokussiert die referenzgesteuerte Generierung, während Video Edit bestehende Video-Assets verändert.
- Fehler beim Bild- oder Videomodell: invalid apitype: -1
Das bedeutet in der Regel, dass die Anfrage an den falschen Endpoint gesendet wurde. Bild- und Videomodelle nutzen normalerweise nicht den Chat-Endpoint. Sende stattdessen die dokumentierte HTTP-Aufgabenanfrage und frage den Aufgabenstatus-Endpoint nach dem Ergebnis ab. Prüfe zuerst den tatsächlichen Anfragetext, die URL und das Payload.
- Eine Bild- oder Videoaufgabe ist fehlgeschlagen, der Nutzer wurde aber trotzdem belastet
Bitte den Nutzer zuerst um das Aufgabenprotokoll oder einen Screenshot und prüfe, ob dort Eingabe- oder Ausgabe-Token auftauchen. Erscheint eine Token-Abrechnung, wurde die Anfrage wahrscheinlich über einen Chat-Endpoint statt über den richtigen Media-Workflow gesendet. Bild- und Videomodelle laufen in der Regel als asynchrone HTTP-Task-APIs: erst die Aufgabe senden, dann gemäß der jeweiligen Dokumentation per Task-ID den Status abfragen.
Verwandte APIs