Use with an AI agent

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 skillCopy Anchor Link

In Claude Code or Codex, ask your agent to install SawtakArabi/skill, or run:

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. The latest release 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 keyCopy Anchor Link

Open 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 provides exact terminal instructions. Check 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, 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 narrationCopy Anchor Link

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:

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 interruptedCopy Anchor Link

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:

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, Text to speech, Voices, and Operations and retries. Machine-readable guides are indexed in llms.txt and collected in llms-full.txt.