Chuyển đến nội dung chính
Youka được thiết kế để được điều khiển bởi các tác nhân. Mọi lệnh CLI đều trả về một phong bì JSON có thể đọc bằng máy, mọi thao tác ghi đều hỗ trợ khóa idempotency, và API công khai cung cấp cùng bề mặt với cùng ngữ nghĩa. Trang này tổng hợp các quy tắc vận hành mà tác giả tác nhân cần biết trước khi kết nối Youka vào một quy trình làm việc.

​
Bắt đầu

Nếu bạn đang thiết lập một tác nhân lần đầu, hãy cài Youka CLI trước, sau đó cài kỹ năng Youka karaoke: 
npm install -g @youka/cli
npx skills add https://github.com/youka-io/skills --skill youka-karaoke
Việc này cung cấp cho tác nhân một kỹ năng Youka có sẵn được hậu thuẫn bởi CLI. Khi đã cài xong, hãy dùng các mẫu quy trình bên dưới để tạo video karaoke, tùy biến phong cách, và xuất tệp MP4 một cách an toàn.

​
Nhắc lệnh cho tác nhân

Sau khi cài CLI và skill, bạn có thể giao cho tác nhân một nhiệm vụ trực tiếp như sau: 
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.

​
Quy tắc vận hành

Luôn dùng --json

Trên CLI, luôn truyền --json. Trên API, luôn đặt Accept: application/json. Không bao giờ phân tích đầu ra dành cho con người.

Luôn gửi một khóa idempotency

Mọi thao tác ghi nên mang một khóa idempotency ổn định để việc thử lại sau khi timeout trả về kết quả ban đầu thay vì nhân đôi công việc.

Đọc lại trạng thái bền vững

Đừng tin phản hồi đột biến đã cũ. Sau một tác vụ kết thúc, hãy đọc lại project hoặc export để lấy trạng thái cuối cùng.

Poll với backoff

Bắt đầu với khoảng 2–3 giây. Tăng giãn cách theo cấp số nhân cho các job dài. Tôn trọng phản hồi 429.

​
Hợp đồng đầu ra

Mọi lệnh CLI ở chế độ --json ghi chính xác một phong bì ra stdout. Thành công: 
{
  "schemaVersion": "1",
  "ok": true,
  "data": { "id": "prj_abc123", "title": "My Song" }
}
Thất bại: 
{
  "schemaVersion": "1",
  "ok": false,
  "error": {
    "code": "CONFLICT",
    "message": "A request with this Idempotency-Key is already in progress.",
    "retryable": true
  }
}
Mã thoát:
CodeMeaningRetry?
0Thành công.N/A
1Lỗi thời gian chạy (network, API, rendering).Kiểm tra error.retryable.
2Đầu vào không hợp lệ (flag sai, payload không đọc được).Không — sửa đầu vào.

​
Quy trình end-to-end

Quy trình chuẩn cho tác nhân là: tạo project, đợi, export, tải xuống kết quả. Đây là mẫu đầy đủ với cả triển khai CLI và SDK. 
# 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')"

​
Hướng dẫn polling

Hầu hết các thao tác ghi trả về operation handles trong SDK. Ưu tiên client.projects.wait(...) và client.exports.wait(...), và chỉ hạ xuống client.tasks.* khi bạn thực sự cần truy cập task mức thấp.
Job typeRecommended initial intervalMax wait
Tạo project (stems + đồng bộ lyrics)3 s15 min
Chỉ tách stem3 s10 min
Chỉ đồng bộ lyrics2 s5 min
Render export3 s30 min
Trên CLI, --wait sẽ xử lý polling cho bạn. Trên SDK, các helper wait dùng khoảng 2 s theo mặc định và chấp nhận pollIntervalMs.
Tôn trọng phản hồi 429. Khi bị rate limit, hãy back off ít nhất theo header Retry-After (hoặc 30 s nếu không có).

​
Khóa idempotency

Mọi thao tác create và update đều hỗ trợ một khóa idempotency. Quy tắc:
  • Dùng một khóa ổn định, duy nhất, mang tính quyết định cho mỗi đột biến logic. Tốt: create-song-${sourceHash}. Không tốt: một UUID mới cho mỗi lần retry.
  • Tái sử dụng cùng khóa qua các lần retry. Server nhận ra việc phát lại và trả về kết quả ban đầu.
  • Khóa có phạm vi theo từng tài khoản và hết hạn sau 24 giờ.
  • Nếu server trả về IDEMPOTENT_REPLAY_IN_PROGRESS (HTTP 202), request ban đầu vẫn đang chạy. Hãy đợi và retry với cùng khóa.
Mẫu ví dụ: 
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;
}
Xem API idempotency để biết hợp đồng đầy đủ.

​
Khôi phục lỗi

Rẽ nhánh theo error.code và error.retryable. Các trường hợp phổ biến:
CodeCauseAction
INVALID_REQUESTRequest body không vượt qua xác thực schema.Sửa payload. Không retry.
UNAUTHORIZEDThiếu hoặc API key không hợp lệ.Hiển thị cho người gọi. Không retry.
NOT_FOUNDTài nguyên không tồn tại hoặc bạn không có quyền truy cập.Không retry.
CONFLICT (409)Xung đột phiên bản hoặc va chạm idempotency.Retry với cùng khóa idempotency.
TOO_MANY_REQUESTS (429)Rate limit.Back off theo Retry-After hoặc 30 s.
INTERNAL_SERVER_ERROR (500)Lỗi máy chủ tạm thời.Retry tối đa 3 lần với backoff.
IDEMPOTENT_REPLAY_IN_PROGRESS (202)Request trước vẫn đang chạy.Đợi và retry với cùng khóa.
TASK_FAILEDTask async kết thúc thất bại.Hiển thị error.task.error cho người gọi. Không retry.
TASK_TIMED_OUTTask async vượt quá ngân sách thời gian.Có thể retry an toàn một lần.

​
Khám phá các trường có thể thay đổi

Trước khi mutate preset, hãy fetch schema của preset để mô hình biết các field hợp lệ và kiểu giá trị: 
# Preset body schema
youka preset schema --json
Đối với project settings, ưu tiên đọc project settings hiện tại trước, sau đó gửi một body cập nhật tối thiểu qua youka project settings <id> --body .... Fetch một lần cho mỗi phiên tác nhân và cache kết quả.

​
Tác nhân song song

Khi nhiều tác nhân chạy đồng thời trên cùng một tài khoản:
  • Giới hạn phạm vi khóa idempotency theo cả danh tính tác nhân và đột biến logic: agent-${agentId}-create-${sourceHash}. Điều này ngăn retry của một tác nhân va chạm với request mới của tác nhân khác.
  • Giữ các thao tác đọc không bị ràng buộc — các request GET rẻ và không có tác dụng phụ.
  • Dùng một hàng đợi duy nhất cho POST /projects/{projectId}/exports theo từng project nếu bạn cần lịch sử export theo thứ tự. Nếu không, các export có thể đến không theo thứ tự.

​
Tiếp theo