Seed Audio API Documentation

The Seed Audio API is asynchronous. Submit a generation request, save the returned task ID, and poll the status endpoint until the task succeeds or fails. Provider selection and fallback are managed internally.

View the API overview · Create or manage API keys

Base URL

https://seedaudio.co/api/v1

Authentication

Create an API key from Settings → API Keys. Send it as a Bearer token on every request.

Authorization: Bearer sk_your_api_key

API access requires a paid plan or credit purchase. The full key is displayed only once when it is created.

Billing

• Web and API requests use the same credit balance.
• Audio is billed at 75 credits per generated minute, calculated from actual output duration.
• The minimum charge is 10 credits.
• A task temporarily reserves 150 credits, the maximum charge for 120 seconds.
• Unused reserved credits are returned after success; failed tasks are fully refunded.
• Internal provider fallback never creates an additional user charge.

Create a generation

POST /audio/generations

curl -X POST 'https://seedaudio.co/api/v1/audio/generations' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: demo-request-001' \
  -d '{
    "model": "seed-audio-1.0",
    "prompt": "Generate a short suspense radio drama in English",
    "output_format": "mp3",
    "sample_rate": 24000,
    "speed": 1,
    "volume": 1,
    "pitch": 0
  }'

Successful submission returns HTTP 202:

{
  "id": "audio_task_xxx",
  "object": "audio.generation",
  "model": "seed-audio-1.0",
  "status": "processing",
  "billing": { "reserved_credits": 150 },
  "output": null,
  "usage": null,
  "error": null
}

Request fields

Field	Type	Required	Description
model	string	yes	Must be seed-audio-1.0
prompt	string	yes	Audio scene prompt, up to 2,048 characters
voice	string	no	Supported preset voice ID
audio_references	string[]	no	Up to three public audio URLs
image_url	string	no	One public image URL; cannot be combined with audio references
output_format	string	no	mp3, wav, pcm, or ogg_opus; default mp3
sample_rate	number	no	8000, 16000, 24000, 32000, 44100, or 48000
speed	number	no	Speech speed
volume	number	no	Output volume
pitch	number	no	Pitch adjustment

Idempotency-Key is optional but strongly recommended. Reusing the same key with the same request returns the original task without another charge. Reusing it with a different body returns HTTP 409.

Query task status

GET /audio/generations/{task_id}

curl 'https://seedaudio.co/api/v1/audio/generations/audio_task_xxx' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Poll every 3–5 seconds. A successful task returns:

{
  "id": "audio_task_xxx",
  "object": "audio.generation",
  "model": "seed-audio-1.0",
  "status": "succeeded",
  "output": {
    "url": "https://cdn.seedaudio.co/.../output.mp3",
    "duration_seconds": 43.2,
    "format": "mp3"
  },
  "usage": { "credits": 54 },
  "error": null
}

Statuses are queued, processing, succeeded, failed, and canceled.

JavaScript example

const headers = {
  Authorization: `Bearer ${process.env.SEED_AUDIO_API_KEY}`,
  'Content-Type': 'application/json',
  'Idempotency-Key': crypto.randomUUID(),
};

const created = await fetch('https://seedaudio.co/api/v1/audio/generations', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    model: 'seed-audio-1.0',
    prompt: 'Generate a short suspense radio drama in English',
    output_format: 'mp3',
  }),
}).then((response) => response.json());

const task = await fetch(
  `https://seedaudio.co/api/v1/audio/generations/${created.id}`,
  { headers: { Authorization: headers.Authorization } }
).then((response) => response.json());

Python example

import os
import uuid
import requests

base_url = "https://seedaudio.co/api/v1"
headers = {
    "Authorization": f"Bearer {os.environ['SEED_AUDIO_API_KEY']}",
    "Idempotency-Key": str(uuid.uuid4()),
}

created = requests.post(
    f"{base_url}/audio/generations",
    headers=headers,
    json={
        "model": "seed-audio-1.0",
        "prompt": "Generate a short suspense radio drama in English",
        "output_format": "mp3",
    },
).json()

task = requests.get(
    f"{base_url}/audio/generations/{created['id']}",
    headers={"Authorization": headers["Authorization"]},
).json()

Errors

Errors use real HTTP status codes and a consistent body:

{
  "error": {
    "code": "insufficient_credits",
    "message": "At least 150 credits are required",
    "request_id": "request_xxx"
  }
}

HTTP	Code	Meaning
400	invalid_request	Invalid request parameters
401	invalid_api_key	Missing, invalid, or deleted API key
402	insufficient_credits	Fewer than 150 available credits
403	api_access_required	No paid plan or credit purchase
404	task_not_found	Task not found or belongs to another user
409	idempotency_conflict	Idempotency key reused with another request
429	rate_limit_exceeded	Requests are too frequent

The machine-readable OpenAPI specification is available at https://seedaudio.co/openapi.json.