Zum Hauptinhalt springen
Youka ist dafür ausgelegt, von Agenten gesteuert zu werden. Jeder CLI-Befehl gibt einen maschinenlesbaren JSON-Umschlag zurück, jeder Schreibvorgang unterstützt Idempotency-Keys, und die öffentliche API bietet dieselbe Oberfläche mit derselben Semantik. Diese Seite sammelt die Betriebsregeln, die ein Agent-Autor benötigt, bevor er Youka in einen Workflow verdrahtet.

​
Erste Schritte

Wenn du zum ersten Mal einen Agenten einrichtest, installiere zuerst die Youka CLI und danach die Youka-Karaoke-Skill: 
npm install -g @youka/cli
npx skills add https://github.com/youka-io/skills --skill youka-karaoke
Damit erhält der Agent eine sofort einsatzbereite Youka-Skill, die durch die CLI unterstützt wird. Sobald das installiert ist, nutze die Workflow-Muster unten, um Karaoke-Videos zu erstellen, den Stil anzupassen und MP4-Dateien sicher zu exportieren.

​
Deinen Agenten prompten

Nach der Installation von CLI und Skill kannst du deinem Agenten eine direkte Aufgabe wie diese geben: 
Use Youka to create a karaoke video from /path/to/song.mp3. Transcribe the lyrics in English, use a clean karaoke subtitle style, export the final video in 1080p, and save it as ./karaoke.mp4.

​
Betriebsregeln

Immer --json verwenden

In der CLI immer --json übergeben. In der API immer Accept: application/json setzen. Niemals menschenlesbare Ausgabe parsen.

Immer einen Idempotency-Key senden

Jeder Schreibvorgang sollte einen stabilen Idempotency-Key tragen, damit Wiederholungen nach einem Timeout das ursprüngliche Ergebnis zurückgeben, statt Arbeit zu duplizieren.

Dauerhaften Zustand erneut lesen

Vertraue keinen veralteten Mutationsantworten. Nach einer terminalen Aufgabe das Projekt oder den Export erneut lesen, um den finalen Zustand zu erhalten.

Mit Backoff pollen

Mit einem Intervall von 2–3 Sekunden starten. Für lange Jobs exponentiell erhöhen. 429-Antworten beachten.

​
Output-Vertrag

Jeder CLI-Befehl im Modus --json schreibt genau einen Umschlag nach stdout. Erfolg: 
{
  "schemaVersion": "1",
  "ok": true,
  "data": { "id": "prj_abc123", "title": "My Song" }
}
Fehler: 
{
  "schemaVersion": "1",
  "ok": false,
  "error": {
    "code": "CONFLICT",
    "message": "A request with this Idempotency-Key is already in progress.",
    "retryable": true
  }
}
Exit-Codes:
CodeBedeutungRetry?
0Erfolg.N/A
1Laufzeitfehler (Netzwerk, API, Rendering).error.retryable prüfen.
2Ungültige Eingabe (schlechte Flags, unlesbarer Payload).Nein — Eingabe korrigieren.

​
End-to-end-Workflow

Der kanonische Agent-Workflow ist: Projekt erstellen, warten, exportieren, Ergebnis herunterladen. Hier ist das vollständige Muster mit CLI- und SDK-Implementierungen. 
# 1. Create the project and wait for stems + lyrics sync to finish
PROJECT_JSON=$(youka project create ./song.mp3 \
  --mode transcribe \
  --lang en \
  --wait \
  --idempotency-key "create-song-2026-04-08-001" \
  --json)

PROJECT_ID=$(echo "$PROJECT_JSON" | jq -r '.data.projectId')

# 2. Start and wait for an export
EXPORT_JSON=$(youka export create "$PROJECT_ID" \
  --resolution 1080p \
  --quality high \
  --wait \
  --download \
  --output ./karaoke.mp4 \
  --idempotency-key "export-$PROJECT_ID-v1" \
  --json)

echo "Done:" "$(echo "$EXPORT_JSON" | jq -r '.data.fileUrl')"

​
Polling-Empfehlungen

Die meisten Schreibvorgänge geben im SDK Operation-Handles zurück. Bevorzuge client.projects.wait(...) und client.exports.wait(...) und gehe nur dann auf client.tasks.* herunter, wenn du ausdrücklich Low-Level-Task-Zugriff brauchst.
Job-TypEmpfohlenes AnfangsintervallMax. Wartezeit
Project create (stems + lyrics sync)3 s15 min
Stem separation only3 s10 min
Lyrics sync only2 s5 min
Export render3 s30 min
In der CLI übernimmt --wait das Polling für dich. Im SDK verwenden die Wait-Helper standardmäßig ein Intervall von 2 s und akzeptieren pollIntervalMs.
429-Antworten beachten. Bei Rate-Limits mindestens um den Retry-After-Header (oder 30 s, falls nicht vorhanden) zurückoffen.

​
Idempotency-Keys

Jede Create- und Update-Operation unterstützt einen Idempotency-Key. Regeln:
  • Verwende pro logischer Mutation einen stabilen, eindeutigen, deterministischen Key. Gut: create-song-${sourceHash}. Schlecht: eine neue UUID pro Retry.
  • Verwende bei Retries denselben Key erneut. Der Server erkennt das Replay und gibt das ursprüngliche Ergebnis zurück.
  • Keys sind pro Account scoped und laufen nach 24 Stunden ab.
  • Wenn der Server IDEMPOTENT_REPLAY_IN_PROGRESS (HTTP 202) zurückgibt, läuft die ursprüngliche Anfrage noch. Warten und mit demselben Key erneut versuchen.
Beispielmuster: 
const key = `create-${sha256(sourceBytes)}`;

try {
  return await client.projects.create(body, { idempotencyKey: key });
} catch (error) {
  if (error instanceof YoukaRequestError && error.retryable) {
    // Safe to retry with the same key
    return await client.projects.create(body, { idempotencyKey: key });
  }
  throw error;
}
Siehe API idempotency für den vollständigen Vertrag.

​
Fehlerbehebung

Verzweige nach error.code und error.retryable. Die häufigsten Fälle:
CodeUrsacheAktion
INVALID_REQUESTRequest-Body hat die Schema-Validierung nicht bestanden.Payload korrigieren. Kein Retry.
UNAUTHORIZEDFehlender oder ungültiger API-Key.An den Aufrufer weitergeben. Kein Retry.
NOT_FOUNDRessource existiert nicht oder du hast keinen Zugriff.Kein Retry.
CONFLICT (409)Versionskonflikt oder Idempotency-Kollision.Mit demselben Idempotency-Key erneut versuchen.
TOO_MANY_REQUESTS (429)Rate-Limit.Um Retry-After oder 30 s zurückoffen.
INTERNAL_SERVER_ERROR (500)Transienter Serverfehler.Bis zu 3-mal mit Backoff retryen.
IDEMPOTENT_REPLAY_IN_PROGRESS (202)Vorherige Anfrage läuft noch.Warten und mit demselben Key erneut versuchen.
TASK_FAILEDDie asynchrone Aufgabe endete mit einem Fehler.error.task.error an den Aufrufer weitergeben. Kein Retry.
TASK_TIMED_OUTDie asynchrone Aufgabe hat ihr Zeitbudget überschritten.Einmalig erneut versuchen ist sicher.

​
Mutierbare Felder ermitteln

Bevor du Presets mutierst, rufe das Preset-Schema ab, damit das Modell die gültigen Felder und Werttypen kennt: 
# Preset body schema
youka preset schema --json
Für Projekteinstellungen ist es besser, zuerst die aktuellen Projekteinstellungen zu lesen und dann einen minimalen Update-Body über youka project settings <id> --body ... zu senden. Einmal pro Agent-Session abrufen und das Ergebnis cachen.

​
Parallele Agenten

Wenn mehrere Agenten gleichzeitig gegen denselben Account laufen:
  • Scope Idempotency-Keys sowohl auf die Agent-Identität als auch auf die logische Mutation: agent-${agentId}-create-${sourceHash}. Das verhindert, dass der Retry eines Agenten mit einer neuen Anfrage eines anderen kollidiert.
  • Reads unbeschränkt lassen — GET-Requests sind günstig und haben keine Nebenwirkungen.
  • Verwende pro Projekt eine einzelne Queue für POST /projects/{projectId}/exports, wenn du eine geordnete Export-Historie brauchst. Andernfalls können Exports in falscher Reihenfolge ankommen.

​
Wie geht’s weiter