Agent recipes

Use these recipes when an agent needs to integrate the API without guessing. Set the environment first, use the OpenAPI contract for exact schemas, and treat the verification step as part of the task.

export SAWTAK_API_BASE_URL="https://api.sawtakarabi.ai/v1"
export SAWTAK_API_KEY="<API_KEY>"

Generate a WAV file

Goal: create a playable Arabic WAV file from text.

curl --fail --show-error "$SAWTAK_API_BASE_URL/audio/speech" \
  -H "Authorization: Bearer $SAWTAK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"arabic-tts-1","input":"مرحباً بك","response_format":"wav"}' \
  --output speech.wav

file speech.wav

Done when: the request exits successfully and file speech.wav identifies a WAV audio file. Do not retry 400, 401, 402, or 403 unchanged. For 429 and transient 5xx responses, follow Request limits.

Transcribe an audio file

Goal: print an Arabic transcript from a local audio file.

curl --fail --show-error "$SAWTAK_API_BASE_URL/audio/transcriptions" \
  -H "Authorization: Bearer $SAWTAK_API_KEY" \
  -F model="arabic asr" \
  -F [email protected] \
  -F response_format=json

Done when: the JSON response contains text. Keep the original file unchanged so a failed upload can be diagnosed or retried safely.

Clone a voice and wait for it

Goal: obtain a ready private voice ID for later synthesis.

1. Send the multipart request in Voice cloning. It requires one reference file, a name, and JSON labels containing dialect.
2. Save the returned id.
3. Poll GET /v1/voices/{id} with the same Bearer key until status is ready.
4. Use that ID as voice in the text-to-speech request.

Done when: the voice response reports status: "ready". Never substitute a different voice when cloning is still processing or fails.

Diagnose a failed request

Goal: choose the next safe action from an API failure.

1. Read the HTTP status and error.code.
2. Save request_id if present.
3. Correct client input for 400, replace credentials for 401, add balance for 402, and use a key with the required scope for 403.
4. For 429, wait for Retry-After and use bounded exponential backoff with jitter.
5. Retry only idempotent work after a transient 5xx; avoid duplicating a voice-creation request.

The canonical machine schema is OpenAPI v1. Use it over inferred fields or values.