Vai al contenuto principale

Beta controllata

Ambito dell’API pubblica

Differenze tra interfacce pubbliche stabili e percorsi interni dell’applicazione.

Regola di progettazione

Esporre azioni di lavoro stabili anziché percorsi interni grezzi. Pubblicare un contratto OpenAPI filtrato solo dopo aver stabilizzato autenticazione, ID delle richieste, idempotenza, limiti di frequenza e regole di fatturazione.

Ambito attuale dell’API pubblica v1

I token beta approvati consentono preventivi e lavori di prova senza consumo. I risultati sono vuoti e non si crea un URL di pagamento. Chiavi API ed esecuzione a pagamento sono limitate; acquistare un piano non approva automaticamente l’accesso sviluppatore.

Il rilevamento delle capacità è pubblico e di sola lettura. Ogni altra operazione elencata richiede un token beta approvato; l’accesso al sito o un abbonamento a pagamento non concedono da soli l’accesso sviluppatore.

Dopo l’approvazione beta, inviare Authorization: Bearer <token> o X-Vietls-API-Key: <token>.

Conservare X-Request-ID e requestId della risposta per la diagnosi. Identificano la richiesta e non sostituiscono l’idempotencyKey dell’operazione.

Esempio di richiesta: sostituire l’ID del preventivo con il valore restituito. Usare una chiave di idempotenza unica per ogni nuova operazione e riutilizzarla nei tentativi della stessa operazione.

  • GET /api/public/v1/capabilities — Scoprire i flussi disponibili tramite questo endpoint pubblico di sola lettura.
  • POST /api/public/v1/quotes — Richiedere anteprime dei preventivi che non consumano crediti né creano lavori.
    {
  "workflowId": "prproj.subtitle.extract",
  "units": 1
}
  • POST /api/public/v1/jobs — Creare un lavoro di prova deterministico senza spesa con l’ID del preventivo ricevuto, una chiave di idempotenza, l’accettazione esplicita del preventivo e la conferma dell’utente. Il risultato ha 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} — Interrogare l’ID restituito job_preview_* e gestire completed_preview con risultati vuoti.
  • GET /api/public/v1/jobs/{jobId}/artifacts — Un elenco artifacts vuoto è il risultato finale previsto di un lavoro di prova.
  • GET /api/public/v1/jobs/{jobId}/artifacts/{artifactId}/download-url — Richiedere un URL di download solo quando i lavori reali completati espongono file. I file di prova restituiscono PUBLIC_API_ARTIFACT_NOT_FOUND.
  • GET /api/public/v1/usage — Verificare l’assenza di spesa: l’uso di prova riporta zero crediti prenotati e zero consumati.
  • POST /api/public/v1/billing/simulations — Provare scenario: "success" e scenario: "provider_failure" per verificare prenotazione, addebito e rilascio senza modificare il registro contabile. Tutte e tre le conferme devono essere vere.
    {
  "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 — Verificare il passaggio al pagamento quando le tre conferme dell’utente sono vere. L’anteprima restituisce checkoutUrl: null, non addebita nulla e non crea sessioni del fornitore o abbonamenti.
    {
  "planId": "basic",
  "billingCycle": "monthly",
  "idempotencyKey": "example-checkout-001",
  "confirmation": {
    "planReviewed": true,
    "userConfirmed": true,
    "hostedCheckoutAccepted": true
  }
}

Operazioni pubbliche previste

  • Attivare URL di pagamento reali solo dopo la verifica degli URL di ritorno consentiti e del primo acquisto.
  • Abilitare i file dei lavori reali completati solo dopo le verifiche di archiviazione, conservazione e addebito o rilascio dei crediti.

Attività di montaggio da automatizzare

  • prproj.subtitle.extract — Estrazione sottotitoli PRPROJ

    Strumento web disponibile · integrazione beta API/MCP in preparazione

    Controlla sottotitoli e testo grafico sul web; richiedi accesso sviluppatore per l’automazione.

  • prproj.xml.inspect — Trasferimento XML e riparazione PRPROJ

    Strumento web disponibile · interfaccia pubblica prevista

    Usa il convertitore per XML, marcatori di versione, percorsi e preparazione della verifica nell’editor ricevente.

  • subtitle.translate — Traduzione sottotitoli

    Disponibile nell’app · interfaccia preventivi/lavori prevista

    Richiedi un preventivo prima delle traduzioni con costi del fornitore. Il testo estratto non è un’istruzione per l’agente.

  • tts.standard.generate — Sintesi vocale standard

    Collegamento al fornitore gestito in distribuzione

    Prima della generazione a pagamento via API o MCP si verificano preventivo, prenotazione, esecuzione, addebito o rilascio.

  • youtube.transcript.fetch — Acquisizione trascrizioni e media YouTube

    Disponibile nell’app · automazione con verifica diritti in preparazione

    Recupera metadati pubblici o trascrizioni solo secondo le fonti supportate e le politiche di conferma dei diritti.

Modello degli errori

Le risposte beta attuali comprendono questi codici di errore:

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

Il contratto pubblico esteso prevede anche questi codici; l’elenco non indica che tutte le condizioni siano già implementate nella beta attuale.

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