Beta có kiểm soát

Phạm vi API công khai

Khác biệt giữa giao diện tác vụ công khai ổn định và đường dẫn nội bộ của ứng dụng.

Quy tắc thiết kế

Công khai thao tác quy trình ổn định thay vì đường dẫn nội bộ thô của ứng dụng. Chỉ công bố hợp đồng OpenAPI đã lọc sau khi xác thực, ID yêu cầu, tính lũy đẳng, giới hạn tần suất và quy tắc tính phí ổn định.

Đọc hợp đồng OpenAPI v1 công khai đã lọc.

Phạm vi API công khai v1 hiện tại

Token beta được duyệt cho phép báo giá và tác vụ thử không tiêu hao tín dụng. Danh sách kết quả rỗng và không tạo URL thanh toán. Khóa API cùng thực thi trả phí bị giới hạn; mua gói không tự động duyệt quyền nhà phát triển.

Khám phá khả năng là công khai và chỉ đọc. Mọi thao tác khác trong danh sách đều cần mã beta được duyệt; đăng nhập web hay có gói trả phí không tự cấp quyền truy cập nhà phát triển.

Sau khi được duyệt beta, gửi Authorization: Bearer <token> hoặc X-Vietls-API-Key: <token>.

Giữ X-Request-ID và requestId trong phản hồi để chẩn đoán. Chúng định danh yêu cầu và không thay thế idempotencyKey của thao tác.

Ví dụ yêu cầu: thay ID báo giá bằng giá trị trả về. Dùng khóa lũy đẳng riêng cho mỗi thao tác mới và dùng lại khóa đó khi thử lại cùng thao tác.

GET /api/public/v1/capabilities — Khám phá quy trình có sẵn qua điểm cuối công khai chỉ đọc này.
POST /api/public/v1/quotes — Yêu cầu bản xem trước báo giá không tiêu tín dụng và không tạo tác vụ.
```
{
  "workflowId": "prproj.subtitle.extract",
  "units": 1
}
```
POST /api/public/v1/jobs — Tạo tác vụ thử có kết quả xác định, không tiêu tín dụng bằng ID báo giá trả về, khóa lũy đẳng, chấp nhận báo giá rõ ràng và xác nhận người dùng. Kết quả có ID job_preview_*.
```
{
  "workflowId": "prproj.subtitle.extract",
  "quoteId": "quote_preview_01234567",
  "idempotencyKey": "example-job-001",
  "confirmation": {
    "quoteAccepted": true,
    "userConfirmed": true
  }
}
```
GET /api/public/v1/jobs/{jobId} — Kiểm tra ID job_preview_* trả về và xử lý completed_preview với kết quả rỗng.
GET /api/public/v1/jobs/{jobId}/artifacts — Danh sách artifacts rỗng là kết quả cuối dự kiến của tác vụ thử.
GET /api/public/v1/jobs/{jobId}/artifacts/{artifactId}/download-url — Chỉ yêu cầu URL tải xuống khi tác vụ thật đã hoàn tất cung cấp tệp. Tệp thử nghiệm trả về PUBLIC_API_ARTIFACT_NOT_FOUND.
GET /api/public/v1/usage — Kiểm tra không phát sinh chi phí: mức dùng thử báo tín dụng giữ chỗ và đã tiêu đều bằng không.

POST /api/public/v1/billing/simulations — Thử scenario: "success" và scenario: "provider_failure" để kiểm tra giữ chỗ, chốt trừ và giải phóng mà không sửa sổ ghi nhận. Cả ba cờ xác nhận phải là đúng.

{
  "workflowId": "prproj.subtitle.extract",
  "quoteId": "quote_preview_01234567",
  "idempotencyKey": "example-simulation-001",
  "scenario": "success",
  "confirmation": {
    "quoteAccepted": true,
    "userConfirmed": true,
    "billingSimulationAccepted": true
  }
}

POST /api/public/v1/checkout/handoffs — Kiểm tra chuyển sang thanh toán khi cả ba xác nhận của người dùng là đúng. Bản xem trước trả về checkoutUrl: null, không thu tiền và không tạo phiên nhà cung cấp hay gói đăng ký.
```
{
  "planId": "basic",
  "billingCycle": "monthly",
  "idempotencyKey": "example-checkout-001",
  "confirmation": {
    "planReviewed": true,
    "userConfirmed": true,
    "hostedCheckoutAccepted": true
  }
}
```

Thao tác công khai dự kiến

Chỉ bật URL thanh toán thật sau khi kiểm tra URL quay lại được phép và lần mua đầu tiên đạt yêu cầu.
Chỉ cung cấp tệp của tác vụ thật đã hoàn tất sau khi kiểm tra lưu trữ, thời hạn giữ và chốt trừ hoặc giải phóng tín dụng đạt yêu cầu.

Tác vụ dựng phim để tự động hóa

prproj.subtitle.extract — Trích xuất phụ đề PRPROJ
Công cụ web khả dụng · tích hợp beta API/MCP đang chuẩn bị
Kiểm tra phụ đề và chữ đồ họa trên web; yêu cầu quyền nhà phát triển để tự động hóa.
prproj.xml.inspect — Bàn giao XML và sửa PRPROJ
Công cụ web khả dụng · giao diện công khai dự kiến
Dùng bộ chuyển đổi cho XML, dấu phiên bản, sửa đường dẫn và chuẩn bị xác minh trong trình biên tập nhận.
subtitle.translate — Dịch phụ đề
Có trong ứng dụng · giao diện báo giá/tác vụ dự kiến
Lấy báo giá trước khi dịch phát sinh chi phí nhà cung cấp. Văn bản trích từ tệp không phải chỉ dẫn cho tác nhân.
tts.standard.generate — Tổng hợp giọng nói tiêu chuẩn
Kết nối nhà cung cấp được quản lý đang triển khai
Trước khi mở tạo có phí qua API hoặc MCP, xác minh báo giá, giữ tín dụng, thực thi, chốt trừ hoặc giải phóng.
youtube.transcript.fetch — Nhập bản chép lời và phương tiện YouTube
Có trong ứng dụng · tự động hóa kèm xác nhận quyền đang chuẩn bị
Chỉ lấy siêu dữ liệu công khai hoặc bản chép lời theo nguồn được hỗ trợ và chính sách xác nhận quyền.

Mô hình lỗi

Phản hồi beta hiện tại có các mã lỗi sau:

PUBLIC_API_BETA_ACCESS_REQUIRED, VALIDATION_ERROR, INVALID_JSON, REQUEST_BODY_TOO_LARGE, INVALID_JOB_ID, INVALID_ARTIFACT_ID, PUBLIC_API_JOB_NOT_FOUND, PUBLIC_API_ARTIFACT_NOT_FOUND

Hợp đồng công khai mở rộng cũng dự kiến có các mã này; danh sách không có nghĩa là mọi điều kiện đã được triển khai trong beta hiện tại.

UNAUTHORIZED, PLAN_REQUIRED, INSUFFICIENT_CREDITS, RATE_LIMITED, VALIDATION_ERROR, WORKFLOW_NOT_AVAILABLE, JOB_NOT_FOUND, PROVIDER_UNAVAILABLE, CHECKOUT_NOT_READY