---
title: Agent recipes
description: Deterministic workflows for Claude, Codex, and other coding agents.
---

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.

```bash
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.

```bash
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](/docs/limits).

## Transcribe an audio file

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

```bash
curl --fail --show-error "$SAWTAK_API_BASE_URL/audio/transcriptions" \
  -H "Authorization: Bearer $SAWTAK_API_KEY" \
  -F model="arabic asr" \
  -F file=@recording.wav \
  -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](/docs/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](https://api.sawtakarabi.ai/v1/openapi.json). Use it over inferred fields or values.