---
title: Use with an AI agent
description: Generate Arabic voiceovers with Claude Code, Codex, and the official Sawtak Arabi skill.
---

Ask your agent to create Arabic audio with Sawtak Arabi. The official **arabic-voiceover** skill selects voices, generates a WAV, and saves it in your workspace. It is free to install; generation uses your Sawtak Arabi balance.

> Use Sawtak Arabi to generate a 20-second Saudi Najdi Arabic ad for my coffee shop. Read https://sawtakarabi.ai/docs/agent-skill and use the official skill. Reply in English.

## 1. Install the official skill

In Claude Code or Codex, ask your agent to install [SawtakArabi/skill](https://github.com/SawtakArabi/skill), or run:

```bash
npx skills add SawtakArabi/skill --skill arabic-voiceover -g -a claude-code -a codex
```

The installer requires Node.js/npm. Generation requires Python 3.10+ and the skill's Python dependencies; your agent can set those up. The skill uses the official OpenAI Python SDK with Sawtak Arabi's API.

Agents can read the [skill instructions directly](https://raw.githubusercontent.com/SawtakArabi/skill/main/skills/arabic-voiceover/SKILL.md). The [latest release](https://github.com/SawtakArabi/skill/releases/latest) includes a downloadable ZIP with the helper and its bundled dialect list. Resolve helper paths relative to the installed `SKILL.md`; do not guess an installation directory.

## 2. Connect your API key

Open [API Keys](/dashboard/api-keys), sign in or create an account, click **Create key**, enter a name such as `Claude voiceovers`, click **Create**, then **Copy** the key shown once. Configure `SAWTAK_API_KEY` in the environment used by your agent. [Authentication](/docs/authentication#configure-the-key-locally) provides exact terminal instructions. Check [Billing](/dashboard/billing) if your balance needs funding.

If the key is missing, the agent should ask:

> Open https://sawtakarabi.ai/dashboard/api-keys and sign in. Click Create key, give it a name, and copy the key shown once. Set it using the terminal or secret-field instructions below—not in this chat. Tell me when it’s ready and I’ll continue your voiceover.

The agent should provide the appropriate Bash/Zsh command from [Authentication](/docs/authentication#configure-the-key-locally), or instructions for its supported secret field. Set the environment variable before launching a local agent; an already-running session does not inherit changes in another terminal. Do not paste the key into ordinary chat, source files, or a public repository. No permission-selection step is needed for dashboard-created keys.

A browsing-only chat can read the instructions but cannot run the helper. Use Claude Code, Codex, or another environment that can execute Python and reach the API. While setup is pending, the agent can still prepare your script and find dialect names.

## 3. Generate your narration

Ask naturally, or invoke `/arabic-voiceover` in Claude Code or `$arabic-voiceover` in Codex. The agent should follow this sequence:

1. Preserve your script and requested dialect, or draft the narration when asked. Reply in the language of your prompt unless you request another reply language.
2. Check setup with `doctor`. This makes no paid synthesis request.
3. Resolve dialect names with `dialects`, then query `voices` and choose a returned voice with `status: ready`. Voice discovery requires your API key; the bundled dialect list does not.
4. Write the narration to a UTF-8 file and run `generate`. Include `--enhance-pronunciation` unless you ask to disable it.
5. Return the WAV link and measured duration. Distinguish file validation from a content check or listening review. For a video request, integrate the audio into the requested video.

For example, with `skill-dir` replaced by the actual installed skill directory:

```bash
python3 <skill-dir>/scripts/generate.py doctor
python3 <skill-dir>/scripts/generate.py dialects --search Najdi
python3 <skill-dir>/scripts/generate.py voices --dialect saudi-najdi --use-case advertisement --limit 5
python3 <skill-dir>/scripts/generate.py generate \
  --voice <returned-ready-voice-id> --text-file narration.txt \
  --output narration.wav --enhance-pronunciation
```

If the use-case filter finds no voices, try the same dialect without that filter; do not silently switch dialects. Use `voices --details` for descriptions and preview links. `--sharing-status public` or `private` limits visibility. The bundled dialect labels are a snapshot; live catalog results determine current availability.

## If generation is interrupted

The helper saves IDs and settings in `narration.json` and keeps received audio as `narration.partial.wav`. A partial WAV is incomplete narration even when it plays. Inspect the saved `operation_id` with:

```bash
python3 <skill-dir>/scripts/generate.py inspect <operation-id>
```

Inspection reads status and billing; it does not generate or download audio. A missing operation is unknown. The agent must not automatically start another paid generation. Reuse successful files and ask before regenerating uncertain work.

For direct API integrations, see [Quickstart](/docs/quickstart), [Text to speech](/docs/text-to-speech), [Voices](/docs/voices), and [Operations and retries](/docs/operations). Machine-readable guides are indexed in [llms.txt](/llms.txt) and collected in [llms-full.txt](/llms-full.txt).