Preface¶

When building product demos, accessibility screen reader content, or phone IVR prompt tones, the common workflow is: write the copy, then go to the platform console to click “Generate Speech” once, or cobble together a script that calls the OpenAI Audio API on your own. When the copy changes, the voice changes, or you need to generate dozens of prompt tones in batch, scripts and parameters easily get scattered across different places, making results hard to reproduce.

OpenAI provides an Agent Skill named speech in its official openai/skills repository. It packages Text-to-Speech into a reusable SKILL.md workflow, paired with a CLI tool (scripts/text_to_speech.py). This allows tools that support Agent Skills like Cursor, Codex CLI, and Claude Code to call the OpenAI Speech API in a unified, standardized way once given clear copy, and output audio files.

What is this¶

speech is one of OpenAI’s officially curated skills, located at:
https://github.com/openai/skills/tree/main/skills/.curated/speech

Its positioning is straightforward: when users need narration, product voiceovers, accessibility screen reader content, IVR/audio prompts, or batch speech generation, the Agent will read this Skill, prioritize using the built-in CLI to call the OpenAI Audio API (POST /v1/audio/speech), and generate audio files. Custom voice cloning is outside the scope of this Skill.

The default model is gpt-4o-mini-tts-2025-12-15, and the default voice is cedar. For a brighter tone, the official recommendation is to use marin first.

Core Features and Highlights¶

Based on the official SKILL.md and references/ documentation, its main capabilities are as follows:

Single and batch processing paths
Use speak for a single piece of copy; use speak-batch for multiple lines/multiple files (using a temporary JSONL file with one task per line). The Skill has a clear decision tree to prevent the Agent from needing to write ad-hoc scripts every time.
Built-in reproducible CLI
The entry point is scripts/text_to_speech.py, which supports speak, speak-batch, and list-voices. The official requirement is to use this CLI first, do not modify the script arbitrarily, and do not write one-off gen_audio.py scripts unless the user explicitly requests it.
Style instructions
For the GPT-4o mini TTS series, you can use the instructions field to describe voice temperament, tone, speaking speed, emotion, pauses, and emphasis, etc. This field is not supported by tts-1 / tts-1-hd, and the CLI will issue a warning and discard it.
Scenario-based reference templates
The repository has split reference documents by use case: narration (narration.md), product voiceover (voiceover.md), IVR (ivr.md), accessibility screen reader content (accessibility.md), as well as prompt writing guides (prompting.md, sample-prompts.md).
Clear output and rate limit conventions
The default output format is mp3, with options including opus, aac, flac, wav, and pcm. The maximum input length per request is 4096 characters. The default and upper limit for batch requests is 50 requests per minute (--rpm maximum 50).

Installation and Activation¶

Install the Skill¶

This Skill follows the universal SKILL.md format and can be installed using Vercel’s skills CLI. The common command is:

npx skills add openai/skills --skill speech

When installing for specific tools, you can specify the agent, for example:

npx skills add openai/skills --skill speech --agent cursor
npx skills add openai/skills --skill speech --agent codex
npx skills add openai/skills --skill speech --agent claude-code

You can also clone the repository manually and copy skills/.curated/speech to the skills directory of your target tool. Common Cursor paths include the project-level .agents/skills/ or the user-level ~/.cursor/skills/. For Codex, the CLI documentation defaults to placing skills in $CODEX_HOME/skills/ (default ~/.codex).

After installation, you can prompt in the chat to “use speech to synthesize this copy into audio”, or use explicit calls like /speech according to the tool’s conventions. The Agent will determine whether to trigger based on the Skill’s description.

Dependencies and Environment Variables¶

To actually call the API, you need:
1. Install the openai Python package (the official recommendation is to use uv):

    uv pip install openai

If you don't have `uv`:

    python3 -m pip install openai

Set the environment variable OPENAI_API_KEY (create one at OpenAI API Keys). Do not paste the full key into your chat; just inform the Agent that “it has been configured locally” after setting it up locally.

Typical Usage Examples¶

The following commands come from the official references/cli.md. First set the CLI path, taking Codex’s default installation location as an example:

export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
export TTS_GEN="$CODEX_HOME/skills/speech/scripts/text_to_speech.py"

1. Dry-run first (no API call)¶

python "$TTS_GEN" speak --input "Test" --dry-run

The --dry-run flag only prints the request payload, no network connection is required, and the openai package does not need to be installed. It is suitable for checking whether parameters are correct.

2. Generate a single narration¶

uv run --with openai python "$TTS_GEN" speak \
  --input "Today is a wonderful day to build something people love!" \
  --voice cedar \
  --instructions "Voice Affect: Warm and composed. Tone: upbeat and encouraging." \
  --response-format mp3 \
  --out speech.mp3

Without uv:

python "$TTS_GEN" speak --input "Hello" --voice cedar --out speech.mp3

View available built-in voices:

python "$TTS_GEN" list-voices

The official built-in voices include: alloy, ash, ballad, cedar, coral, echo, fable, marin, nova, onyx, sage, shimmer, verse.

3. Batch generate IVR prompt tones¶

mkdir -p tmp/speech
cat > tmp/speech/jobs.jsonl << 'JSONL'
{"input":"Thank you for calling. Please hold.","voice":"cedar","response_format":"mp3","out":"hold.mp3"}
{"input":"For sales, press 1. For support, press 2.","voice":"marin","instructions":"Tone: clear and neutral. Pacing: slow.","response_format":"wav"}
JSONL

python "$TTS_GEN" speak-batch --input tmp/speech/jobs.jsonl --out-dir out --rpm 50
rm -f tmp/speech/jobs.jsonl

Each line in the JSONL file can override parameters such as model, voice, response_format, speed, instructions, and out. The official recommendation is to store temporary files in tmp/speech/ and delete them after running; do not commit them to the repository. Final outputs can be placed in output/speech/ or specified using --out / --out-dir.

4. Prompt writing for Agents¶

The Skill requires: first collect “the original text (verbatim), voice, style, format, and constraints”, then organize the style into short tag descriptions, do not rewrite the original text. For example:

Input text: "Welcome to the demo. Today we'll show how it works."
Instructions:
Voice Affect: Warm and composed.
Tone: Friendly and confident.
Pacing: Steady and moderate.
Emphasis: Stress "demo" and "show".

When iterating, only change one item at a time (voice, speaking speed, or instructions) to facilitate comparison. After synthesizing important segments, it is recommended to listen to them manually to check clarity, rhythm, and whether proper nouns are pronounced correctly.

Applicable Scenarios and Notes¶

Applicable scenarios:
- Product demo / explainer video voiceovers
- Application guides, help pages, and accessibility screen reader content
- Batch generation of phone IVR and customer service prompt tones
- Automated pipelines that require consistent voice and parameters and can be run repeatedly

Notes:
- You must be connected to the internet and have a valid OPENAI_API_KEY configured; offline environments can only run --dry-run.
- Custom voice creation is not supported; only built-in voices can be used.
- The maximum length of a single text input is 4096 characters. For longer content, you need to split it into chunks or use batch processing.
- instructions only takes effect for GPT-4o mini TTS series models; style instructions will be ignored when switching to tts-1 / tts-1-hd.
- When targeting end users, the official requirement is to clearly inform them that “this speech was generated by AI”.
- Do not modify scripts/text_to_speech.py; when capabilities are missing, first ask the user before deciding whether to write an additional script.

Summary¶

The speech Skill packages OpenAI’s Text-to-Speech capabilities into an installable, reproducible Agent workflow: use speak for single requests, use JSONL + speak-batch for batch processing, with clear default models and voices, and includes reference templates for narration, voiceover, IVR, accessibility, and more. For developers who frequently need to create demo voiceovers, prompt tones, or automate multimedia content, it is more reliable than cobbling together API calls ad-hoc every time.

Official address: https://github.com/openai/skills/tree/main/skills/.curated/speech

Using OpenAI Speech Skill to synthesize reusable voice from text