Local reference

Voices

List Personalities

Return built-in voice personality presets.

Response Body

`application/json`

bash

curl -X GET "https://example.com/personalities"

json

null

List Profiles

Response Body

`application/json`

bash

curl -X GET "https://example.com/profiles"

json

null

Create Profile

Create a voice profile (spec: docs/specs/voice-studio-unification.md §5).

kind='clone' — requires ref_audio (the user's reference recording). kind='design' — requires vd_states (JSON of category picks); the server renders a deterministic sample WAV (seed 42, same path as archetype materialization) and stores it as the profile's reference so the voice identity is stable across runs.

Request Body

multipart/form-data

name*Name

ref_audio?string|null

ref_text?Ref Text

Default""

instruct?Instruct

Default""

language?Language

Default"Auto"

seed?integer|null

personality?Personality

Default""

kind?Kind

Default"clone"

vd_states?string|null

Response Body

`application/json`

`application/json`

bash

curl -X POST "https://example.com/profiles" \
  -F name="string"

json

null

Get Profile

Full profile record for the voice profile page.

Path Parameters

profile_id*Profile Id

Response Body

`application/json`

`application/json`

bash

curl -X GET "https://example.com/profiles/string"

json

null

Delete Profile

Path Parameters

profile_id*Profile Id

Response Body

`application/json`

`application/json`

bash

curl -X DELETE "https://example.com/profiles/string"

json

null

Update Profile

Partial update — only fields set on the payload are changed.

Path Parameters

profile_id*Profile Id

Request Body

application/json

name?string|null

ref_text?string|null

instruct?string|null

language?string|null

personality?string|null

Response Body

`application/json`

`application/json`

bash

curl -X PUT "https://example.com/profiles/string" \
  -H "Content-Type: application/json" \
  -d '{}'

json

null

Sync Profile To Hosted

Explicitly copy a consent-verified local clone to the hosted library.

This is deliberately not part of local profile creation: merely creating a profile must never upload biometric source audio. The hosted service records the existing spoken-consent evidence as its versioned attestation; it does not receive the consent recording itself.

Path Parameters

profile_id*Profile Id

Response Body

`application/json`

`application/json`

bash

curl -X POST "https://example.com/profiles/string/hosted-sync"

json

null

Get Profile Usage

Where has this voice been used? Synth-history + segment counts per project.

Path Parameters

profile_id*Profile Id

Response Body

`application/json`

`application/json`

bash

curl -X GET "https://example.com/profiles/string/usage"

json

null

Get Profile Audio

Path Parameters

profile_id*Profile Id

Response Body

`application/json`

`application/json`

bash

curl -X GET "https://example.com/profiles/string/audio"

json

null

Lock Profile

Path Parameters

profile_id*Profile Id

Request Body

application/x-www-form-urlencoded

history_id*History Id

seed?integer|null

Response Body

`application/json`

`application/json`

bash

curl -X POST "https://example.com/profiles/string/lock" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'history_id=string'

json

null

Unlock Profile

Path Parameters

profile_id*Profile Id

Response Body

`application/json`

`application/json`

bash

curl -X POST "https://example.com/profiles/string/unlock"

json

null

Path Parameters

profile_id*Profile Id

Request Body

multipart/form-data

consent_audio*Consent Audio

consent_text*Consent Text

Response Body

`application/json`

`application/json`

bash

curl -X POST "https://example.com/profiles/string/consent" \
  -F consent_audio="string" \
  -F consent_text="string"

json

null

Path Parameters

profile_id*Profile Id

Response Body

`application/json`

`application/json`

bash

curl -X DELETE "https://example.com/profiles/string/consent"

json

null

List all voice gallery categories.

Response Body

`application/json`

bash

curl -X GET "https://example.com/gallery/categories"

json

null

List Voices

List voices in the gallery, optionally filtered by category or search.

Query Parameters

category?|

Filter by category

search?|

Search by name or character

limit?Limit

Range1 <= value <= 200

Default50

Response Body

`application/json`

`application/json`

bash

curl -X GET "https://example.com/gallery/voices"

json

null

Get Voice

Get a specific voice from the gallery.

Path Parameters

voice_id*Voice Id

Response Body

`application/json`

`application/json`

bash

curl -X GET "https://example.com/gallery/voices/string"

json

null

Update Voice

Update voice metadata — name, tags, is_favorite.

Path Parameters

voice_id*Voice Id

Request Body

application/json

[key: string]?any

Response Body

`application/json`

`application/json`

bash

curl -X PATCH "https://example.com/gallery/voices/string" \
  -H "Content-Type: application/json" \
  -d '{}'

json

null

Delete Voice

Delete a voice from the gallery.

Path Parameters

voice_id*Voice Id

Response Body

`application/json`

`application/json`

bash

curl -X DELETE "https://example.com/gallery/voices/string"

json

null

Search Youtube

Search a source site (via yt-dlp) for clips matching the user's query.

The query is user-supplied; the project ships no celebrity/character seed list. Users are responsible for the licensing of whatever they import.

Query Parameters

query*Query

User-supplied search terms or video title

category?Category

Free-form tag stored with results

Default"import"

max_results?Max Results

Range1 <= value <= 20

Default5

Response Body

`application/json`

`application/json`

bash

curl -X POST "https://example.com/gallery/search/youtube?query=string"

json

null

Download Youtube Clip

Download a clip from YouTube for voice cloning.

Query Parameters

video_url*Video Url

YouTube video URL

start_time?Start Time

Start time in seconds

Range0 <= value

Default0

duration?Duration

Clip duration in seconds

Range1 <= value <= 30

Default10

character_name*Character Name

Name to label this clip

category?Category

Free-form tag stored with the clip

Default"import"

description?Description

Optional description

Default""

Response Body

`application/json`

`application/json`

bash

curl -X POST "https://example.com/gallery/download?video_url=string&character_name=string"

json

null

Upload Voice Clip

Upload a voice clip directly to the gallery.

Request Body

multipart/form-data

name*Name

character?Character

Default""

category?Category

Default"import"

description?Description

Default""

audio*Audio

Response Body

`application/json`

`application/json`

bash

curl -X POST "https://example.com/gallery/upload" \
  -F name="string" \
  -F audio="string"

json

null

Save Voice As Profile

Save a gallery voice as a voice profile for cloning.

Path Parameters

voice_id*Voice Id

Query Parameters

profile_name*Profile Name

Name for the voice profile

Response Body

`application/json`

`application/json`

bash

curl -X POST "https://example.com/gallery/voices/string/save-as-profile?profile_name=string"

json

null

Preview Voice

Get a voice clip for preview playback.

Path Parameters

voice_id*Voice Id

Response Body

`application/json`

`application/json`

bash

curl -X GET "https://example.com/gallery/voices/string/preview"

json

null

Batch Delete Voices

Delete multiple voices by ID list.

Request Body

application/json

[key: string]?any

Response Body

`application/json`

`application/json`

bash

curl -X POST "https://example.com/gallery/voices/batch-delete" \
  -H "Content-Type: application/json" \
  -d '{}'

json

null

Voice To Profile

Create a voice profile from a gallery clip.

Path Parameters

voice_id*Voice Id

Response Body

`application/json`

`application/json`

bash

curl -X POST "https://example.com/gallery/voices/string/to-profile"

json

null

The seven use-case categories the gallery is organized by.

Response Body

`application/json`

bash

curl -X GET "https://example.com/archetypes/categories"

json

null

Preview Gallery Status

Consent state, coverage and freshness for the Settings line.

Response Body

`application/json`

bash

curl -X GET "https://example.com/archetypes/previews/status"

json

null

Set Preview Gallery

Turn pre-rendered previews on or off.

Turning it ON is the user's explicit yes to an outbound call, and is the only thing that ever starts one — there is no on-install background fetch. The featured set is pulled right here so the yes has a visible effect; failures are silent by design (fetch_featured swallows them) and leave previews rendering locally.

Request Body

application/json

enabled*Enabled

Response Body

`application/json`

`application/json`

bash

curl -X PUT "https://example.com/archetypes/previews" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true
  }'

json

null

Check Preview Gallery

Manual "check now" — bypasses the 24 h throttle, never the signature.

Response Body

`application/json`

bash

curl -X POST "https://example.com/archetypes/previews/check"

json

null

List Archetypes Endpoint

Filtered, paginated view over the archetype catalog.

q is a free-text substring match over the archetype name/instruct so a voice picker can search the entire several-hundred-voice catalog by typing (the facet filters alone can't reach a specific voice by name). Content-free and local — it just narrows the in-memory catalog.

Query Parameters

q?string|null

use_case?string|null

gender?string|null

age?string|null

pitch?string|null

accent?string|null

whisper?boolean|null

lang?string|null

featured?boolean|null

limit?Limit

Range1 <= value <= 500

Default60

offset?Offset

Range0 <= value

Default0

Response Body

`application/json`

`application/json`

bash

curl -X GET "https://example.com/archetypes"

json

null

Get Archetype Endpoint

Path Parameters

archetype_id*Archetype Id

Response Body

`application/json`

`application/json`

bash

curl -X GET "https://example.com/archetypes/string"

json

null

Preview Archetype State

Where the next /preview for this archetype would come from.

Touches neither the model nor the network, so a picker can label a voice ("may take a moment", "download a model first") before it commits to a request that may take 40 seconds or fail.

Path Parameters

archetype_id*Archetype Id

Response Body

`application/json`

`application/json`

bash

curl -X GET "https://example.com/archetypes/string/preview/state"

json

null

Preview Archetype

Serve a short preview clip — from the gallery, the cache, or the engine.

Path Parameters

archetype_id*Archetype Id

Query Parameters

local?Local

Bypass gallery audio after a client decode failure

Defaultfalse

Response Body

`application/json`

`application/json`

bash

curl -X GET "https://example.com/archetypes/string/preview"

json

null

Use Archetype

Materialize an archetype into a reusable voice profile.

Renders a reference sample (so the voice has a concrete identity and a preview) and inserts a voice_profiles row carrying the archetype's instruct + language. The profile then shows up everywhere voices are picked (Dub / Generate / Clone).

Never sourced from the voice gallery, no matter how cheap that would be: this WAV lands in VOICES_DIR as the profile's reference audio, so a downloaded, lossily-encoded MP3 would silently become the sample every future clone of this voice is built from. It renders locally or it fails.

Path Parameters

archetype_id*Archetype Id

Query Parameters

name?string|null

Response Body

`application/json`

`application/json`

bash

curl -X POST "https://example.com/archetypes/string/use"

json

null

Community Sources

The content repos the gallery loads from (default: omnivoice-gallery).

Response Body

`application/json`

bash

curl -X GET "https://example.com/community/sources"

json

null

Community Manifest

Query Parameters

refresh?Refresh

Defaultfalse

Response Body

`application/json`

`application/json`

bash

curl -X GET "https://example.com/community/manifest"

json

null

Community Items

Query Parameters

use_case?string|null

gender?string|null

type?string|null

lang?string|null

q?string|null

limit?Limit

Range1 <= value <= 500

Default60

offset?Offset

Range0 <= value

Default0

refresh?Refresh

Defaultfalse

Response Body

`application/json`

`application/json`

bash

curl -X GET "https://example.com/community/items"

json

null

Community Submit Url

Build the prefilled GitHub submission URL (server-free, local-first).

Query Parameters

type?Type

Default"preset"

source?string|null

Response Body

`application/json`

`application/json`

bash

curl -X GET "https://example.com/community/submit-url"

json

null

Community Preview

Serve every community preview through the authenticated same-origin API.

Path Parameters

item_id*Item Id

Query Parameters

local?Local

Bypass canonical gallery audio after decode failure

Defaultfalse

Response Body

`application/json`

`application/json`

bash

curl -X GET "https://example.com/community/items/string/preview"

json

null

Community Use

Materialize a community item into a reusable voice profile.

Preset → render through the archetype engine. Voice → download the (host-allow-listed, SHA-256-verified) reference clip. Both create a voice_profiles row usable everywhere voices are picked.

Path Parameters

item_id*Item Id

Query Parameters

name?string|null

Response Body

`application/json`

`application/json`

bash

curl -X POST "https://example.com/community/items/string/use"

json

null

Export Profile

Export a voice profile as a downloadable .omnivoice bundle (ZIP).

Path Parameters

profile_id*Profile Id

Response Body

`application/json`

`application/json`

bash

curl -X POST "https://example.com/marketplace/export/string"

json

null

Import Profile

Import a voice profile from a .omnivoice bundle.

Request Body

multipart/form-data

file*File

A .omnivoice bundle file

Response Body

`application/json`

`application/json`

bash

curl -X POST "https://example.com/marketplace/import" \
  -F file="string"

json

null

Publish To Marketplace

Publish a voice profile to the local marketplace directory.

This saves a .omnivoice bundle to the marketplace folder so other VoiceStudio instances on the same machine (or shared network drive) can discover and import it.

Path Parameters

profile_id*Profile Id

Query Parameters

tags?Tags

Comma-separated tags

Default""

Response Body

`application/json`

`application/json`

bash

curl -X POST "https://example.com/marketplace/publish/string"

json

null

Browse Marketplace

List available .omnivoice bundles in the local marketplace directory.

Query Parameters

search?|

Search by name or tags

Response Body

`application/json`

`application/json`

bash

curl -X GET "https://example.com/marketplace/browse"

json

null

Install From Marketplace

Import a voice profile from a bundle in the local marketplace directory.

Path Parameters

filename*Filename

Response Body

`application/json`

`application/json`

bash

curl -X POST "https://example.com/marketplace/install/string"

json

null

Remove From Marketplace

Remove a bundle from the local marketplace directory.

Path Parameters

filename*Filename

Response Body

`application/json`

`application/json`

bash

curl -X DELETE "https://example.com/marketplace/string"

json

null

Export Persona

Build + stream a .ovsvoice bundle for a profile.

Path Parameters

profile_id*Profile Id

Query Parameters

license_spdx?License Spdx

Default"LicenseRef-VoiceStudio-Personal"

tags?Tags

Default""

include_reference?Include Reference

Defaulttrue

Response Body

`application/json`

`application/json`

bash

curl -X POST "https://example.com/personas/export/string"

json

null

Import Persona

Create a new voice profile from a .ovsvoice (or legacy .omnivoice) bundle.

Request Body

multipart/form-data

file*File

Response Body

`application/json`

`application/json`

bash

curl -X POST "https://example.com/personas/import" \
  -F file="string"

json

null

Inspect Persona

Read a bundle's manifest + consent summary WITHOUT writing any file or row.

Request Body

multipart/form-data

file*File

Response Body

`application/json`

`application/json`

bash

curl -X POST "https://example.com/personas/inspect" \
  -F file="string"

json

null

Audio

Previous Page

Dubbing

Next Page