Title: Documentation references invalid legacy Audio/TTS model (openai-audio)

[humair-m]

Summary

Your public documentation contains examples for text-to-speech (TTS/Audio) that reference the model identifier openai-audio and a simple GET pattern (https://text.pollinations.ai/{prompt}?model=openai-audio&voice={voice}). Those examples are currently not reproducible: both the GET style example and the OpenAI-style POST to /openai return a 404 with the message:

{"error":"Model not found: openai-audio. This is our legacy API - for the full model list and new features, visit https://enter.pollinations.ai","status":404}

This is confusing for integrators and prevents adoption of TTS/Audio features. The docs imply openai-audio is a working TTS/Audio model, but the live /models registry shows no audio models available on the text.pollinations.ai endpoint. Please update docs or the API behavior to remove this mismatch.

---

Why this matters / Impact

• New and existing users cannot reproduce the official TTS/Audio examples, wasting time and causing loss of trust.
• Automation and scripts built from the docs will fail in production (404 on deploy).
• Third-party libraries and tutorials referencing your docs will propagate broken examples.
• The error message refers users to enter.pollinations.ai but the docs still show the legacy examples — this split messaging causes additional confusion.

---

Exact reproduction (tested with curl)

1. Verified model registry (no audio models present):

curl -s "https://text.pollinations.ai/models" | head -n 80

Partial output captured:

[{"name":"deepseek","description":"DeepSeek V3.1","maxInputChars":10000,"reasoning":true,"tier":"seed","community":false,"input_modalities":["text"],"output_modalities":["text"],"tools":true,"aliases":["deepseek-v3","deepseek-v3.1","deepseek-reasoning","deepseek-r1-0528"],"vision":false,"audio":false},
 {"name":"gemini","description":"Gemini 2.5 Flash Lite","tier":"seed","community":false,"input_modalities":["text","image"],"output_modalities":["text"],"tools":true,"aliases":["gemini-2.5-flash-lite"],"vision":true,"audio":false},
 {"name":"gemini-search","description":"Gemini 2.5 Flash Lite with Google Search","tier":"seed","community":false,"input_modalities":["text","image"],"output_modalities":["text"],"tools":true,"aliases":["searchgpt","geminisearch"],"vision":true,"audio":false},
 {"name":"mistral","description":"Mistral Small 3.2 24B","tier":"seed","community":false,"input_modalities":["text"],"output_modalities":["text"],"tools":true,"aliases":["mistral-small-3.1-24b-instruct","mistral-small-3.1-24b-instruct-2503","mistral-small-3.2-24b-instruct-2506"],"vision":false,"audio":false},
 {"name":"openai","description":"OpenAI GPT-5 Nano","tier":"anonymous","community":false,"input_modalities":["text","image"],"output_modalities":["text"],"tools":true,"maxInputChars":7000,"aliases":["gpt-5-mini"],"vision":true,"audio":false},
 {"name":"openai-fast","description":"OpenAI GPT-4.1 Nano","tier":"anonymous","community":false,"input_modalities":["text","image"],"output_modalities":["text"],"tools":true,"maxInputChars":5000,"aliases":["gpt-5-nano"],"vision":true,"audio":false},
 ...
]

Note: audio:false for the visible entries above; no audio-capable models were returned in this snippet.

2. GET TTS/Audio example:

# Example attempted:
https://text.pollinations.ai/Hello%20world?model=openai-audio&voice=nova

# Response:
{"error":"Model not found: openai-audio. This is our legacy API - for the full model list and new features, visit https://enter.pollinations.ai","status":404}

3. POST TTS/Audio example (OpenAI-style):

curl -s -X POST "https://text.pollinations.ai/openai" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"openai-audio",
    "modalities":["text","audio"],
    "audio": {"voice":"alloy","format":"mp3"},
    "messages":[
      {"role":"system","content":"You are a text-to-speech synthesizer."},
      {"role":"user","content":"Hello world. This is a test."}
    ]
  }' --output out.mp3

Response printed to terminal:

{"error":"Model not found: openai-audio. This is our legacy API - for the full model list and new features, visit https://enter.pollinations.ai","status":404}

---

Expected behavior

• The docs should either:

  • Provide working TTS/Audio examples that use currently available model identifiers and voices (matching /models output), OR
  • Mark the openai-audio pattern as deprecated and clearly show the migration path and examples using the new endpoint/model identifiers (with versioned examples and timelines).

• The /models endpoint should return at least one audio-enabled model (with "audio": true) if TTS/Audio is publicly supported on that endpoint — otherwise the docs should not reference TTS/Audio examples for text.pollinations.ai GET/POST endpoints.

• Error message should be actionable: return a 4xx with details suggesting the /models endpoint to query, or include a short link to the replacement docs for migration.

---

Suggested documentation changes (concrete)

1. Update GET example in docs:

Current (broken):

GET https://text.pollinations.ai/{URL-encoded prompt}?model=openai-audio&voice=nova

Suggested replacement (example — replace audio-model-name with the model shown by /models that has "audio": true):

# Minimal GET example (use ASCII hyphen, URL-encode prompt)
GET https://text.pollinations.ai/Hello%20world?model=audio-model-name&voice=nova&format=mp3
# Example curl:
curl -s "https://text.pollinations.ai/Hello%20world?model=audio-model-name&voice=nova&format=mp3" -o hello.mp3

2. Update POST example (OpenAI style) with clear fields and sample response:

POST https://text.pollinations.ai/openai
{
  "model":"audio-model-name",
  "modalities":["text","audio"],
  "audio":{"voice":"alloy","format":"mp3","sample_rate":24000},
  "messages":[
    {"role":"system","content":"TTS/Audio system"},
    {"role":"user","content":"This text will be returned as an MP3 audio file."}
  ]
}

Include a small note on expected headers and response behavior: Content-Type: audio/mpeg or whether you return a JSON with a pre-signed URL.

3. Add a "TTS/Audio / Models" doc page that:

   • Lists currently supported audio models and voices (pulled from /models).
   • Shows curl examples for both GET and POST, with variants for short/long text.
   • Notes about hyphen/character encoding pitfalls (explicitly call out non-ASCII hyphen issues).
   • Clearly describes rate limits, max input char counts (for TTS/Audio), and audio output formats supported (mp3, wav, opus).

4. Add machine-readable deprecation header for any legacy examples, e.g., X-Pollinations-Deprecated: openai-audio; replacement=audio-v2; removal-date=2025-12-31.

---

Suggested API/server behavior improvements

• When a model identifier is deprecated/removed, return a 400 with a JSON payload that includes:

  • valid_models_url (link to /models)
  • message explaining deprecation and replacement
  • suggested_models (if mapping exists) Example:

  {
    "error":"Model not found: openai-audio",
    "message":"Model 'openai-audio' is deprecated. See https://text.pollinations.ai/models for current models.",
    "valid_models_url":"https://text.pollinations.ai/models",
    "suggested_models":["audio-v2","voice-alloy"]
  }
  

• Add /models fields audio and voices (if not already present) so clients can discover TTS/Audio capabilities programmatically, e.g.:

{
  "name":"audio-v2",
  "description":"TTS/Audio engine v2",
  "input_modalities":["text"],
  "output_modalities":["audio"],
  "audio": true,
  "voices": ["alloy", "nova", "fable"],
  "maxInputChars":20000
}

---

Minimal reproduction (what I ran, copy-paste)

# 1) Check models
curl -s "https://text.pollinations.ai/models" | head -n 80

# 2) Attempt GET TTS/Audio (broken example from docs)
curl -s "https://text.pollinations.ai/Hello%20world?model=openai-audio&voice=nova" -o hello.mp3 || echo "failed"

# 3) Attempt POST TTS/Audio (OpenAI-style)
curl -s -X POST "https://text.pollinations.ai/openai" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"openai-audio",
    "modalities":["text","audio"],
    "audio": {"voice":"alloy","format":"mp3"},
    "messages":[
      {"role":"system","content":"You are a text-to-speech synthesizer."},
      {"role":"user","content":"Hello world. This is a test."}
    ]
  }' --output out.mp3 || echo "failed"

Observed terminal errors are included above in the issue.

---

Proposed PR text (short)

If you prefer a ready-to-copy PR body for the docs repository:

Fix: Replace legacy openai-audio TTS/Audio examples with current model usage and add a TTS/Audio discovery section.

• Remove GET/POST examples referencing openai-audio.
• Add a /models discovery example and programmatic voice listing.
• Add concrete curl GET and POST examples that use an audio model and voice names returned by /models.
• Add a "Migration" snippet for anyone still using openai-audio.

---

Request / Ask of maintainers

1. Please confirm whether TTS/Audio is intended to be publicly supported on text.pollinations.ai or if it has been moved to another host/entrypoint (enter.pollinations.ai).
2. If TTS/Audio is still supported, please publish a short, working example (GET and POST) in the docs that exactly matches what the /models endpoint returns (a canonical, copy-paste example).
3. If openai-audio is deprecated, please mark it explicitly in the docs and provide migration guidance.
4. Please add a short line to /models or the docs explaining where to find up-to-date voice names and audio formats.

---

Labels you may want to add

docs, bug, api, TTS/Audio, high priority, needs triage

---

Environment / Other metadata

• Endpoint tested: https://text.pollinations.ai (GET /models, GET TTS/Audio, POST /openai)
• Client used: curl on Linux (Ubuntu) shell
• Date tested: 2025-12-19
• Exact error returned from server:

{"error":"Model not found: openai-audio. This is our legacy API - for the full model list and new features, visit https://enter.pollinations.ai","status":404}

---