Sync HTTP

Use the sync TTS endpoint when the text is short enough for a request-response flow and your product can wait for the audio before continuing. For long text, batch work, or user-visible queues, use Async Jobs.

POST /api/open/v1/speech/tts
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

Request

{
  "text": "Hello from FishSpeech.",
  "voiceId": "YOUR_VOICE_ID",
  "format": "mp3"
}

Common fields:

reference_id and modelId are legacy aliases for the same voice row id. New clients should send voiceId and keep aliases only while migrating older code.

curl https://fishaudio.org/api/open/v1/speech/tts \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello from FishSpeech.","voiceId":"YOUR_VOICE_ID","format":"mp3"}' \
  --output speech.mp3

Response

When cache is false or omitted, successful responses return binary audio. When cache is true, successful responses return JSON metadata:

{
  "audio_url": "https://example.com/generated.mp3",
  "credits_used": 12,
  "quota_remaining": 987988
}

Your client should branch on the Content-Type header instead of assuming one response shape. Store generated audio in your own durable storage if the URL is short-lived.

Billing And Credits

Sync TTS consumes credits based on generated content and model configuration. Because the endpoint performs generation inside the HTTP request, a client timeout does not always mean the server cancelled work. Use idempotency in your own application layer when retrying user actions.

If you need exact post-generation balance, call Profile after the request completes. For large batches, prefer async jobs so each task has a durable id and status.

Errors