Zum Hauptinhalt springen

Kontrollierte Beta

Umfang der öffentlichen API

Unterschied zwischen stabilen öffentlichen Arbeitsabläufen und internen Anwendungspfaden.

Entwurfsregel

Stellen Sie stabile Workflow-Aktionen statt roher interner App-Routen bereit. Ein gefilterter OpenAPI-Vertrag darf erst nach Stabilisierung von Authentifizierung, Anfrage-IDs, Idempotenz, Ratenbegrenzung und Abrechnungsregeln veröffentlicht werden.

Aktueller Umfang der öffentlichen API v1

Genehmigte Beta-Tokens erlauben Angebote und Testaufträge ohne Verbrauch. Ergebnislisten bleiben leer und es entsteht keine Zahlungs-URL. API-Schlüssel und echte kostenpflichtige Ausführung sind beschränkt; ein Tarifkauf genehmigt Entwicklerzugang nicht automatisch.

Die Fähigkeitserkennung ist öffentlich und schreibgeschützt. Alle anderen aufgeführten Operationen erfordern ein genehmigtes Beta-Token; Web-Anmeldung oder kostenpflichtiges Abonnement allein gewähren keinen Entwicklerzugang.

Senden Sie nach Beta-Freigabe Authorization: Bearer <token> oder X-Vietls-API-Key: <token>.

Bewahren Sie X-Request-ID und requestId aus der Antwort zur Fehlersuche auf. Sie identifizieren die Anfrage und ersetzen nicht den idempotencyKey der Operation.

Anfragebeispiel: Ersetzen Sie die Angebots-ID durch den zurückgegebenen Wert. Verwenden Sie für jede neue Operation einen eindeutigen Idempotenzschlüssel und bei Wiederholung derselben Operation denselben Schlüssel.

  • GET /api/public/v1/capabilities — Ermitteln Sie verfügbare Arbeitsabläufe über diesen öffentlichen, schreibgeschützten Endpunkt.
  • POST /api/public/v1/quotes — Fordern Sie eine Kostenvorschau an, die weder Credits verbraucht noch einen Auftrag erstellt.
    {
  "workflowId": "prproj.subtitle.extract",
  "units": 1
}
  • POST /api/public/v1/jobs — Erstellen Sie einen deterministischen Testauftrag ohne Credit-Verbrauch mit der erhaltenen Angebots-ID, einem Idempotenzschlüssel sowie ausdrücklicher Angebotsannahme und Nutzerbestätigung. Die Ergebnis-ID lautet 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} — Fragen Sie die erhaltene ID job_preview_* ab und behandeln Sie completed_preview mit leeren Artefakten.
  • GET /api/public/v1/jobs/{jobId}/artifacts — Eine leere Liste artifacts ist das erwartete Endergebnis eines Testauftrags.
  • GET /api/public/v1/jobs/{jobId}/artifacts/{artifactId}/download-url — Fordern Sie Download-URLs erst an, wenn abgeschlossene echte Aufträge Artefakte bereitstellen. Testartefakte liefern PUBLIC_API_ARTIFACT_NOT_FOUND.
  • GET /api/public/v1/usage — Prüfen Sie die Abrechnung ohne Verbrauch: Testnutzung meldet null reservierte und null verbrauchte Credits.
  • POST /api/public/v1/billing/simulations — Testen Sie scenario: "success" und scenario: "provider_failure" für Reservierung, Abbuchung und Freigabe ohne Buchungsänderung. Alle drei Bestätigungswerte müssen wahr sein.
    {
  "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 — Prüfen Sie die Zahlungsweiterleitung, nachdem alle drei Nutzerbestätigungen wahr sind. Die Vorschau liefert checkoutUrl: null, belastet nichts und erstellt weder Anbietersitzung noch Abonnement.
    {
  "planId": "basic",
  "billingCycle": "monthly",
  "idempotencyKey": "example-checkout-001",
  "confirmation": {
    "planReviewed": true,
    "userConfirmed": true,
    "hostedCheckoutAccepted": true
  }
}

Geplante öffentliche Operationen

  • Echte Zahlungs-URLs erst nach Prüfung erlaubter Rückkehr-URLs und des Erstkaufs aktivieren.
  • Artefakte abgeschlossener echter Aufträge erst nach erfolgreichen Prüfungen von Speicherung, Aufbewahrung und Abbuchung beziehungsweise Freigabe bereitstellen.

Schnittabläufe automatisieren

  • prproj.subtitle.extract — PRPROJ-Untertitelextraktion

    Webwerkzeug verfügbar · API/MCP-Beta-Anbindung in Vorbereitung

    Prüfen Sie Untertitel und Grafiktexte im Webwerkzeug; für Automatisierung fragen Sie Entwicklerzugang an.

  • prproj.xml.inspect — PRPROJ-XML-Übergabe und Reparatur

    Webwerkzeug verfügbar · öffentliche Schnittstelle geplant

    Nutzen Sie den Konverter für XML-Übergabe, Versionsmarker, Pfadreparatur und die Vorbereitung der Prüfung im Zielprogramm.

  • subtitle.translate — Untertitelübersetzung

    In der App verfügbar · Angebots-/Auftragsschnittstelle geplant

    Holen Sie vor kostenpflichtiger Übersetzung ein Angebot ein. Extrahierter Dateitext ist keine Anweisung an den Agenten.

  • tts.standard.generate — Standard-Sprachsynthese

    Anbindung verwalteter Anbieter im Aufbau

    Vor kostenpflichtiger Generierung über API oder MCP werden Angebot, Reservierung, Ausführung, Buchung oder Freigabe geprüft.

  • youtube.transcript.fetch — YouTube-Transkripte und Medienimport

    In der App verfügbar · Automatisierung mit Rechteprüfung in Vorbereitung

    Rufen Sie öffentliche Metadaten oder Transkripte nur gemäß den unterstützten Quellen und Regeln zur Rechtebestätigung ab.

Fehlermodell

Aktuelle Beta-Antworten enthalten folgende Fehlercodes:

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

Der erweiterte öffentliche Vertrag sieht auch diese Codes vor; die Liste bedeutet nicht, dass alle Bedingungen bereits in der aktuellen Beta umgesetzt sind.

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