API Dokumentation für Immobilien-Freelancer

Von PlayTTS Studio Redaktion · Aktualisiert 2026-11-18

Diese Dokumentation erklärt Ihnen Schritt für Schritt, wie Sie unsere Text-to-Speech-API für Immobilien-Exposés und virtuelle Touren nutzen. Sie erfahren, wie Sie Ihren persönlichen API-Schlüssel erhalten, erste Audio-Dateien generieren und die Integration in Ihre bestehenden Workflows mit dem OpenAI SDK meistern. Alles, was Sie für die automatische Sprachausgabe Ihrer Objektbeschreibungen benötigen, finden Sie hier kompakt zusammengefasst.

Die Anleitung richtet sich speziell an Freelancer im Immobilienbereich, die Textvorlagen schnell und kostengünstig in professionelle Audiodateien umwandeln möchten. Wir listen die verfügbaren Modelle, Stimmen und Formate auf und zeigen Ihnen anhand konkreter CURL-Beispiele, wie Sie die API direkt ansprechen. So erstellen Sie effizient native Sprachaufnahmen für hunderte Objekte, ohne technische Hürden zu überwinden.

API Dokumentation für Immobilien-Freelancer

Häufig gestellte Fragen

Wie erhalte ich meinen API-Schlüssel?

Registrieren Sie sich auf /get-api-key/ mit Google oder E-Mail. Nach der Anmeldung sehen Sie Ihren persönlichen API-Schlüssel, Ihr Guthaben und die verbleibenden Zeichen auf der Seite. Sie können jederzeit einen neuen Schlüssel ausstellen, wodurch der alte sofort ungültig wird.

Welche SDKs werden unterstützt?

Wir bieten kein eigenes SDK. Die API ist kompatibel mit der offiziellen OpenAI SDK, indem Sie die base_url auf https://api.playtx666.com/v1 ändern. Sie können auch jede andere HTTP-Bibliothek nutzen, die JSON-Anfragen unterstützt.

Kann ich die API mit Python nutzen?

Ja, Sie können die API problemlos mit Python nutzen. Verwenden Sie die OpenAI Python SDK oder eine Standard-Library wie requests. Ändern Sie einfach die base_url auf https://api.playtx666.com/v1 und übergeben Sie Ihren API-Schlüssel im Header.

Wie hoch ist die maximale Textlänge?

Die maximale Textlänge beträgt 4096 Zeichen pro Anfrage. Für längere Texte wie ganze Exposés müssen Sie den Text in kleinere Teile aufteilen, diese einzeln synthetisieren und die resultierenden Audio-Dateien anschließend zusammenfügen.

Was passiert bei einem Timeout?

Wenn die Synthese fehlschlägt, wird der Betrag vollständig erstattet. Sie zahlen also nur für erfolgreiche Anfragen. Bei hoher Auslastung kann es zu Wartezeiten in der Queue kommen, aber die Kosten bleiben fair.

Gibt es eine Dokumentation für alle Parameter?

Ja, die Parameter sind über den Endpunkt GET /v1/voices dokumentiert, der Stimmen, Sprachen, Formate und Preise auflistet. Der POST-Endpunkt für v1/audio/speech akzeptiert model, input, voice, response_format, speed und language.

Kann ich mehrere API-Schlüssel gleichzeitig nutzen?

Pro Konto ist nur ein aktiver API-Schlüssel möglich. Wenn Sie einen neuen Schlüssel ausstellen, wird der alte sofort ungültig. Sie können jedoch mehrere unabhängige Konten erstellen, um mehrere Schlüssel parallel zu nutzen.

Wie lange ist der API-Schlüssel gültig?

Der API-Schlüssel hat keine feste Ablaufzeit. Er bleibt gültig, solange Ihr Konto aktiv ist. Sie können jederzeit einen neuen Schlüssel ausstellen, wodurch der vorherige sofort deaktiviert wird, ohne dass das Guthaben verloren geht.

Werden JSON-Objekte im Body unterstützt?

Ja, Sie senden JSON-Objekte an den Endpunkt POST https://api.playtx666.com/v1/audio/speech. Das JSON enthält Felder wie model, input, voice und response_format. Die Struktur entspricht der OpenAI-Speech-Endpunkt-Spezifikation.

Kann ich die API mit Proxy nutzen?

Ja, da es sich um eine Standard-HTTP/HTTPS-API handelt, können Sie sie problemlos hinter einem Proxy nutzen. Stellen Sie sicher, dass Ihre Proxy-Konfiguration die Authentifizierung über den Authorization: Bearer-Header korrekt weiterleitet.

Gibt es eine Sandbox-Umgebung?

Es gibt keine separate Sandbox-Umgebung. Sie nutzen die gleiche Produktions-API. Sie erhalten jedoch 0,50 $ Startguthaben für 7 Tage, wenn Sie sich mit Google anmelden. Dies eignet sich gut, um die API zu testen.

Wie kann ich die Lautstärke anpassen?

Sie können jedoch die Geschwindigkeit (speed) zwischen 0.25 und 4.0 anpassen. Für Lautstärkenanpassungen nach der Generierung nutzen Sie einfach ein Standard-Audio-Tool Ihrer Wahl.

Unterstützt die API Hintergrundgeräusche?

Nein, die API erzeugt reinen Sprachaudio. Es werden keine Hintergrundgeräusche oder Musik unterstützt. Das generierte Audio enthält nur die synthetisierte Stimme. Hintergrundgeräusche müssen Sie ggf. nachträglich in Ihrer Audio-Software hinzufügen.

Erste Anfrage

curl

curl https://api.playtx666.com/v1/audio/speech \
  -H "Authorization: Bearer $TTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"tts-1","voice":"aria","input":"Hello from the API.","response_format":"mp3"}' \
  --output hello.mp3

Python (openai)

from openai import OpenAI

client = OpenAI(base_url="https://api.playtx666.com/v1", api_key="tts-...")

with client.audio.speech.with_streaming_response.create(
    model="tts-1", voice="nova", input="Hello from Python.", response_format="mp3"
) as response:
    response.stream_to_file("hello.mp3")

Node.js (openai)

import OpenAI from "openai";
import fs from "node:fs";

const client = new OpenAI({ baseURL: "https://api.playtx666.com/v1", apiKey: process.env.TTS_API_KEY });
const res = await client.audio.speech.create({ model: "tts-1", voice: "milo", input: "Hello from Node.js." });
fs.writeFileSync("hello.mp3", Buffer.from(await res.arrayBuffer()));
voice
ariaweiblich
novaweiblich
lunaweiblich
sageweiblich
felixmännlich
milomännlich
atlasmännlich
orionmännlich
language
arالعربية
zh中文
daDansk
nlNederlands
enEnglish
fiSuomi
frFrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
itItaliano
ja日本語
ko한국어
msBahasa Melayu
noNorsk
plPolski
ptPortuguês
ruРусский
esEspañol
swKiswahili
svSvenska
trTürkçe

API-Schlüssel erhalten

Schallwellenillustration für: API-Schlüssel erhalten

Erhalten Sie Ihren API-Schlüssel, um Text-to-Speech-Daten für Immobilien-Exposés zu generieren. Die Registrierung erfolgt direkt auf unserer Plattform für Freelancer im Immobilienbereich.

Sobald Ihr Konto eingerichtet ist, haben Sie sofort Zugriff auf die notwendigen Credentials für die Integration unserer TTS-API in Ihre Arbeitsabläufe.

Registrierung auf der Seite

Registrierung auf der Seite

Besuchen Sie die Seite /get-api-key/, um Ihr Konto zu erstellen. Sie können sich entweder mit Ihrem Google-Konto anmelden oder ein neues Konto mit E-Mail und Passwort erstellen. Beachten Sie, dass Google-Anmeldungen einen kostenlosen Testguthaben von $0,50 erhalten, während E-Mail-Konten ohne Guthaben starten.

Nach der Anmeldung wird Ihr persönlicher API-Schlüssel angezeigt. Dieser Schlüssel ist der Zugang zu unserer API und ermöglicht es Ihnen, Audioanfragen zu stellen.

  • Anmeldung mit Google oder E-Mail
  • Sofortiger Zugang zum Dashboard

Schlüssel im Dashboard

Schlüssel im Dashboard

Ihr API-Schlüssel wird im Dashboard unter /get-api-key/ angezeigt. Hier sehen Sie auch Ihr aktuelles Guthaben, die Anzahl der verbleibenden Zeichen und Ihre Nutzungshistorie.

Der Schlüssel beginnt mit 'tts-'. Nutzen Sie diesen Schlüssel im Authorization-Header Ihrer API-Anfragen, um Audio-Dateien zu generieren.

  • Schlüssel: tts-...
  • Dashboard mit Nutzungsstatistiken

Schlüssel neu generieren

Sie können jederzeit einen neuen API-Schlüssel ausstellen. Wenn Sie einen neuen Schlüssel generieren, wird der alte Schlüssel sofort ungültig.

Dies ist nützlich, wenn Sie den Schlüssel in mehreren Projekten verwenden und ihn bei einem Verlust schnell ersetzen möchten.

  • Sofaltige Ungültigkeit des alten Schlüssels
  • Einfache Neuerstellung

Erste Anfrage mit CURL

Schallwellenillustration für: Erste Anfrage mit CURL

Erhalten Sie Ihren API-Schlüssel über das Dashboard auf /get-api-key/. Dort sehen Sie auch Ihren Kontostand und die verbleibenden Zeichen. Mit diesem Schlüssel können Sie direkt erste Audio-Dateien generieren, ohne zusätzliche Bibliotheken zu installieren.

JSON-Body erstellen

Die Anfrage erfolgt per POST an https://api.playtx666.com/v1/audio/speech. Der Body ist JSON und enthält model (tts-1 oder tts-1-hd), input (Ihr Text, max. 4096 Zeichen), voice (z. B. aria oder atlas), response_format und optional speed sowie language. Vergessen Sie nicht, Leerzeichen und Interpunktion als Zeichen zu zählen.

Authorization Header setzen

Setzen Sie den Header Authorization: Bearer tts-... mit Ihrem persönlichen Schlüssel aus dem Dashboard. Dieser Schlüssel ist pro Account gültig und kann jederzeit neu generiert werden, wobei der alte sofort ungültig wird. Stellen Sie sicher, dass kein Leerzeichen vor oder nach dem Token steht.

Audio-Datei speichern

Bei erfolgreicher Verarbeitung erhalten Sie die Audiodatei direkt im gewählten Format (mp3, wav, opus, flac oder pcm). Speichern Sie die Antwort binär ab. Bei Fehlern wird der Fehlercode zurückgegeben, die Anfrage bleibt jedoch kostenfrei. Testen Sie zunächst kurze Sätze, um die Qualität der Stimme zu prüfen.

OpenAI SDK Integration

Schallwellenillustration für: OpenAI SDK Integration

Da die API exakt dem Format der OpenAI-Speech-Endpunkte entspricht, können Sie die offiziellen OpenAI-SDKs nahezu unverändert nutzen. Der einzige notwendige Schritt ist die Anpassung der base_url auf unseren Endpunkt, sodass die Authentifizierung und das Payload-Format sofort kompatibel sind.

Base-URL anpassen

Ändern Sie in Ihrem SDK-Client die Basis-URL von https://api.openai.com/v1 zu https://api.playtx666.com/v1. Dies stellt sicher, dass alle nachfolgenden Anfragen direkt an unsere Infrastruktur gerichtet werden, ohne dass Sie JSON-Strukturen manuell anpassen müssen.

  • Base-URL: https://api.playtx666.com/v1
  • Kompatibel mit OpenAI Python/Node.js SDKs
  • Keine zusätzlichen Bibliotheken nötig

API-Schllüssel einfügen

Verwenden Sie den API-Schlüssel aus Ihrem Dashboard als Authorization: Bearer Header. Stellen Sie sicher, dass Sie den Schlüssel im Format tts-... verwenden, der Ihnen nach der Registrierung auf /get-api-key/ zur Verfügung steht.

Code-Beispiel bereitstellen

Hier ist ein minimales Python-Beispiel zur Generierung einer Audio-Datei für eine Immobilienbeschreibung:

  • ```python
  • import openai
  • client = openai.OpenAI(base_url='https://api.playtx666.com/v1', api_key='tts-DEIN_SCHLÜSSEL')
  • response = client.audio.speech.create(
  • model='tts-1',
  • voice='nova',
  • input='Dieses moderne Haus bietet viel Platz und Licht.'
  • )
  • response.write_to_file('haus.mp3')
  • ```

Verfügbare Modelle

Schallwellenillustration für: Verfügbare Modelle

Die API bietet zwei Modellvarianten an, die denselben Synthese-Engine nutzen: "tts-1" für den Standard-Einsatz und "tts-1-hd" für höchste audio-technische Präzision. Beide Modelle unterstützen alle 8 verfügbaren Stimmen und die gleichen Parameter.

tts-1 Standard

Das Modell "tts-1" ist die Standardoption für die meisten Anwendungsfälle, wie etwa virtuelle Immobilien-Touren. Es liefert schnelle Ergebnisse bei guter Klangqualität und ist ideal, um schnell hunderte von Objekten mit Text zu versehen.

tts-1 HD Qualität

Mit "tts-1-hd" erhalten Sie Audio-Dateien mit höherer Qualität. Dies ist besonders vorteilhaft, wenn die Audiospur in professionellen Video-Exposés oder hochwertigen Rundfunk-Qualitäten eingesetzt wird und jede Nuance der Stimme zählen soll.

Gleicher Preis für beide

Ein entscheidender Vorteil: Beide Modelle kosten exakt gleich. Der Preis beträgt 10 $ pro 1 Million Zeichen, unabhängig davon, ob Sie das Standardmodell oder die HD-Variante wählen. Sie können also jederzeit auf HD wechseln, ohne die Kosten zu erhöhen.

Audio-Formate

Schallwellenillustration für: Audio-Formate

Wählen Sie das richtige Format für Ihre Immobilien-Workflows. MP3 bietet die beste Balance aus Dateigröße und Qualität für die meisten Anwendungen im Web.

WAV und FLAC sind ideal, wenn Sie maximale Audio-Integrität benötigen, etwa für professionelle Archivierung oder hochwertige Video-Exposés.

MP3 für Web

MP3 ist das Standardformat für die meisten Webanwendungen und virtuellen Touren. Die Dateigrößen bleiben gering, was Ladegeschzeiten verkürzt und die Benutzererfahrung auf Mobilgeräten verbessert.

  • Unterstützt alle gängigen Browser und Mediaplayer
  • Ideal für die Wiedergabe in Web-Exposés

WAV für hohe Qualität

WAV bietet unkomprimierten Audio. Dies ist die bevorzugte Wahl, wenn Sie Audio-Dateien für professionelle Video-Schnittprogramme benötigen, ohne Qualitätsverlust bei weiterer Verarbeitung.

  • Verlustfreie Speicherung für maximale Detailtreue
  • Gut geeignet für nachgelagerte Audiobearbeitung

FLAC verlustfrei

FLAC (Free Lossless Audio Codec) komprimiert Audio ohne Qualitätsverlust. Es ist kleiner als WAV, aber genauso hochwertig, was Speicherplatz spart, während die Originalqualität erhalten bleibt.

  • Verlustfreie Komprimierung für Archivierungszwecke
  • Effizienter als WAV bei gleicher Klangqualität
Audio-Formate

Stimmen & Parameter

Schallwellenillustration für: Stimmen & Parameter

Wähle aus acht vorkonfigurierten Stimmen, die auf lizenzierten Aufnahmen basieren. Für Immobilien-Exposés eignen sich Aria, Luna oder Milo besonders gut, um Vertrauen und Wärme zu vermitteln. Jede Stimme beherrscht alle 23 unterstützten Sprachen, sodass du auch für internationale Käufer den passenden Ton findest.

Mit dem Parameter speed zwischen 0,25 und 4,0 passt du die Sprechgeschwindigkeit präzise an den Kontext an. Schnelle Touren profitieren von höherer Geschwindigkeit, während detaillierte Beschreibungen ruhiger wirken. Der optionale Sprachcode stellt sicher, dass die Aussprache korrekt bleibt, wenn die automatische Erkennung versagt.

8 verfügbare Stimmen

Unsere Bibliothek bietet vier weibliche und vier männliche Stimmen für unterschiedliche Szenarien. Aria liefert klare Narration, während Luna sich für Geschichten eignet. Felix eignet sich für energetische Promo-Objekte, und Atlas bietet eine neutrale Nachrichtenstimme. Milo spricht freundlich und konversationell, was gut zu virtuellen Touren passt.

Alle Stimmen basieren auf lizenzierten Aufnahmen (LibriTTS-R) und tragen ein unsichtbares Wasserzeichen. Du kannst jede Stimme für jede der 23 Sprachen nutzen, ohne zusätzliche Modelle zu benötigen.

  • Aria: Warme, klare Erzählerin
  • Nova: Hell und energiegeladen
  • Luna: Sanft, perfekt für Storytelling
  • Sage: Ruhig, instruktiv
  • Felix: Energetisch, ideal für Promo
  • Milo: Freundlich, gesprächig
  • Atlas: Neutral, wie Nachrichten
  • Orion: Tief, dokumentarisch

Geschwindigkeit 0.25–4.0

Der speed-Parameter erlaubt dir, die Wiedergabegeschwindigkeit von sehr langsam bis sehr schnell zu skalieren. Für lange Objektbeschreibungen ist eine moderate Geschwindigkeit oft angenehmer. Bei schnellen Durchläufen durch viele Immobilien kannst du die Geschwindigkeit erhöhen, um Zeit zu sparen.

Sprachcode optional

Wenn du keinen Sprachcode angibst, versucht die API, die Sprache basierend auf dem Skript zu erraten. Bei lateinischem Text wird standardmäßig Englisch angenommen. Für andere Sprachen wie Deutsch, Französisch oder Spanisch solltest du den ISO-Code explizit setzen, um Fehler bei der Aussprache zu vermeiden.

Fehlerbehandlung

Schallwellenillustration für: Fehlerbehandlung

Bei der Integration der TTS-API in Ihre Immobilien-Workflows stoßen Sie gelegentlich auf Fehler. Eine klare Fehlerbehandlung stellt sicher, dass Ihre Skripte robuste Audio-Dateien generieren, ohne dass manuell eingegriffen werden muss. Die API sendet spezifische HTTP-Statuscodes, die den genauen Grund für das Scheitern der Synthese anzeigen.

HTTP-Statuscodes

Die API antwortet mit Standard-HTTP-Codes. Ein 400-Fehler bedeutet meist, dass der JSON-Body oder die Parameter (wie model oder voice) ungültig sind. Ein 401 weist auf einen falschen oder fehlenden API-Schlüssel hin. 429 signalisiert, dass das Rate Limit von 60 Anfragen pro Minute überschritten wurde. 500-Fehler sind selten und deuten auf einen Serverfehler hin.

Fehlermeldungen verstehen

Jeder Fehler enthält eine kurze Beschreibung im JSON-Response. Lesen Sie diese Meldung, um das Format oder den Textinhalt zu korrigieren. Stellen Sie sicher, dass input nicht länger als 4096 Zeichen ist, da dies sonst zu einem Validierungsfehler führt.

  • Prüfen Sie immer den type und message im Response-Body.
  • Stellen Sie sicher, dass voice zu den 8 verfügbaren Presets gehört.

Kostenlose Fehlanfragen

Ein entscheidender Vorteil für Immobilien-Freelancer: Wenn die Synthese aufgrund eines technischen Fehlers oder ungültiger Parameter nicht erfolgreich ist, wird Ihr Guthaben nicht belastet. Die Charge wird im Falle eines Fehlers vollständig erstattet.

Rate Limits

Schallwellenillustration für: Rate Limits

Um eine stabile Generierung Ihrer Immobilien-Audioexposés zu gewährleisten, sind die API-Anfragen auf 60 pro Minute begrenzt. Dies stellt sicher, dass auch bei hoher Auslastung jedes Textfragment zuverlässig verarbeitet wird. Da die Synthese sequentiell abläuft, können bei Spitzenlast kurze Wartezeiten in der Queue entstehen.

60 Anfragen pro Minute

Jeder API-Schlüssel ist auf maximal 60 Requests pro Minute begrenzt. Dies entspricht einer hohen Durchsatzrate für die meisten Freelancer-Szenarien, bei denen Sie oft mehrere Textblöcke pro Objekt generieren.

10 Anfragen am Anfang

Neue Konten starten mit einem reduzierten Limit von nur 10 Anfragen pro Minute. Dies ermöglicht Ihnen, die API zunächst in Ruhe zu testen, ohne sofortige Limits zu erreichen. Erhöhen Sie Ihr Limit auf 60 Anfragen pro Minute durch eine erste Aufladung.

Limit nach Erstaufladung

Nach der ersten Top-up-Zahlung über USTRC20 (mindestens 5 $) aktivieren Sie das volle Limit von 60 Anfragen pro Minute. Die Aktivierung erfolgt in der Regel innerhalb weniger Minuten nach Bestätigung der Transaktion auf der TRON-Blockchain.

Hören Sie sich die 8 Stimmen an

Jede der folgenden Samples wurde von dieser API aus demselben Satz generiert. Sage verkörpert eine ruhige, sachliche Stimme, die sich perfekt für professionelle Immobilien-Exposés eignet.

Avatar der Stimme aria
ariaweiblich
Avatar der Stimme nova
novaweiblich
Avatar der Stimme luna
lunaweiblich
Avatar der Stimme sage
sageweiblich
Avatar der Stimme felix
felixmännlich
Avatar der Stimme milo
milomännlich
Avatar der Stimme atlas
atlasmännlich
Avatar der Stimme orion
orionmännlich

23 Sprachen

Jede Stimme kann jede dieser Sprachen sprechen.

Quellen und weiterführende Literatur

  1. Wikipedia
  2. LibriVox public-domain audiobooks
  3. LibriTTS-R paper (arXiv 2305.18802)
  4. Creative Commons Attribution 4.0
  5. MDN: Web Speech API
  6. Tether (USDT)
  7. FFmpeg documentation
  8. W3C WAI: making audio and video accessible
  9. IETF RFC 7845: Ogg Opus
  10. Python documentation
  11. curl documentation
  12. ISO 639 language codes

Mehr auf dieser Website