Skip to main content
The Voice primitive lets an agent speak in a cloned voice it is authorized to use, and lets a human create and manage those voices under an explicit consent record. On top of it, the digital-twin clone turns a reference image + a cloned voice + a script into a lip-synced talking video. There are two surfaces with deliberately different trust levels:
  • Agent surface (API key): synthesize speech in a voice the agent already owns, list voices, generate talking videos.
  • Human surface (signed-in session): create (clone) and revoke voices. These record a legal consent affirmation, so they require a human session — not just an API key.
Cloning and revoking a voice are human-only. Run naive auth session-login first (see Authentication). Synthesis and talking-video generation work with a normal agent API key.

​
Cloning a voice (human-only)

# Establish a human session, then clone
naive auth session-login

naive voice clone \
  --file ./sample.wav \
  --name "Founder VO" \
  --consent-type self \
  --authorized-uses email,video \
  --i-affirm \
  --wait
Key options:
OptionRequiredDescription
--file <path>YesAudio sample to clone from
--name <name>YesDisplay name for the voice
--i-affirmYesYou affirm you have the right to clone this voice
--consent-type <type>Yesself, third_party_attested, or third_party_verified
--authorized-uses <list>NoComma-separated allowed uses, e.g. email,video
--consenter-name <name>For third-partyName of the person who consented
--consenter-email <email>For third-partyConsenter email (required for third-party consent)
--accept-tosFor third_party_attestedAccept the voice-cloning Terms of Service
--scope <company|agent>NoOwnership scope (default company)
--waitNoPoll until the clone is ready
For third-party voices the consenter receives a verification link; the voice stays in a draft/pending state until consent is confirmed. authorized_uses is enforced at synthesis time — a voice cloned for email only will refuse a video use.

​
Revoking a voice (human-only, irreversible)

naive voice revoke <voice-id> --yes --reason "no longer authorized"
This irreversibly erases the voice and its underlying audio, and marks the consent record revoked. Any later synthesis attempt returns voice_revoked.

​
Synthesizing speech (agent surface)

# List voices available to you
naive voice list

# Speak in a voice you own
naive voice say --voice <voice-id> --text "Thanks for booking with us." --out hello.mp3

# Check a past synthesis
naive voice status <synthesis-id>
REST: 
curl -X POST https://api.usenaive.ai/v1/voice/synthesize \
  -H "Authorization: Bearer nv_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "voice_id": "voice-uuid", "text": "Thanks for booking with us.", "use": "email" }'

const res = await fetch("https://api.usenaive.ai/v1/voice/synthesize", {
  method: "POST",
  headers: { "Authorization": "Bearer nv_sk_your_key", "Content-Type": "application/json" },
  body: JSON.stringify({ voice_id: "voice-uuid", text: "Thanks for booking with us.", use: "email" }),
});
const { synthesis_id, url, credits, char_count } = await res.json();
REST endpointPurpose
POST /v1/voice/synthesizeSynthesize speech (returns a presigned audio URL, valid 24h)
POST /v1/voice/streamStream synthesized audio
GET /v1/voice/voicesList voices available to the caller
GET /v1/voice/synthesis/:idStatus of a past synthesis
The use field must fall within the voice’s authorized_uses. Text is capped at 5000 characters per call. The audio URL is presigned and expires after 24 hours — re-run say if it lapses.

​
Digital twin — talking video

naive clone generate produces a lip-synced talking video of a real person from a reference image, an existing cloned voice, and a script. The voice supplies both the audio and the consent record; the image supplies the likeness (which you must separately affirm). 
naive clone generate \
  --voice <voice-id> \
  --image ./founder.jpg \
  --text "Welcome to the launch — here's what's new this week." \
  --scene "cliffside pool deck at golden hour" \
  --i-affirm \
  --wait

# Check a generation job
naive clone status <job-id>
OptionRequiredDescription
--voice <id>YesAn existing cloned voice profile (its consent + audio)
--image <path|url>YesReference image — a local file or a public https URL
--text <script>YesThe script the cloned voice should speak
--i-affirmYesYou affirm the depicted person consented to this likeness animation
--scene <description>NoOptional scene/relight description
--waitNoPoll until the job completes
REST: 
curl -X POST https://api.usenaive.ai/v1/clone/generate \
  -H "Authorization: Bearer nv_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_id": "voice-uuid",
    "image_url": "https://example.com/founder.jpg",
    "text": "Welcome to the launch.",
    "scene": "golden hour",
    "quality": "max",
    "i_affirm": true
  }'
# Poll: GET /v1/clone/:job_id  (quality: "max" = best lip-sync, "fast" = cheaper)
Generation is async and runs through the unified jobs system; the finished video is auto-ingested into your Media Asset Manager. Every voice is backed by a consent record that captures who consented, the affirmation text, and the authorized uses. This is enforced end to end:
  • Cloning requires --i-affirm and a consent_type; third-party voices require the consenter’s verification.
  • Synthesis and talking-video generation are refused if the voice was revoked (voice_revoked) or the declared use is outside the authorized set.
  • The digital-twin clone additionally requires an explicit likeness affirmation for the depicted person.

​
Billing

  • Synthesis is billed per synthesis based on character count (returned as credits on each say).
  • Talking-video generation is billed on completion like other video jobs — failed jobs cost nothing.
  • Cloning and revoking voices are free; you pay only when you synthesize or generate.
Account Kits can enable/disable the voice primitive per user, and the human-only clone/revoke surface is always gated behind a signed-in session.