受控测试

公开 API 范围

说明稳定的公开工作流接口与内部应用路径的区别。

设计规则

公开稳定的工作流操作，而非内部应用的原始路由。仅在身份验证、请求 ID、幂等性、速率限制和计费机制稳定后，发布经过筛选的 OpenAPI 协议。

阅读经过筛选的公开 OpenAPI v1 协议。

当前公开 API v1 边界

已批准的测试令牌可试用无扣费报价和测试任务。测试结果列表为空，也不会生成结账 URL。API 密钥和实际付费执行受限；购买套餐不会自动获得开发者访问批准。

功能发现公开且只读。其余列出的操作均需要获批的测试版令牌；仅登录网站或购买付费订阅并不会授予开发者访问权限。

测试版访问获批后，发送 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 — 核对无扣款账目：测试用量显示预留积分和已消耗积分均为零。

POST /api/public/v1/billing/simulations — 测试 scenario: "success" 和 scenario: "provider_failure"，验证预留、确认扣款及释放，且不修改账本。三个确认标志必须全部为真。

{
  "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 — 在用户的三个确认标志全部为真后验证结账交接。预览返回 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