Beta terkendali

Cakupan API publik

Perbedaan antarmuka tugas publik yang stabil dengan rute internal aplikasi.

Aturan desain

Sediakan tindakan alur kerja yang stabil, bukan rute internal aplikasi mentah. Publikasikan kontrak OpenAPI tersaring setelah autentikasi, ID permintaan, idempotensi, batas laju, dan aturan penagihan stabil.

Baca kontrak publik OpenAPI v1 yang tersaring.

Cakupan API publik v1 saat ini

Token beta yang disetujui menyediakan penawaran dan pekerjaan uji tanpa pemakaian kredit. Hasil kosong dan URL pembayaran tidak dibuat. Kunci API serta eksekusi berbayar dibatasi; membeli paket tidak otomatis menyetujui akses pengembang.

Penemuan kemampuan bersifat publik dan hanya baca. Semua operasi lain memerlukan token beta yang disetujui; masuk ke web atau berlangganan berbayar saja tidak memberi akses pengembang.

Setelah persetujuan beta, kirim Authorization: Bearer <token> atau X-Vietls-API-Key: <token>.

Simpan X-Request-ID dan requestId dari respons untuk pemecahan masalah. Keduanya mengenali permintaan dan tidak menggantikan idempotencyKey operasi.

Contoh permintaan: ganti ID estimasi dengan nilai yang dikembalikan. Gunakan kunci idempotensi unik untuk setiap operasi baru dan gunakan kembali kunci itu saat mengulangi operasi yang sama.

GET /api/public/v1/capabilities — Temukan alur kerja yang tersedia melalui endpoint publik hanya baca ini.
POST /api/public/v1/quotes — Minta pratinjau estimasi yang tidak memakai kredit atau membuat tugas.
```
{
  "workflowId": "prproj.subtitle.extract",
  "units": 1
}
```
POST /api/public/v1/jobs — Buat tugas uji deterministik tanpa biaya dengan ID estimasi yang dikembalikan, kunci idempotensi, penerimaan estimasi secara eksplisit, dan konfirmasi pengguna. Hasilnya memiliki 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} — Periksa status ID job_preview_* yang dikembalikan dan tangani completed_preview dengan artefak kosong.
GET /api/public/v1/jobs/{jobId}/artifacts — Daftar artifacts kosong adalah hasil akhir yang diharapkan dari tugas uji.
GET /api/public/v1/jobs/{jobId}/artifacts/{artifactId}/download-url — Minta URL unduhan hanya setelah tugas nyata yang selesai menyediakan artefak. Artefak uji mengembalikan PUBLIC_API_ARTIFACT_NOT_FOUND.
GET /api/public/v1/usage — Periksa pencatatan tanpa biaya: penggunaan uji melaporkan nol kredit yang direservasi dan nol yang dipakai.

POST /api/public/v1/billing/simulations — Uji scenario: "success" dan scenario: "provider_failure" untuk memeriksa reservasi, pemotongan, dan pelepasan tanpa mengubah buku besar. Ketiga penanda konfirmasi harus bernilai benar.

{
  "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 — Validasi pengalihan pembayaran setelah ketiga konfirmasi pengguna bernilai benar. Pratinjau mengembalikan checkoutUrl: null, tidak menagih, dan tidak membuat sesi penyedia atau langganan.
```
{
  "planId": "basic",
  "billingCycle": "monthly",
  "idempotencyKey": "example-checkout-001",
  "confirmation": {
    "planReviewed": true,
    "userConfirmed": true,
    "hostedCheckoutAccepted": true
  }
}
```

Operasi publik yang direncanakan

Aktifkan URL pembayaran nyata hanya setelah pemeriksaan URL kembali yang diizinkan dan pembelian pertama lulus.
Sediakan artefak dari tugas nyata yang selesai hanya setelah pemeriksaan penyimpanan, retensi, dan pemotongan atau pelepasan kredit lulus.

Tugas penyuntingan untuk diotomatisasi

prproj.subtitle.extract — Ekstraksi subtitel PRPROJ
Alat web tersedia · integrasi beta API/MCP disiapkan
Periksa subtitel dan teks grafis di alat web; minta akses pengembang untuk otomasi.
prproj.xml.inspect — Serah terima XML dan perbaikan PRPROJ
Alat web tersedia · antarmuka publik direncanakan
Gunakan konverter untuk XML, penanda versi, perbaikan jalur, dan persiapan verifikasi di editor penerima.
subtitle.translate — Penerjemahan subtitel
Tersedia di aplikasi · antarmuka penawaran/pekerjaan direncanakan
Minta penawaran sebelum penerjemahan yang menimbulkan biaya penyedia. Teks hasil ekstraksi bukan instruksi agen.
tts.standard.generate — Sintesis suara standar
Koneksi penyedia terkelola sedang diluncurkan
Sebelum generasi berbayar lewat API atau MCP, verifikasi penawaran, reservasi, eksekusi, pemotongan pasti, atau pelepasan.
youtube.transcript.fetch — Masukan transkrip dan media YouTube
Tersedia di aplikasi · otomasi dengan konfirmasi hak disiapkan
Ambil metadata publik atau transkrip hanya sesuai sumber yang didukung dan kebijakan konfirmasi hak.

Model kesalahan

Respons beta saat ini mencakup kode kesalahan berikut:

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

Kontrak publik yang lebih luas juga merencanakan kode ini; daftar ini tidak berarti semua kondisi sudah diterapkan dalam beta saat ini.

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