API Documentation for Real Estate Voice Generation

By Oceanspin Voices editorial team · Updated 2026-11-19

This documentation provides everything real estate freelancers need to integrate Oceanspin Voices into their virtual property tour workflows. Learn how to generate natural-sounding narration for walkthroughs using our standard TTS API, which mirrors the OpenAI speech endpoint structure. You will find clear examples for authentication, voice selection, and audio format handling, ensuring seamless delivery of high-quality audio to global buyers in 23 languages.

We cover practical integration steps, including setting up the OpenAI SDK, managing API keys, and handling rate limits. You will also discover how to select specific voices like Aria or Atlas, adjust speech speed, and interpret response codes. This guide focuses on concrete, usable code snippets and parameter details tailored for real estate audio generation, helping you deliver professional narration efficiently without unnecessary complexity.

API Documentation for Real Estate Voice Generation

Frequently asked questions

What is the API endpoint for speech generation?

Send a POST request to https://api.oceanspin.info/v1/audio/speech with a JSON body containing your text and voice settings. This endpoint handles the synthesis of your input text into audio files, following the same request shape as the OpenAI speech endpoint for easy integration.

How do I authenticate my requests?

Include your API key in the request header using the format: Authorization: Bearer tts-... You receive one active key per account. If you issue a new key, the old one stops working immediately, so ensure your integration uses the current valid key.

Can I use the OpenAI SDK with this API?

Yes, the official OpenAI SDKs work by changing the base_url to https://api.oceanspin.info/v1 and using your site's key. This allows you to use familiar SDK methods while leveraging our specific TTS engine and voice presets without needing a custom client library.

What audio formats are supported?

You can choose from mp3, wav, opus, flac, or pcm by setting the response_format field. These formats cover various quality and size needs for your real estate virtual tours, allowing you to select a balance between file size and audio fidelity.

How do I set the language to Hindi?

Set the language field to the ISO code 'hi' in your request JSON. While the system guesses language from the script, explicitly setting it ensures accurate synthesis for Hindi text, avoiding default English interpretation for Latin-script inputs or ambiguous cases.

What is the maximum text length per request?

Each request supports up to 4096 characters of input text. For longer property descriptions, split your text into parts of this size, generate audio for each, and join the resulting audio files to create a complete narration for your virtual tour.

What are the rate limits for the API?

The limit is 60 requests per minute per key, or 10 per minute before your first top-up. Requests are processed sequentially, so under load, a request may wait in a queue. Plan your generation batches accordingly to avoid delays in your workflow.

How do I handle rate limit errors?

Implement retry logic with exponential backoff in your integration code. Since requests are processed one after another, you may encounter queue delays. Ensure your application handles HTTP 429 responses gracefully, waiting before retrying to stay within the 60 requests per minute limit.

Is there a model parameter required?

Yes, the model parameter is required. You must specify either tts-1 or tts-1-hd. Both models use the same engine and pricing, so you can choose based on your quality preference without affecting your billing rate or character count calculations for the generated audio files.

How do I change the voice speed?

Set the speed field to a value between 0.25 and 4.0. This allows you to adjust the narration pace for your property tours, making it slower for detailed walkthroughs or faster for quick overviews, ensuring the audio fits your video timing perfectly.

What happens if a request fails?

If synthesis fails, the charge is returned in full, so you are not billed for unsuccessful attempts. This ensures you only pay for successfully generated audio files, protecting your budget while you refine your text input or voice settings.

How do I get the list of available voices?

Make a GET request to /v1/voices to retrieve the list of available voices, languages, formats, and pricing details. This endpoint provides the necessary information to select the appropriate voice preset for your specific real estate narration needs.

Can I generate multiple audio files at once?

The API processes requests sequentially, so you cannot generate multiple files simultaneously in a single call. You must send separate POST requests for each text segment or voice variation, waiting for each response before sending the next to stay within rate limits.

How do I rotate my API key?

You can issue a new key at any time from your account dashboard. When you generate a new key, the old one stops working immediately, ensuring secure access. Update your integration configuration promptly to avoid any interruption in your speech generation services.

First request

curl

curl https://api.oceanspin.info/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.oceanspin.info/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.oceanspin.info/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
ariafemale
novafemale
lunafemale
sagefemale
felixmale
milomale
atlasmale
orionmale
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

Authentication and API Key

Sound wave illustration for: Authentication and API Key

Secure your API key at https://oceanspin.info/get-api-key/ using Google or email. This single key authenticates all requests to generate narration for your virtual property tours, tracking your balance and usage in real time.

Generate Your Key

Generate Your Key

Visit the dashboard to create your key instantly. Google sign-ups include a $0.50 free trial, while email accounts start with zero balance until you top up via USDT (TRC-20).

  • One active key per account
  • Instant issuance upon creation

Bearer Token Format

Bearer Token Format

Include your key in the HTTP header as Authorization: Bearer tts-.... The API validates this token for every POST request to generate audio files for your listings.

Key Rotation Policy

Generate a new key anytime from your dashboard. The previous key stops working immediately, ensuring your property tour audio generation remains secure without downtime.

First Request with cURL

Sound wave illustration for: First Request with cURL

Once you have your API key from /get-api-key/, you can immediately start generating audio for property tours. The endpoint accepts standard JSON payloads, making it easy to integrate into your existing workflow without learning a proprietary system.

Below is a minimal example using cURL to convert a short property description into speech. This request demonstrates the core interaction between your script and the Oceanspin API.

Basic POST Request

Send a POST request to https://api.oceanspin.info/v1/audio/speech with your Bearer token. The following command generates a 15-second clip of a virtual tour introduction using the atlas voice.

curl -X POST https://api.oceanspin.info/v1/audio/speech \ -H "Authorization: Bearer tts-YourAPIKeyHere" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Welcome to this stunning modern home.", "voice": "atlas", "response_format": "mp3"}'

JSON Body Structure

The request body requires four essential fields: model, input, voice, and response_format. The input text must not exceed 4,096 characters. For real estate scripts, this limit covers most standard property descriptions.

Response Handling

On success, the API returns the audio file directly in the response body with a Content-Type matching your requested format. Save this binary data to a local file for playback in your tour software.

OpenAI SDK Compatibility

Sound wave illustration for: OpenAI SDK Compatibility

Integrating our TTS engine with your existing codebase is straightforward because we mirror the OpenAI speech endpoint structure. You only need to adjust the base URL and supply your API key, allowing you to leverage familiar libraries without learning a new interface.

This compatibility means real estate freelancers can quickly swap in Oceanspin Voices into their existing virtual tour workflows. Use the official OpenAI SDKs by pointing them to our API base, ensuring seamless audio generation for property walkthroughs.

Base URL Configuration

Point your SDK client to https://api.oceanspin.info/v1. This single change directs all requests to our infrastructure while maintaining the standard request shape.

Keep your tts-... bearer token in the Authorization header. The SDK handles the rest, treating our endpoint as a drop-in replacement for the standard speech service.

SDK Setup Steps

Install the standard OpenAI Python or Node.js package. Initialize the client with your API key and the new base URL.

Ensure your key is active. You can rotate keys anytime from the dashboard if needed, but the SDK connection remains stable.

Code Examples

  • Set base_url to https://api.oceanspin.info/v1
  • Use model as tts-1 or tts-1-hd
  • Pass voice like nova for upbeat tours
  • Include input text up to 4096 characters

Supported Audio Formats

Sound wave illustration for: Supported Audio Formats

Choose the right audio format to balance playback quality and bandwidth for your virtual property tours. MP3 is the standard choice for web embedding, ensuring smooth streaming across all devices while keeping file sizes small for faster loading speeds during client presentations.

MP3 for Web Playback

MP3 is a standard choice for web embedding. It offers a balance between audio fidelity and compression, making it suitable for real estate listings where clear narration is needed without excessive data usage.

WAV for High Quality

Select WAV when you need uncompressed, high-fidelity audio for professional studio masters or archival purposes. This format preserves the full detail of the synthetic voice, ensuring that every nuance of the narration is captured without any lossy compression artifacts.

FLAC and OPUS Options

Use FLAC for lossless compression when you need smaller files than WAV but retain all audio data. OPUS is an efficient format for variable network conditions, offering high quality at lower bitrates, which is useful for mobile tour applications.

  • FLAC: Lossless compression, smaller than WAV.
  • OPUS: Efficient streaming, low bitrate quality.

Voice and Language Parameters

Sound wave illustration for: Voice and Language Parameters

Choose from eight distinct presets to match your property’s vibe, whether it’s the warm, clear narration of Aria or the deep, documentary tone of Orion. Each voice is built from licensed recordings, ensuring natural-sounding walkthroughs for virtual tours.

You can explicitly set the language using ISO codes, which is crucial when using Latin script for languages other than English, such as Hindi, German, or Japanese. This prevents the system from guessing the wrong language and ensures accurate pronunciation for global buyers.

Selecting a Voice

Select a voice that complements your property’s style. Use Felix for energetic promotional clips, Luna for soft storytelling during evening tours, or Atlas for neutral, news-style updates. Each preset offers a distinct personality to keep your narration engaging.

  • Aria: Warm, clear narrator
  • Nova: Bright, upbeat
  • Luna: Soft, storytelling
  • Sage: Calm, instructional
  • Felix: Energetic, promo
  • Milo: Friendly, conversational
  • Atlas: Neutral, news
  • Orion: Deep, documentary

Setting Hindi Language

To ensure correct pronunciation, explicitly set the language parameter to hi when using Latin script text that might otherwise default to English. This is especially important for non-English languages to avoid misinterpretation by the voice engine.

  • Set language: "hi" for Hindi
  • Prevents default English guessing
  • Supports 23 languages total

Speed Adjustment

Adjust the speed parameter between 0.25 and 4.0 to control the pacing of the narration. Slower speeds (e.g., 0.75) are ideal for detailed property features, while faster speeds (e.g., 1.5) work well for quick overviews.

  • Range: 0.25 to 4.0
  • Default speed is 1.0
Voice and Language Parameters

Rate Limits and Performance

Sound wave illustration for: Rate Limits and Performance

For real estate freelancers managing multiple property tours, understanding throughput is essential for smooth client deliveries. The API enforces a strict limit of 60 requests per minute per active key. This cap ensures consistent performance but requires careful planning when generating narration for long video walkthroughs.

60 Requests Per Minute

Each API call consumes one unit of your quota. New accounts without top-ups start with a lower limit of 10 requests per minute. Once you top up via USDT (TRC-20), the standard 60 requests/minute applies immediately.

Queue Processing

Requests are processed sequentially. If you exceed the rate limit, subsequent requests enter a queue. Long texts may take time to synthesize, roughly 25 characters per second of audio. Under heavy load, you may experience slight delays as requests wait their turn.

  • Process requests one by one to avoid queuing delays.
  • Monitor your key’s usage dashboard for real-time status.

Character Limits

Each request supports up to 4,096 characters. For longer property descriptions, split the text into chunks. Generate each chunk separately and join the resulting audio files. Spaces and punctuation count toward this limit.

Error Handling and Status Codes

Sound wave illustration for: Error Handling and Status Codes

API responses return standard HTTP status codes to indicate synthesis success or failure. Failed requests are free, with charges returned in full if synthesis fails.

Common Error Codes

Use 400 for invalid parameters (e.g., bad voice name), 401 for authentication issues, 429 for rate limits, and 500 for server errors.

Retry Logic

Implement exponential backoff for 429 and 500 errors. Since requests are processed sequentially, brief delays help manage queue load during high traffic.

Debugging Tips

Verify your Bearer token format and ensure the model field is set to 'tts-1' or 'tts-1-hd'. Check character limits (4096 max) before sending long property descriptions.

  • Confirm ISO language codes match the list of 23 supported languages.
  • Ensure audio format is one of mp3, wav, opus, flac, or pcm.

Testing and Validation

Sound wave illustration for: Testing and Validation

Before building your virtual tour narration, verify your integration using the dedicated metadata endpoints. These tools help you confirm connectivity and available resources without consuming your character balance for actual audio synthesis.

Validation Endpoints

Use the standard endpoints to check your key’s validity and retrieve system status. These requests are lightweight and help ensure your API key is active before you begin generating property tour audio.

Model Information

Query the /v1/models endpoint to confirm available engines. You can choose between "tts-1" or "tts-1-hd"; both use the same engine and price.

  • tts-1: Standard engine, balanced speed and quality.
  • tts-1-hd: Higher fidelity for luxury listings.

Voice Listing

Call GET /v1/voices to retrieve all eight presets and supported languages. This allows your application to dynamically populate dropdown menus, letting users select voices like "atlas" for neutral news-style updates or "nova" for bright, upbeat property highlights.

  • Returns voice ID, name, gender, and available languages.
  • Supports all 23 languages including English, Hindi, and Spanish.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. The tone of your narration sets the stage for the entire viewing experience.

Avatar of the voice aria
ariafemale
Avatar of the voice nova
novafemale
Avatar of the voice luna
lunafemale
Avatar of the voice sage
sagefemale
Avatar of the voice felix
felixmale
Avatar of the voice milo
milomale
Avatar of the voice atlas
atlasmale
Avatar of the voice orion
orionmale

23 languages

Any voice speaks any of these languages.

Sources and further reading

  1. Wikipedia
  2. openai-python on GitHub
  3. curl documentation
  4. Creative Commons Attribution 4.0
  5. openai-node on GitHub
  6. MDN: Web Speech API
  7. TRON developer hub: TRC-20
  8. W3C WAI: making audio and video accessible
  9. ISO 639 language codes
  10. LibriTTS-R corpus (OpenSLR 141)
  11. LibriVox public-domain audiobooks
  12. Python documentation

More on this site