Speech from Text

The Speech from Text card converts written text into spoken audio using a voice the agent already has. Pick the voice from GET /v1/agents/{agent_id}/voice/library (public catalog, designed, cloned, or connected voices) and pass its voice_id.

Note

All generation endpoints require the agent_id query parameter.

Generate speech

POST /v1/vidsheet/{id}/cells/{cell_id}/generate?agent_id={agent_id}

Request body

Field	Type	Required	Description
generation_type	string	Yes	"speech_from_text".
data.text	string	Yes	The text to speak, 1–4000 characters.
data.voice_id	string	Yes	A voice from the agent’s voice library.
data.enhance_voice	boolean	No	Post-process for clarity. Default false.
data.remove_silence	boolean	No	Trim leading/trailing silence. Default false.

Note

Designing a voice from a description or cloning one from an audio sample are separate jobs (design_voice, clone_voice) that produce a reusable voice — they are not modes of speech_from_text.

Example

curl -X POST "https://api.gen.pro/v1/vidsheet/101/cells/3000/generate?agent_id=42" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "generation_type": "speech_from_text",
    "data": {
      "text": "Welcome back to another episode of our series.",
      "voice_id": "pNInz6obpgDQGcFmaJgB",
      "enhance_voice": true
    }
  }'

---

Response

Poll Check generation status until complete. The finished generation includes the audio URL in output_resources.

{
  "id": 9000,
  "status": "completed",
  "output_resources": [
    {
      "id": 1500,
      "url": "https://cdn.gen.pro/outputs/voiceover-abc123.mp3",
      "object_type": "audio",
      "type": "output"
    }
  ]
}

Tip

You can also run speech generation on a layer within a cell by using the layer endpoint: POST /v1/vidsheet/{id}/cells/{cell_id}/layers/{layer_id}/generate?agent_id={agent_id}

---

Cell configuration

Tip

Cell configuration is set via PATCH /v1/vidsheet/{id}/cells/{cell_id} with additional_attributes in the request body. These defaults are used when generation is triggered.

Field	Type	Description
autoGenerate	boolean	Auto-trigger generation when the text cell changes.

The voice is passed in the generation data parameter, not stored as a cell attribute.