PaperOffice Voice API

Schnittstelle zur automatischen Sprachsynthese für sämtliche PaperOffice-Anwendungen. Die folgende Dokumentation beschreibt den direkten Zugriff auf die TTS-Pipeline der zweiten Generation.

Basis-URL

https://api.paperoffice.ai/job/add/paperoffice_voice___tts

Für Tests in Entwicklungsumgebungen existieren separate Staging-Endpunkte mit identischer Struktur.

Authentifizierung

Zugriff erfolgt ausschließlich über freigeschaltete Systeme innerhalb der PaperOffice-Infrastruktur. Zusätzliche Header sind nicht erforderlich.

Request

• Methode: POST
• Content-Type: multipart/form-data (optional application/x-www-form-urlencoded)

Pflichtfelder

Feld	Typ	Beschreibung
text	string	Inhalt, der vertont werden soll. Unterstützung für Emotions-Markup wie (happy), (sad), (whispering) usw.
voice	string	Alias einer verfügbaren Stimme. Alias ist nicht case-sensitiv.

Optionale Felder

Feld	Typ / Werte	Standard	Beschreibung
language	ISO-639-1 (z. B. de, en)	automatisch aus voice	Kann gesetzt werden, falls kein Voice-Alias verwendet wird.
output_format	mp3 \ wav \ ogg	mp3	Zielformat der Ausgabe.
priority	queue \ stream	queue	stream hält die Verbindung bis zur Fertigstellung (Timeout 120 s).
return_url	bool (true/false)	false	Bei true liefert der Endpunkt das Ergebnis direkt im Response-Body.
gpu	0 \ 1	Auto	Ziel-GPU, falls mehrere Instanzen verfügbar sind.
speed	float	1.0	Nachträgliche Geschwindigkeitsanpassung. Werte ≠ 1 beeinträchtigen Qualität.
temperature	float (0.1 – 1.0)	0.95	Variation der Stimmführung.
top_p	float (0.1 – 1.0)	0.85	Sampling-Parameter für Diversität.
repetition_penalty	float (0.9 – 1.99)	1.0	Unterdrückt Wiederholungen.
reference_voice	string	–	Direkter Pfad zu einer Referenzdatei, falls kein Alias genutzt wird.
voice_type	base \ standard \ premium	base	Nur relevant, wenn voice nicht gesetzt ist.
gender	male \ female	–	Auswahlkriterium in Kombination mit language.
return_base64	bool	false	Liefert zusätzlich die Audiodaten als Base64-String.

Beispiel-Request

POST /job/add/paperoffice_voice___tts
Content-Type: multipart/form-data

text=(happy)Sehr geehrter Herr Becker(laughing), vielen Dank für Ihre Nachricht...
voice=Marlene
output_format=mp3
priority=stream
return_url=true
gpu=1
temperature=0.95
top_p=0.8
repetition_penalty=1.0

Erfolgsantwort (Direktmodus)

{
  "job_id": "poai-job_900_1762796561.6829",
  "message": "Job processed successfully",
  "operation": "tts",
  "pipeline": "paperoffice_voice",
  "processing_time": "7236.85ms",
  "result": {
    "status": "completed",
    "audio_base64": "",
    "output_files": [
      "https://api.paperoffice.ai/job/download/<token>"
    ],
    "duration_ms": "6853.0",
    "audio_duration_seconds": 24.938,
    "text_length": 885,
    "message": "TTS Audio generiert (Sprache=de, Stimme=Marlene, 885 Zeichen)",
    "processing_time_seconds": 6.853,
    "processing_ratio": "1:3.64",
    "real_time_factor": 0.275
  },
  "status": "success"
}

Bedeutende Felder

• job_id – eindeutige Kennung, kann für Monitoring und Kontrolle verwendet werden.
• output_files – signierte Download-URLs (gültig ca. 24 h); bei Bedarf sofort sichern.
• audio_base64 – nur gesetzt, wenn return_base64=true.
• processing_ratio / real_time_factor – Qualitätskennzahlen (je größer das Verhältnis, desto schneller).
• duration_ms – erzeugte Audio-Länge in Millisekunden.

Erfolgsantwort (Queue-Modus)

{
  "job_id": "poai-job_900_1762797000.1234",
  "message": "Job queued",
  "status": "queued"
}

Das Ergebnis wird später über die gleichen Felder (result, output_files usw.) bereitgestellt und kann über den Download-Link bezogen werden.

Fehlermeldungen

{
  "status": "error",
  "message": "Voice-Alias 'XYZ' wurde nicht gefunden",
  "pipeline": "paperoffice_voice",
  "processing_time": "112.34ms"
}

Typische Ursachen:

• Fehlende Pflichtfelder (text, voice).
• Ungültige Parameterbereiche (z. B. repetition_penalty außerhalb 0.9–1.99).
• Voice-Alias existiert nicht oder ist deaktiviert.

Stimmenkatalog

Die vollständige Liste aller Voice-Alias befindet sich in voices.json. Alias-Namen sind lokalisiert (z. B. Marlene, Anneliese, Polina).

• standard – reguläre Sprecher:innen.
• premium – speziell optimierte Stimmen, beispielsweise russische Varianten.
• Alias-Auflösung ist nicht case-sensitiv.

Best Practices

• Emotionale Tags im Text nutzen, z. B. (happy), (sad), (whispering).
• Standardgeschwindigkeit (speed=1.0) beibehalten für bestmögliche Qualität.
• Längere Skripte auf < 2000 Zeichen pro Anfrage begrenzen.
• Für Echtzeit-Antworten priority=stream und return_url=true kombinieren.

Changelog (Kurzfassung)

• Voice Pipeline V2 – Datei-basierte Jobsteuerung, redundante Ergebnis-Speicherung, neue Metriken (audio_duration_seconds, processing_ratio, real_time_factor), Unterstützung für verschiedene Ausgabekodierungen (mp3, wav, ogg), optimierte Stimmenauswahl über voices.json.