Voice Design API

Authentication and workspace

Use an organization API key with Authorization: Bearer $DIALT_API_KEY on https://api.dialt.com/v1/voice-design. The organization owns every resource. The API supports the same upload, preview, revision, save and publication operations as the Voice Design browser UI. Active team users can also author in their personal workspace with a personal key, but personal workspaces cannot upload recordings.

Design loop

1. GET /bases returns results, upload_enabled and the recording permission statement. Select an entry with available: true. Audio requires an explicit base ID; drafts may leave it null until a base is selected. Unavailable stock entries cannot be selected.
2. POST /revisions with the complete design below creates an immutable draft revision (201). Set parent to the previous revision ID for the next edit. A stale parent returns 409; read the latest revision before retrying. Omit parent to start a new draft.
3. POST /audio with base_voice, conditioning_prompt and text (1–500 characters) returns audio/wav. Listen, adjust, and repeat. It synthesizes the supplied text; it does not execute the assistant’s instructions.
4. POST /saved-designs with {"revision":"REVISION_UUID","name":"Garden guide"} keeps that exact version (201; identical repeats return 200).
5. GET /saved-designs returns the latest 200 workspace checkpoints plus available shared simulation designs, with the complete nested revision. GET /revisions returns the latest 200 workspace draft revisions. Both use results.

One Design ID across the website and API

After saving, expand API integration to find the Saved design ID and its Copy ID button. This is the id returned by POST /saved-designs. Read that exact saved version with GET /saved-designs/{design_id}, or open /voice-design?design={design_id} on the website in the matching workspace. Designs created through the API appear in the same Saved designs selector.

The Design ID identifies an immutable named version containing base reference, delivery, developer instructions and brain tier. Saving later edits creates a new Design ID; automatic drafts do not change the saved version. Publication, runtime and Evals reuse this same UUID. The nested revision.id identifies its draft snapshot, and revision.base_voice identifies its speaker reference; neither is a runtime selector.

curl "https://api.dialt.com/v1/voice-design/saved-designs/$DESIGN_ID" \
  -H "Authorization: Bearer $DIALT_API_KEY"

Publish and use a saved design

Organization members publish from an available base reference in Voice Design. The published voice is available to that organization's API keys, Playground and Evals. Personal authoring remains team-only. Ordinary stock voices remain available to all accounts.

Dialt-curated simulation packs are available to every authenticated personal and organization account, including non-team personal accounts. Their catalogue entries and saved designs include simulation_pack, a display name such as “Simulated patients”. They remain kind: "design" entries selected with mode.design in Playground, sessions and Evals, or design in exact-text speech. Anonymous reads remain stock-only. Playground groups them by pack with counts; Voice Design groups saved characters and speaker bases in their selectors. Open the saved character to load its complete scenario.

A shared design from another workspace returns read_only: true. Use it directly. Accounts with Voice Design authoring access can create a new revision with its base, delivery, instructions and tier, omitting parent, then save their own checkpoint. Your customization stays private and never changes the shared source. Shared use does not grant authoring or deletion access. You cannot delete, unpublish or claim another workspace's revision history. Pack membership is operator-managed and cannot be supplied in authoring requests. Removing a shared reference makes dependent private copies unavailable for speech until a new available base is selected; their text remains.

POST /saved-designs/{design_id}/publish with {} returns design and mode using the saved UUID. First publication returns 201; repeats return 200 with the same UUID. Editing a draft never changes a saved design. Saved design responses include a published boolean, replacing published_voice. Publication belongs to each saved design, even when designs share a base and delivery.

{
  "design": "SAVED_DESIGN_UUID",
  "mode": {"kind": "dialt", "design": "SAVED_DESIGN_UUID"}
}

Pass this mode to an ordinary call. design loads the saved base, delivery, instructions and brain tier together and conflicts with explicit voice, instructions and brain. Optional additional_instructions requires a design and appends scenario instructions after its saved instructions. Delivery goes only to synthesis; brain selects Dialt Fast or Smart and its rate. Authenticated GET /v1/voices includes your workspace's usable published designs and curated shared packs as kind: "design" entries, whose key is the saved UUID. Select them with mode.design. Stock voices, including those with kind: "designed", still use mode.voice. Your own designs stay private unless Dialt explicitly curates them for sharing. Use standard capacity; designs are not eligible for Spot, including standard fallback requests.

Use in Playground saves pending draft edits before loading the published checkpoint. Stock and saved design selection needs no confirmation or page reload; Playground retains separate stock settings and per-design additions for this workspace in the current tab. Saved instructions and a management link remain visible. A running design call keeps its configuration fixed until it ends. Evals accept the same UUID in target.design or simulator.design and snapshot the resolved configuration and additions. A caller design uses its saved tier and retains signed caller lifecycle and capability restrictions; callers without a design retain their pinned configuration. Supply caller-appropriate instructions: Dialt does not rewrite an assistant into a caller. A target design uses its saved brain by default; explicit comparison targets override it and record the effective brain. External targets cannot use a Dialt design. Text Evals assess instructions, not voice delivery.

Optional catalogue_group groups private characters without sharing them. Saved-design responses also expose optional display_name; the catalogue uses it as the voice name when set. The original checkpoint name and Design ID stay unchanged. These presentation fields do not grant access. Cross-organization access still requires explicitly curated simulation_pack sharing.

Revisions also save assistant_interruptions: "off" | "pauses" | "speech" (default "off"). Ordinary sessions and either Eval side inherit the saved value when omitted; an explicit session value overrides it, including "off". Playground loads the saved value into its visible interruption selector. Instructions decide when to interrupt; this experimental permission does not force interruptions. Text and multi-speaker sessions keep interruptions off. Resume inherits the effective session value and rejects changes. Python SDK 0.50.0 and older send explicit "off" by default, so pass the desired setting explicitly with those versions.

Without explicit comparison targets, target designs in one run must share a tier; ordinary targets count as Fast. Split mixed Fast/Smart cases into runs or choose explicit comparison targets.

A running session pins its complete configuration. Changing the design, voice, instructions or brain requires a new session. Resume retains the design and additions and rejects replacement configuration. Start, Eval execution and resume recheck availability and workspace authorization; unavailable designs fail without a stock fallback. Tools and response-specific controls retain their existing scope.

Revision input

{
  "name": "Garden guide",
  "brain": "fast",
  "assistant_interruptions": "off",
  "base_voice": null,
  "conditioning_prompt": "Warm, measured delivery with a relaxed pace.",
  "instructions": "Help callers plan their garden. Ask about sunlight first.",
  "parent": null
}

Delivery describes pace, pauses, emphasis, intonation and energy. The delivery prompt is the conditioning_prompt field: aim for 5–15 words; validation allows 1–500 printable characters, one line, without parentheses. Developer instructions describe the assistant’s role, tasks, policies and wording preferences (1–12,000 characters). Both mechanisms can affect speaking style; neither replaces Dialt’s platform rules or voice guidance. A base selects the speaker reference. brain selects fast (default) or smart for the design conversation and is saved with the revision. Audio samples synthesize supplied text without using a brain. Names accept 1–120 characters.

Organization voice snippets

Organization members and organization API keys can upload recordings inside Voice Design without manual approval. Personal workspaces cannot upload. Organization keys can also list and use their published designs through /v1/voices and mode.design. Playground and the runtime API consume the published design; they never create a clone.

POST /uploads accepts multipart fields clip, name (1–64 characters) and consent=true, matching the browser upload. Consent confirms permission from the speaker and rights holder to create and use this voice. Authorized audio is sent to the synthesis service to create a private voice reference. Use clean English mono or stereo WAV, FLAC, MP3 or OGG audio, up to 30 seconds and 16 MiB. Aim for 10–30 seconds. The returned id is a base reference for this designer only.

Upload creates the voice reference once so you can hear it before saving. Repeated uploads of the same recording in the same workspace and service reuse its base. Revisions, named saves and publications do not clone it again. Each saved design retains the complete configuration; shared acoustic caching is internal and never couples publication state. If preparation ends with an uncertain result, contact support before retrying; the recording is kept unavailable rather than silently registering it twice. Longer-recording fine-tuning is available by discussion: contact us.

Delete designs, voices and recordings

The website and organization API keys support the same deletion actions. Only resources in the selected workspace can be deleted; shared stock recordings are protected.

1. DELETE /saved-designs/{design_id}/publish unpublishes only this design (204, including repeats). It reports published: false; its UUID, text and base stay. New calls, resume and queued Evals cannot use it; admitted calls retain their snapshot. Publishing again uses the same UUID. Other saved designs remain unchanged.
2. DELETE /saved-designs/{design_id} removes a named checkpoint (204). Unpublish it first or the request returns 409. Revision history, other checkpoints and the base recording stay. A missing or previously deleted checkpoint returns 404.
3. DELETE /bases/{base_id} permanently removes your private voice identity, including an imported designed voice or uploaded clone, from the synthesis service (204). Unpublish every dependent saved design first or the request returns 409. Confirmed provider deletion releases its slot. Drafts and saved designs retain their text but need a new saved version with an available base to speak. Calls already using the identity may be interrupted. The website exposes this separately under Manage private voice identities with inline review; deleting a checkpoint alone never deletes its underlying identity.

The old publication-ID DELETE /voices/{voice_key} route and acoustic-only design_UUID voice selection are removed without compatibility aliases. Clone deletion first makes the base unavailable. A 503 means provider removal was not confirmed: retry deletion to finish, rather than uploading again. Successful clone deletion and unpublication can be repeated safely and return 204. Re-uploading after confirmed deletion creates a new base; old IDs never rebind. Historical metadata, revision text and session recordings are not purged by these operations. Unresolved registrations and legacy recordings need support.

Preparation and errors

Editing, saving and publishing are free. Live designer conversations and published-voice API calls use standard Dialt Fast ($0.065/min) or Smart ($0.085/min) credits; startup waiting is uncharged. Ordinary Playground remains free. Audio previews allow 60 attempts per workspace per UTC day, shared across browser and API use. The initial conversation warm-up and failed or unconfirmed generation attempts count. Exhaustion returns 429 with Retry-After.

Uploads wait for voice registration, and previews wait for synthesis. A 503 means preparation or synthesis did not complete. Do not blindly replay an uncertain generation. Audio and upload requests share a 10-per-minute actor limit (429 when exceeded). A 403 denies workspace or upload permission; a 404 hides an inaccessible or disabled base or revision. Provider credentials and recording URLs are never returned.

There is no public realtime designer-session endpoint yet. An agent supplies the design edits and sample text in this HTTP loop. The website provides the voice conversation.