मुख्य सामग्री पर जाएं
Youka को एजेंट्स द्वारा संचालित किए जाने के लिए डिज़ाइन किया गया है। हर CLI कमांड एक मशीन-पठनीय JSON एन्वेलप लौटाता है, हर write idempotency keys को सपोर्ट करता है, और public API वही surface और वही semantics एक्सपोज़ करता है। यह पेज उन ऑपरेटिंग नियमों को संकलित करता है जिनकी एक एजेंट लेखक को Youka को किसी वर्कफ़्लो में जोड़ने से पहले ज़रूरत होती है।

​
शुरुआत करें

यदि आप पहली बार कोई एजेंट सेट अप कर रहे हैं, तो पहले Youka CLI इंस्टॉल करें, फिर Youka karaoke skill इंस्टॉल करें: 
npm install -g @youka/cli
npx skills add https://github.com/youka-io/skills --skill youka-karaoke
इससे एजेंट को CLI द्वारा समर्थित एक तैयार-उपयोग Youka skill मिल जाता है। इंस्टॉल होने के बाद, नीचे दिए गए वर्कफ़्लो पैटर्न का उपयोग करके karaoke वीडियो बनाएं, स्टाइल कस्टमाइज़ करें, और MP4 फ़ाइलें सुरक्षित रूप से एक्सपोर्ट करें।

​
अपने एजेंट को प्रॉम्प्ट करें

CLI और skill इंस्टॉल करने के बाद, आप अपने एजेंट को इस तरह सीधा कार्य दे सकते हैं: 
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.

​
ऑपरेटिंग नियम

हमेशा --json इस्तेमाल करें

CLI पर हमेशा --json पास करें। API में हमेशा Accept: application/json सेट करें। कभी भी human output को parse न करें।

हमेशा idempotency key भेजें

हर write के साथ एक स्थिर idempotency key होनी चाहिए, ताकि timeout के बाद retries मूल परिणाम लौटाएं और काम डुप्लिकेट न हो।

टिकाऊ state को फिर से पढ़ें

stale mutation responses पर भरोसा न करें। किसी terminal task के बाद, final state पाने के लिए project या export को फिर से read करें।

backoff के साथ poll करें

2–3 सेकंड के interval से शुरू करें। लंबी jobs के लिए exponentially back off करें। 429 responses का सम्मान करें।

​
Output contract

--json मोड में हर CLI कमांड stdout पर ठीक एक envelope लिखता है। Success: 
{
  "schemaVersion": "1",
  "ok": true,
  "data": { "id": "prj_abc123", "title": "My Song" }
}
Failure: 
{
  "schemaVersion": "1",
  "ok": false,
  "error": {
    "code": "CONFLICT",
    "message": "A request with this Idempotency-Key is already in progress.",
    "retryable": true
  }
}
Exit codes:
Codeअर्थRetry?
0Success.N/A
1Runtime error (network, API, rendering).error.retryable जाँचें।
2Invalid input (bad flags, unreadable payload).नहीं — input ठीक करें।

​
एंड-टू-एंड वर्कफ़्लो

कैनॉनिकल एजेंट वर्कफ़्लो है: एक प्रोजेक्ट बनाएं, प्रतीक्षा करें, एक्सपोर्ट करें, परिणाम डाउनलोड करें। यहाँ CLI और SDK दोनों implementations के साथ पूरा पैटर्न है। 
# 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 मार्गदर्शन

SDK में अधिकांश writes operation handles लौटाते हैं। client.projects.wait(...) और client.exports.wait(...) को प्राथमिकता दें, और client.tasks.* पर तभी जाएँ जब आपको स्पष्ट रूप से low-level task access की ज़रूरत हो।
Job typeRecommended initial intervalMax wait
Project create (stems + lyrics sync)3 s15 min
Stem separation only3 s10 min
Lyrics sync only2 s5 min
Export render3 s30 min
CLI पर, --wait आपके लिए polling संभालता है। SDK पर, wait helpers डिफ़ॉल्ट रूप से 2 s interval उपयोग करते हैं और pollIntervalMs स्वीकार करते हैं।
429 responses का सम्मान करें। rate limits पर, कम से कम Retry-After header जितना (या अनुपस्थित होने पर 30 s) back off करें।

​
Idempotency keys

हर create और update operation एक idempotency key सपोर्ट करता है। नियम:
  • हर logical mutation के लिए stable, unique, deterministic key इस्तेमाल करें। अच्छा: create-song-${sourceHash}। खराब: हर retry पर नया UUID।
  • retries के दौरान उसी key का पुन: उपयोग करें। सर्वर replay पहचानकर मूल परिणाम लौटाता है।
  • keys per-account scoped होती हैं और 24 घंटे बाद expire हो जाती हैं।
  • यदि सर्वर IDEMPOTENT_REPLAY_IN_PROGRESS (HTTP 202) लौटाए, तो original request अभी भी चल रही है। प्रतीक्षा करें और उसी key के साथ retry करें।
Example pattern: 
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;
}
पूरा contract देखने के लिए API idempotency देखें।

​
Error recovery

error.code और error.retryable के आधार पर branch करें। सामान्य केस:
CodeकारणAction
INVALID_REQUESTRequest body schema validation में fail हुआ।payload ठीक करें। retry नहीं।
UNAUTHORIZEDAPI key missing या invalid।caller तक surface करें। retry नहीं।
NOT_FOUNDresource मौजूद नहीं है या आपके पास access नहीं है।retry नहीं।
CONFLICT (409)version conflict या idempotency collision।उसी idempotency key के साथ retry करें।
TOO_MANY_REQUESTS (429)rate limit।Retry-After या 30 s के अनुसार back off करें।
INTERNAL_SERVER_ERROR (500)transient server failure।backoff के साथ 3 बार तक retry करें।
IDEMPOTENT_REPLAY_IN_PROGRESS (202)prior request अभी भी चल रही है।प्रतीक्षा करें और उसी key के साथ retry करें।
TASK_FAILEDasync task failure में समाप्त हुई।error.task.error को caller तक surface करें। retry नहीं।
TASK_TIMED_OUTasync task ने अपना budget पार कर लिया।एक बार retry करना सुरक्षित है।

​
Mutable fields की खोज

presets को mutate करने से पहले, preset schema fetch करें ताकि मॉडल valid fields और value types जान सके: 
# Preset body schema
youka preset schema --json
project settings के लिए, पहले current project settings पढ़ना बेहतर है, फिर youka project settings <id> --body ... के जरिए minimal update body सबमिट करें। प्रति agent session एक बार fetch करें और परिणाम cache करें।

​
Parallel agents

जब एक ही account के खिलाफ कई agents concurrently चल रहे हों:
  • idempotency keys को agent identity और logical mutation — दोनों के अनुसार scope करें: agent-${agentId}-create-${sourceHash}। इससे एक agent का retry किसी दूसरे agent की fresh request से collide नहीं करेगा।
  • reads को unbounded रखें — GET requests सस्ते होते हैं और उनके कोई side effects नहीं होते।
  • यदि आपको ordered export history चाहिए, तो प्रति project POST /projects/{projectId}/exports के लिए single queue इस्तेमाल करें। अन्यथा exports out of order आ सकते हैं।

​
आगे क्या