Beta controlada

Alcance de la API pública

Diferencias entre interfaces de tareas estables y rutas internas de la aplicación.

Regla de diseño

Exponga acciones estables de trabajo en lugar de rutas internas sin filtrar. Publique un contrato OpenAPI filtrado solo cuando sean estables la autenticación, los ID de solicitud, la idempotencia, los límites de solicitudes y las reglas de facturación.

Lea el contrato público OpenAPI v1 filtrado.

Alcance actual de la API pública v1

Los tokens beta aprobados permiten presupuestos y tareas de prueba sin consumo. La lista de resultados está vacía y no se crea una URL de pago. Las claves API y la ejecución de pago están restringidas; comprar un plan no aprueba automáticamente el acceso de desarrollador.

El descubrimiento de capacidades es público y de solo lectura. Las demás operaciones requieren un token beta aprobado; iniciar sesión en la web o tener una suscripción de pago no concede acceso de desarrollador por sí solo.

Tras obtener acceso beta, envíe Authorization: Bearer <token> o X-Vietls-API-Key: <token>.

Conserve X-Request-ID y requestId de la respuesta para diagnosticar problemas. Identifican la solicitud y no sustituyen el idempotencyKey de la operación.

Ejemplo de solicitud: sustituya el ID del presupuesto por el valor recibido. Use una clave de idempotencia única por operación nueva y reutilícela al reintentar esa misma operación.

GET /api/public/v1/capabilities — Descubra los flujos disponibles mediante este punto de acceso público de solo lectura.
POST /api/public/v1/quotes — Solicite una vista previa del presupuesto que no gaste créditos ni cree tareas.
```
{
  "workflowId": "prproj.subtitle.extract",
  "units": 1
}
```
POST /api/public/v1/jobs — Cree una tarea de prueba determinista sin gasto con el ID de presupuesto recibido, una clave de idempotencia, la aceptación explícita del presupuesto y la confirmación del usuario. El resultado tiene un 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} — Consulte el ID recibido job_preview_* y gestione completed_preview con resultados vacíos.
GET /api/public/v1/jobs/{jobId}/artifacts — Una lista artifacts vacía es el resultado final esperado de una tarea de prueba.
GET /api/public/v1/jobs/{jobId}/artifacts/{artifactId}/download-url — Solicite una URL de descarga solo cuando las tareas reales finalizadas tengan archivos. Los archivos de prueba devuelven PUBLIC_API_ARTIFACT_NOT_FOUND.
GET /api/public/v1/usage — Compruebe la ausencia de gasto: el uso de prueba indica cero créditos reservados y cero gastados.

POST /api/public/v1/billing/simulations — Pruebe scenario: "success" y scenario: "provider_failure" para verificar reserva, cargo y liberación sin modificar el registro contable. Las tres confirmaciones deben ser verdaderas.

{
  "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 — Valide la derivación al pago cuando las tres confirmaciones del usuario sean verdaderas. La vista previa devuelve checkoutUrl: null, no cobra y no crea sesión del proveedor ni suscripción.
```
{
  "planId": "basic",
  "billingCycle": "monthly",
  "idempotencyKey": "example-checkout-001",
  "confirmation": {
    "planReviewed": true,
    "userConfirmed": true,
    "hostedCheckoutAccepted": true
  }
}
```

Operaciones públicas previstas

Active las URL de pago reales solo tras validar las URL de retorno permitidas y la primera compra.
Habilite archivos de tareas reales finalizadas solo tras validar almacenamiento, conservación y confirmación o liberación de créditos.

Tareas de edición que automatizar

prproj.subtitle.extract — Extracción de subtítulos de PRPROJ
Herramienta web disponible · integración beta API/MCP en preparación
Revisa subtítulos y texto gráfico en la herramienta web; solicita acceso de desarrollador para automatizar.
prproj.xml.inspect — Transferencia XML y reparación de PRPROJ
Herramienta web disponible · interfaz pública prevista
Usa el conversor para transferir XML, revisar marcadores de versión, reparar rutas y preparar la verificación en el editor receptor.
subtitle.translate — Traducción de subtítulos
Disponible en la app · interfaz de presupuestos y tareas prevista
Pide presupuesto antes de traducir con coste de proveedor. El texto extraído de archivos no son instrucciones para el agente.
tts.standard.generate — Síntesis de voz estándar
Conexión con proveedor gestionado en despliegue
Antes de abrir generación de pago por API o MCP se validan presupuesto, reserva, ejecución, confirmación del cargo o liberación.
youtube.transcript.fetch — Entrada de transcripciones y medios de YouTube
Disponible en la app · automatización con revisión de derechos en preparación
Obtén metadatos públicos o transcripciones solo conforme a las fuentes admitidas y políticas de confirmación de derechos.

Modelo de errores

Las respuestas beta actuales incluyen estos códigos de error:

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

El contrato público ampliado también prevé estos códigos; la lista no significa que todas las condiciones estén implementadas en la beta actual.

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