Voices

Voices are workspace-scoped resources that hold a voice sample or reference a third-party voice provider. Pass the version ID as voice_ref when creating a session.

Try it →

List voices

GET /api/v1/workspaces/{wsId}/voices

Required scope: voices:read

Response 200

{
  "data": [
    {
      "id": "019...",
      "workspace_id": "019...",
      "name": "My voice",
      "kind": "stock",
      "current_version_id": "019...",
      "status": "active",
      "deleted_at": null,
      "region_tag": "us",
      "created_at": 1719000000,
      "updated_at": 1719000000
    }
  ]
}

---

Create a voice

POST /api/v1/workspaces/{wsId}/voices

Required scope: voices:write

Request body

{ "name": "My voice", "kind": "stock" }

Field	Required	Description
name	Yes	Human-readable label.
kind	No	"stock" (default) or "cloned".

Response 201 — voice object as shown in list above.

---

Get a voice

GET /api/v1/workspaces/{wsId}/voices/{voiceId}

Required scope: voices:read

Response 200 — single voice object.

---

List voice versions

GET /api/v1/workspaces/{wsId}/voices/{voiceId}/versions

Required scope: voices:read

Response 200

{
  "data": [
    {
      "id": "019...",
      "voice_id": "019...",
      "version_number": 1,
      "sample_r2_key": "workspaces/.../audio",
      "external_voice_id": null,
      "created_by": null,
      "created_at": 1719000000
    }
  ]
}

---

Create a voice version

POST /api/v1/workspaces/{wsId}/voices/{voiceId}/versions

Required scope: voices:write

Request body (optional)

{ "configJson": "{}" }

Response 201

{
  "id": "019...",
  "voice_id": "019...",
  "version_number": 1,
  "sample_r2_key": null,
  "external_voice_id": null,
  "created_by": null,
  "created_at": 1719000000,
  "upload_url": "/api/v1/workspaces/{wsId}/voices/{voiceId}/versions/{id}/upload"
}

After creating the version, PUT the voice audio bytes to upload_url:

curl -X PUT https://api.casola.ai{upload_url} \
  -H "Authorization: Bearer $CASOLA_API_KEY" \
  -H "Content-Type: audio/wav" \
  --data-binary @sample.wav

Pass this version’s id as voice_ref when creating a session.