Quickstart

Make your first transcription or synthesis API call in under 5 minutes. Both products use the same key, the same billing balance, and the same locale codes.

1. Get your API key

Sign up at developers.phonetico.ai and create an API key from the API Keys page. If your email already has a Phonetico account, sign in with it instead and add developer access.

2. Transcribe audio

The simplest path is the multipart upload endpoint - POST /v1/asr/upload. Send the audio file directly with your API key as a Bearer token.

curl -X POST https://api.phonetico.ai/v1/asr/upload \
  -H "Authorization: Bearer pk_live_your_key_here" \
  -F "[email protected]" \
  -F "localeCode=amh"

Response

A successful response includes the transcript, the duration of the audio that was processed, and a confidence score.

{
  "transcript": "አንድነታችን ነው፣ ጸንቶ የሚያቆመን",
  "localeCode": "amh",
  "latencyMs": 612,
  "audioDurationMs": 3580,
  "confidence": 0.95
}

3. Synthesize text

Pick a preset voice from GET /v1/tts/voices and submit text. Today only Tigrinya (tir) has a deployed finetune; voice tir_phonetico_01 is seeded and ready. Other locales return 503 until their models land.

curl -X POST https://api.phonetico.ai/v1/tts \
  -H "Authorization: Bearer pk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "ምስ መኪና ስለዘላተሙኒ ውነይ ስሒተ።",
    "language": "tir",
    "voice": { "preset": "tir_phonetico_01" },
    "options": { "qualityTier": "balanced" }
  }' | jq -r '.audio' | base64 -d > synthesized.wav

Response

{
  "audio": "<base64 WAV bytes>",
  "format": "wav",
  "sampleRate": 24000,
  "outputAudioDurationMs": 820,
  "latencyMs": 6240,
  "rtf": 7.61,
  "voice": "tir_phonetico_01",
  "seed": 195950210,
  "qualityTier": "balanced"
}

Quality tiers. fast (1× cost), balanced (2× cost), quality (3× cost). Higher tiers run more diffusion steps; billing scales with GPU work.

Word-level timestamps (optional)

Need timing for each word, for captions, search-within-audio, or click-to-seek UIs? Send the JSON endpoint with wordTimestamps: true. The response gains a wordTimestamps array of {word, start, end} entries (seconds).

{
  "transcript": "አንድነታችን ነው፣ ጸንቶ የሚያቆመን",
  "localeCode": "amh",
  "audioDurationMs": 3580,
  "latencyMs": 1420,
  "confidence": 0.95,
  "wordTimestamps": [
    { "word": "አንድነታችን", "start": 0.20, "end": 1.10 },
    { "word": "ነው",       "start": 1.24, "end": 1.56 },
    { "word": "ጸንቶ",      "start": 1.74, "end": 2.22 },
    { "word": "የሚያቆመን",  "start": 2.36, "end": 3.42 }
  ]
}

Supported locales

ASR and TTS support are tracked separately. See the Languages page for details and beta status.

Custom voice cloning (optional)

Beyond preset voices, you can clone any voice from a short reference clip. Send voice.reference with the clip (base64) plus its exact transcript and rightsAttestation: true. Before the first custom-reference call on a new key, accept the rights attestation from the API Keys page (one-time per key). Without it, calls 412 with attestation_required.

# Encode the reference clip and the target text
REF_AUDIO=$(base64 -i voice-sample.wav)
curl -X POST https://api.phonetico.ai/v1/tts \
  -H "Authorization: Bearer pk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d @- <<JSON > synthesized.json
{
  "text": "ምስ መኪና ስለዘላተሙኒ ውነይ ስሒተ።",
  "language": "tir",
  "voice": {
    "reference": {
      "audio": "$REF_AUDIO",
      "transcript": "the exact text spoken in voice-sample.wav",
      "rightsAttestation": true
    }
  },
  "options": { "qualityTier": "balanced" }
}
JSON

# Extract the WAV
cat synthesized.json | jq -r '.audio' | base64 -d > synthesized.wav

Response shape is the same as the preset path; only voice differs (returns "custom" instead of a preset ID).

Next steps

• API Reference. Full endpoint specification (transcribe + synthesize)
• Authentication. API key best practices
• Audio Guide. Recording quality tips