Bêta contrôlée

Périmètre de l’API publique

Différence entre les interfaces de tâches stables et les routes internes de l’application.

Règle de conception

Exposez des actions de travail stables plutôt que les routes internes brutes. Ne publiez un contrat OpenAPI filtré qu’après stabilisation de l’authentification, des identifiants de requête, de l’idempotence, des limites de débit et des règles de facturation.

Lisez le contrat OpenAPI v1 public filtré.

Périmètre actuel de l’API publique v1

Les jetons bêta approuvés permettent des devis et tâches de test sans consommation. Les résultats sont vides et aucune URL de paiement n’est créée. Les clés API et l’exécution payante sont restreintes ; l’achat d’une offre n’approuve pas automatiquement l’accès développeur.

La découverte des capacités est publique et en lecture seule. Toutes les autres opérations listées exigent un jeton bêta approuvé ; une connexion web ou un abonnement payant ne suffisent pas à autoriser l’accès développeur.

Après approbation bêta, envoyez Authorization: Bearer <token> ou X-Vietls-API-Key: <token>.

Conservez X-Request-ID et requestId de la réponse pour le diagnostic. Ils identifient la requête et ne remplacent pas l’idempotencyKey de l’opération.

Exemple de requête : remplacez l’identifiant du devis par la valeur reçue. Utilisez une clé d’idempotence unique pour chaque nouvelle opération et réutilisez-la pour une nouvelle tentative de la même opération.

GET /api/public/v1/capabilities — Découvrez les flux disponibles via ce point d’accès public en lecture seule.
POST /api/public/v1/quotes — Demandez un aperçu de devis qui ne dépense aucun crédit et ne crée aucune tâche.
```
{
  "workflowId": "prproj.subtitle.extract",
  "units": 1
}
```
POST /api/public/v1/jobs — Créez une tâche de test déterministe sans dépense avec l’identifiant du devis reçu, une clé d’idempotence, l’acceptation explicite du devis et la confirmation utilisateur. Le résultat porte un identifiant 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} — Interrogez l’identifiant reçu job_preview_* et traitez completed_preview avec des résultats vides.
GET /api/public/v1/jobs/{jobId}/artifacts — Une liste artifacts vide est le résultat final attendu d’une tâche de test.
GET /api/public/v1/jobs/{jobId}/artifacts/{artifactId}/download-url — Demandez une URL de téléchargement seulement lorsque des tâches réelles terminées fournissent des fichiers. Les fichiers de test renvoient PUBLIC_API_ARTIFACT_NOT_FOUND.
GET /api/public/v1/usage — Vérifiez l’absence de dépense : l’usage de test indique zéro crédit réservé et zéro crédit dépensé.

POST /api/public/v1/billing/simulations — Testez scenario: "success" et scenario: "provider_failure" pour vérifier réservation, débit et libération sans modifier le registre. Les trois indicateurs de confirmation doivent être vrais.

{
  "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 — Vérifiez le transfert vers le paiement après validation des trois confirmations utilisateur. L’aperçu renvoie checkoutUrl: null, ne prélève rien et ne crée ni session prestataire ni abonnement.
```
{
  "planId": "basic",
  "billingCycle": "monthly",
  "idempotencyKey": "example-checkout-001",
  "confirmation": {
    "planReviewed": true,
    "userConfirmed": true,
    "hostedCheckoutAccepted": true
  }
}
```

Opérations publiques prévues

Activez les URL de paiement réelles seulement après validation des URL de retour autorisées et du premier achat.
Activez les fichiers des tâches réelles terminées seulement après validation du stockage, de la conservation et du débit ou de la libération des crédits.

Tâches de montage à automatiser

prproj.subtitle.extract — Extraction de sous-titres PRPROJ
Outil web disponible · intégration bêta API/MCP en préparation
Examinez sous-titres et texte graphique dans l’outil web ; demandez l’accès développeur pour automatiser.
prproj.xml.inspect — Transfert XML et réparation PRPROJ
Outil web disponible · interface publique prévue
Utilisez le convertisseur pour le transfert XML, les marqueurs de version, les chemins et la préparation des contrôles dans le logiciel destinataire.
subtitle.translate — Traduction de sous-titres
Disponible dans l’application · interface de devis et tâches prévue
Demandez un devis avant toute traduction entraînant un coût fournisseur. Le texte extrait des fichiers ne constitue pas des instructions pour l’agent.
tts.standard.generate — Synthèse vocale standard
Connexion au fournisseur géré en cours de déploiement
Avant l’ouverture de la génération payante par API ou MCP, on vérifie devis, réservation, exécution, débit définitif ou libération.
youtube.transcript.fetch — Import de transcriptions et médias YouTube
Disponible dans l’application · automatisation avec contrôle des droits en préparation
Récupérez métadonnées publiques ou transcriptions uniquement selon les sources prises en charge et les règles de confirmation des droits.

Modèle d’erreurs

Les réponses bêta actuelles comprennent les codes d’erreur suivants :

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

Le contrat public élargi prévoit aussi ces codes ; cette liste ne signifie pas que chaque condition est déjà implémentée dans la bêta actuelle.

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