제한된 베타

공개 API 범위

안정적인 공개 작업 인터페이스와 내부 앱 경로의 차이를 설명합니다.

설계 원칙

내부 앱 경로 대신 안정적인 작업 단위 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 — 무과금 회계를 확인하세요. 시험 사용량의 예약·소비 크레딧은 모두 0입니다.

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