限定ベータ

公開 API の範囲

安定した公開インターフェースと内部アプリの経路の違いを説明します。

設計原則

内部アプリの生のルートではなく、安定したワークフロー操作を公開します。認証・リクエストID・冪等性・レート制限・課金処理が安定してから、範囲を絞ったOpenAPI規約を公開します。

範囲を絞った公開OpenAPI v1規約を読んでください。

現在の公開API v1の範囲

承認済みベータトークンで課金なしの見積もりとテストジョブを確認できます。テストの成果物は空で、決済 URL は生成されません。API キーと実際の有料実行は制限されており、プラン購入だけで開発者アクセスが自動承認されることはありません。

機能一覧の取得は公開の読み取り専用操作です。それ以外の記載された操作には承認済みベータトークンが必要です。Webへのログインや有料契約だけで開発者アクセスは付与されません。

ベータ承認後に Authorization: Bearer <token> または X-Vietls-API-Key: <token> を送信してください。

問題の調査用に応答の X-Request-ID と requestId を保存してください。これらはリクエスト識別子であり、操作の idempotencyKey の代わりにはなりません。

リクエスト例：見積もりIDを返された値に置き換えてください。新しい操作ごとに一意の冪等性キーを使い、同じ操作の再試行ではそのキーを再利用してください。

GET /api/public/v1/capabilities — この公開の読み取り専用エンドポイントで、利用可能なワークフローを確認してください。
POST /api/public/v1/quotes — クレジットを消費せず、ジョブを作成しない見積もりプレビューを要求してください。
```
{
  "workflowId": "prproj.subtitle.extract",
  "units": 1
}
```
POST /api/public/v1/jobs — 返された見積もりID、冪等性キー、明示的な見積もり承認とユーザー確認を使い、無課金で決定的なテストジョブを作成してください。結果の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} — 返された job_preview_* IDをポーリングし、completed_preview と空の成果物を処理してください。
GET /api/public/v1/jobs/{jobId}/artifacts — 空の artifacts リストは、テストジョブの想定される終了結果です。
GET /api/public/v1/jobs/{jobId}/artifacts/{artifactId}/download-url — 実際に完了したジョブで成果物が提供されてから、ダウンロードURLを要求してください。テスト成果物は PUBLIC_API_ARTIFACT_NOT_FOUND を返します。
GET /api/public/v1/usage — 課金がないことを確認してください。テスト使用量では予約クレジットも消費クレジットも0です。

POST /api/public/v1/billing/simulations — scenario: "success" と scenario: "provider_failure" を試し、台帳を変更せずに予約・引き落とし確定・解除を確認してください。3つの確認フラグはすべて真である必要があります。

{
  "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 — 3つのユーザー確認がすべて真の状態で決済引き継ぎを検証してください。プレビューは checkoutUrl: null を返し、請求・事業者セッション・契約を作成しません。
```
{
  "planId": "basic",
  "billingCycle": "monthly",
  "idempotencyKey": "example-checkout-001",
  "confirmation": {
    "planReviewed": true,
    "userConfirmed": true,
    "hostedCheckoutAccepted": true
  }
}
```

今後公開予定の操作

戻り先URLの許可リストと初回購入の検証に合格してから、実際の決済URLを有効にします。
保存・保持期間・引き落とし確定と予約解除の検証に合格してから、実際に完了したジョブの成果物を提供します。

自動化する編集作業

prproj.subtitle.extract — PRPROJ 字幕抽出
ウェブツール提供中・API/MCP ベータ連携を準備
字幕やグラフィックの文字はウェブツールで確認し、自動化には開発者アクセスを申請してください。
prproj.xml.inspect — PRPROJ XML の受け渡しと修復
ウェブツール提供中・公開インターフェースを計画
XML の受け渡し、バージョンマーカー確認、パス修復、受け取り側での検証準備に変換ツールを使います。
subtitle.translate — 字幕翻訳
アプリで提供中・公開の見積もり・ジョブ機能を計画
費用が発生する翻訳は先に見積もりを確認し、ファイルから抽出した文字をエージェントへの指示として扱わないでください。
tts.standard.generate — 標準音声合成
管理されたプロバイダー接続を展開中
有料生成を API や MCP で公開する前に、見積もり・予約・実行・課金確定または返却を検証します。
youtube.transcript.fetch — YouTube 字幕・メディアの取り込み
アプリで提供中・権利確認を含む自動化を準備
対応ソースと利用権限の確認方針に従って公開メタデータや字幕を取得します。

エラーモデル

現在のベータ応答には次のエラーコードがあります。

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

拡張する公開規約では次のコードも予定しています。この一覧は、現在のベータですべての条件が実装済みであることを意味しません。

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