Seed Audio API Documentation

Overview

Convert text to natural-sounding speech using a library of built-in voices, or clone a custom voice from a short audio sample for consistent narration.

Primary Endpoint

POST/api/v1/seedAudio/generate

Queues a Seed Audio task. Advance quotes through `/api/v1/generation/quote` are not supported because the actual output duration is unknown before generation. Do not request or retry an advance quote; explain the reservation and settlement rules and obtain the user's acceptance before submitting this request. The current runtime unit price and the 120-credit reservation are snapshotted when the task is submitted. The reservation is not the final price. After success, billing is recalculated from the original output duration rounded up; unused credits are refunded and any additional charge is limited to the user's remaining balance. Failed tasks receive a full refund. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `text_prompt`. ### Behavior - Validates the submitted payload and performs the operation described by the request schema. - Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Too many unfinished Seed Audio tasks for the current user. ### Related Operations - `GET /api/v1/seedAudio/allRecords` — Get all Seed Audio records. - `GET /api/v1/seedAudio/{_id}` — Get Seed Audio task detail. - `DELETE /api/v1/seedAudio/{_id}` — Delete Seed Audio task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).

Request Parameters

Name	Type	Required	Description
text_prompt	string	Yes	maxLength: 3000
references	array<object>	No	Use either one image reference, or up to three audio references in total, where `audio_url` and `speaker` entries may be combined. Image references cannot be mixed with audio or speaker references.
display_text	string	No	maxLength: 2100
performance_direction	string	No	maxLength: 800
audio_config	object	No	-
audio_config.speech_rate	integer	No	minimum: -50; maximum: 100
audio_config.loudness_rate	integer	No	minimum: -50; maximum: 100
audio_config.pitch_rate	integer	No	minimum: -12; maximum: 12

Request schema and conditional rules

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "text_prompt"
  ],
  "properties": {
    "text_prompt": {
      "type": "string",
      "maxLength": 3000,
      "example": "high quality, clear, cinematic"
    },
    "references": {
      "type": "array",
      "description": "Use either one image reference, or up to three audio references in total, where `audio_url` and `speaker` entries may be combined. Image references cannot be mixed with audio or speaker references.",
      "anyOf": [
        {
          "maxItems": 1,
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "image_url"
            ],
            "properties": {
              "image_url": {
                "type": "string"
              }
            }
          }
        },
        {
          "maxItems": 3,
          "items": {
            "oneOf": [
              {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "audio_url"
                ],
                "properties": {
                  "audio_url": {
                    "type": "string"
                  }
                }
              },
              {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "speaker"
                ],
                "properties": {
                  "speaker": {
                    "type": "string"
                  }
                }
              }
            ]
          }
        }
      ],
      "example": [
        {
          "image_url": "https://example.com/image.jpg"
        }
      ]
    },
    "display_text": {
      "type": "string",
      "maxLength": 2100,
      "example": "example"
    },
    "performance_direction": {
      "type": "string",
      "maxLength": 800,
      "example": "example"
    },
    "audio_config": {
      "type": "object",
      "properties": {
        "speech_rate": {
          "type": "integer",
          "minimum": -50,
          "maximum": 100,
          "example": -50
        },
        "loudness_rate": {
          "type": "integer",
          "minimum": -50,
          "maximum": 100,
          "example": -50
        },
        "pitch_rate": {
          "type": "integer",
          "minimum": -12,
          "maximum": 12,
          "example": -12
        }
      },
      "example": {}
    }
  },
  "example": {
    "text_prompt": "high quality, clear, cinematic"
  }
}

Response Fields

code: integer
message: string
data: object
data._id: string
data.current_status: enum: initialized | processing | completed | failed
data.text_prompt: string
data.display_text: string
data.performance_direction: string
data.result_url: string: Generated audio URL, empty until the task is completed
data.format: string
data.duration: number: Output audio duration in seconds
data.original_duration: number: Provider-reported duration used for billing
data.billed_duration: number
data.billing_unit_price: number
data.billing_reservation_coins: number
data.expected_coins: number
data.coins: number: Credits finally charged for this task
data.billing_discount_coins: number
data.hasRefundCoin: boolean
data.subtitle: object
data.request_id: string
data.provider_log_id: string
data.failed_code: string
data.failed_message: string
data.createdAt: string
data.updatedAt: string
data.expiration_days: integer: Days the generated audio is retained
data.expiration_time: string
trace_id: string: Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.

Request Example

curl -X POST "https://headswap.app/api/v1/seedAudio/generate" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "text_prompt": "Gentle rain in a quiet forest",
  "references": []
}'