Voiceover

Generate AI voiceover audio from property listing data. The API writes a narration script from property details and produces professional spoken audio.

Overview

The voiceover endpoint accepts property details (address, description, price, bedrooms, bathrooms) and generates a professional narration audio file. By default, the API uses AI to write an engaging property description script, then converts it to speech. You can also provide your own custom script to skip the AI writing step.

Voice settings can be customized using the voice ID, stability, and similarity boost parameters.

Quick Example

Submit property details to generate a voiceover:

curl -X POST \
  -H "X-API-Key: dome_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "property": {
      "address": "42 Harbour Road, Sydney NSW 2000",
      "description": "Stunning harbourside residence with panoramic views",
      "price": "$2,500,000",
      "bedrooms": 4,
      "bathrooms": 3
    }
  }' \
  https://api.dometech.com.au/v1/voiceover/generate

Response (202):

{
  "data":  {
    "job_id":  "550e8400-e29b-41d4-a716-446655440000",
    "status":  "queued"
  },
  "meta":  {
    "request_id":  "req_abc123",
    "timestamp":  "2026-02-18T10:00:00.000Z",
    "mode":  "live"
  }
}

Step-by-Step

1. Submit Property Details

Send a POST request to /v1/voiceover/generate with the property information. The only required field is the address, but providing more details produces a better narration.

curl -X POST \
  -H "X-API-Key: dome_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "property": {
      "address": "42 Harbour Road, Sydney NSW 2000",
      "description": "Stunning harbourside residence with panoramic views across the harbour",
      "price": "$2,500,000",
      "bedrooms": 4,
      "bathrooms": 3
    },
    "options": {
      "stability": 0.5,
      "similarity_boost": 0.75
    }
  }' \
  https://api.dometech.com.au/v1/voiceover/generate

The API returns a 202 Accepted response with a job_id. The audio is generated asynchronously.

Tip: To use your own narration text instead of AI generation, include options.script with your custom text. The API will skip AI script writing and generate speech directly from your script.

2. Poll for Completion

Poll the job status endpoint until the status changes to completed. Voiceover generation typically takes 15 to 45 seconds.

curl -H "X-API-Key: dome_live_your_key_here" \
  https://api.dometech.com.au/v1/jobs/550e8400-e29b-41d4-a716-446655440000

3. Retrieve the Audio

When the job completes, the output field contains the audio URL and the generated script text.

{
  "data":  {
    "id":  "550e8400-e29b-41d4-a716-446655440000",
    "job_type":  "voiceover",
    "status":  "completed",
    "mode":  "live",
    "input":  {
      "property":  { "address":  "42 Harbour Road, Sydney NSW 2000" }
    },
    "output":  {
      "audio_url":  "https://storage.example.com/voiceover.mp3",
      "script":  "Welcome to 42 Harbour Road, a stunning harbourside residence..."
    },
    "created_at":  "2026-02-18T10:00:00.000Z",
    "updated_at":  "2026-02-18T10:00:30.000Z",
    "completed_at":  "2026-02-18T10:00:30.000Z"
  },
  "meta":  {
    "request_id":  "req_abc123",
    "timestamp":  "2026-02-18T10:00:30.000Z",
    "mode":  "live"
  }
}

Options

Parameter	Type	Required	Description
`property.address`	string	Yes	Full property address
`property.description`	string	No	Property description text
`property.price`	string	No	Price display text (e.g. "$1,200,000")
`property.bedrooms`	integer	No	Number of bedrooms
`property.bathrooms`	integer	No	Number of bathrooms
`options.voice_id`	string	No	Voice ID. Default: "EXAVITQu4vr4xnSDxMaL" (Sarah)
`options.script`	string	No	Custom script text. If provided, skips AI script generation
`options.stability`	number (0-1)	No	Voice stability. Default: 0.5
`options.similarity_boost`	number (0-1)	No	Voice similarity boost. Default: 0.75
`webhook_url`	string (URI)	No	URL to receive progress and completion webhooks
`callback_metadata`	object	No	Opaque data returned in webhook payloads

See the API Reference for full parameter details and response schemas.

Output

When the job completes, the output object contains:

Field	Type	Description
`audio_url`	string	URL of the generated voiceover audio file (MP3)
`script`	string	The narration script text (AI-generated or the custom script you provided)

Next Steps

API Reference — Voiceover — Full parameter details and schemas
Brochure Slides — Generate visual slides to pair with your voiceover
Video Clips — Generate video clips to combine with narration audio
Jobs & Webhooks — Polling best practices and real-time notifications