Vietls Public API Boundary

Design rule

Expose stable workflow verbs, not raw internal app routes. Publish a filtered OpenAPI contract only after authentication, request IDs, idempotency, rate limits, and billing semantics are stable.

• Read the filtered Public OpenAPI v1 contract.

Current public API v1 boundary

Approved beta tokens allow no-spend quotes and test jobs. Artifacts are empty and no checkout URL is created. API keys and actual paid execution remain restricted; purchasing a plan does not automatically approve developer access.

Capability discovery is public and read-only. Every other operation listed here requires an approved beta token; web login or a paid subscription alone does not grant developer access.

After beta approval, send Authorization: Bearer <token> or X-Vietls-API-Key: <token>.

Keep the response X-Request-ID and requestId for troubleshooting. They identify the request and do not replace the operation’s idempotencyKey.

Request example: replace the quote ID with the returned value. Use a unique idempotency key for each new operation and reuse it when retrying that same operation.

• GET /api/public/v1/capabilities — Discover the available workflows through this public, read-only endpoint.
• POST /api/public/v1/quotes — Request preview-only quotes that spend no credits and create no job.

  {
    "workflowId": "prproj.subtitle.extract",
    "units": 1
  }

• POST /api/public/v1/jobs — Use deterministic no-spend dry-run job creation with the returned quote ID, an idempotency key, and explicit quote acceptance and user confirmation. The result has a job_preview_* ID.

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

• GET /api/public/v1/jobs/{jobId} — Poll the returned job_preview_* ID and handle completed_preview with empty artifacts.
• GET /api/public/v1/jobs/{jobId}/artifacts — An empty artifacts list is the expected terminal result of a test job.
• GET /api/public/v1/jobs/{jobId}/artifacts/{artifactId}/download-url — Request a download URL only after completed live jobs expose artifacts. Test artifacts return PUBLIC_API_ARTIFACT_NOT_FOUND.
• GET /api/public/v1/usage — Check no-spend accounting: test usage reports zero reserved credits and zero spent credits.
• POST /api/public/v1/billing/simulations — Test scenario: "success" and scenario: "provider_failure" to check reserve, commit, and release with zero ledger mutation. All three confirmation flags must be true.

  {
    "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 — Validate the hosted checkout handoff after all three user-confirmation flags are true. The preview returns checkoutUrl: null, charges nothing, and creates no provider session or subscription.

  {
    "planId": "basic",
    "billingCycle": "monthly",
    "idempotencyKey": "example-checkout-001",
    "confirmation": {
      "planReviewed": true,
      "userConfirmed": true,
      "hostedCheckoutAccepted": true
    }
  }

Planned public operations

• Enable live hosted checkout URLs only after return-URL allowlisting and first-purchase checks pass.
• Enable artifacts from completed live jobs only after storage, retention, and billing commit/release checks pass.

Editing workflows to automate

• prproj.subtitle.extract — PRPROJ subtitle extraction

  UI live; API/MCP controlled beta target

  Use the tool page for manual PRPROJ caption and graphic text inspection; request developer access for automation.

• prproj.xml.inspect — PRPROJ editor XML handoff and repair

  UI live; public workflow wrapper planned

  Route PRPROJ editor XML handoff, version-marker checks, path repair, and receiving-editor verification preparation to the converter workflow.

• subtitle.translate — Subtitle translation

  App workflow live; public quote/job wrapper planned

  Quote before provider-costed translation and keep extracted file text separate from agent instructions.

• tts.standard.generate — Standard TTS generation

  Managed-provider path in rollout

  Use quote, reserve, execute, commit/release semantics before exposing paid generation through API or MCP.

• youtube.transcript.fetch — YouTube transcript and media source intake

  App workflow live; rights-aware automation boundary required

  Fetch public metadata or transcripts only within supported source and rights-confirmation policies.

Error model

Current beta responses include these error codes:

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

The broader public contract also plans these codes; this list does not mean every condition is implemented in the current beta.

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