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.mp3Python (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 | |
|---|---|
aria | female |
nova | female |
luna | female |
sage | female |
felix | male |
milo | male |
atlas | male |
orion | male |
| language | |
|---|---|
ar | العربية |
zh | 中文 |
da | Dansk |
nl | Nederlands |
en | English |
fi | Suomi |
fr | Français |
de | Deutsch |
el | Ελληνικά |
he | עברית |
hi | हिन्दी |
it | Italiano |
ja | 日本語 |
ko | 한국어 |
ms | Bahasa Melayu |
no | Norsk |
pl | Polski |
pt | Português |
ru | Русский |
es | Español |
sw | Kiswahili |
sv | Svenska |
tr | Türkçe |
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
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
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
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
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_urltohttps://api.oceanspin.info/v1 - Use
modelastts-1ortts-1-hd - Pass
voicelikenovafor upbeat tours - Include
inputtext up to 4096 characters
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
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

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
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
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.
23 languages
Any voice speaks any of these languages.
