---
updatedAt: 2025-09-09T22:21:17.000Z
agentTools:
  projectIndex: https://docs.play.ht/llms.txt
---

# Create Batch TTS Job

Creates a new batch Text-to-Speech (TTS) job that converts multiple input texts into audio asynchronously.
The API responds with information about the newly created batch TTS job.
The created jobs are processed, and their status can be tracked via the GET endpoints.

# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "API",
    "version": "2.0",
    "description": "API documentation for Play.ht's Standard & Premium, and PlayHT Voices\n"
  },
  "servers": [
    {
      "url": "https://api.play.ht"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": [],
      "XUserIdAuth": []
    }
  ],
  "paths": {
    "/api/v2/tts/batches": {
      "post": {
        "tags": [
          "Batch Text-to-Speech"
        ],
        "operationId": "api-create-batch-tts",
        "summary": "Create Batch TTS Job",
        "description": "Creates a new batch Text-to-Speech (TTS) job that converts multiple input texts into audio asynchronously.\nThe API responds with information about the newly created batch TTS job.\nThe created jobs are processed, and their status can be tracked via the GET endpoints.\n",
        "security": [
          {
            "ApiKeyAuth": [],
            "XUserIdAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateBatchTtsRequestBody"
              },
              "example": {
                "webhook_url": "https://your.domain/batch-webhook",
                "jobs": [
                  {
                    "custom_id": "my-optional-custom-id-001",
                    "webhook_url": "https://your.domain/optional-job1-webhook",
                    "voice_engine": "PlayDialog",
                    "text": "Hello from job one.",
                    "voice": "s3://voice-cloning-zero-shot/d9ff78ba-d016-47f6-b0ef-dd630f59414e/female-cs/manifest.json",
                    "quality": "medium",
                    "output_format": "mp3",
                    "speed": 1,
                    "sample_rate": 24000,
                    "seed": 123,
                    "temperature": 0.7,
                    "language": "english"
                  },
                  {
                    "text": "Second job, minimal parameters.",
                    "voice": "s3://voice-cloning-zero-shot/another-voice-id/manifest.json"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Batch TTS job created successfully.",
            "headers": {
              "Location": {
                "description": "The URL to retrieve the created batch job.",
                "schema": {
                  "type": "string",
                  "format": "uri"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchTtsJobResource"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidParametersError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "403": {
            "$ref": "#/components/responses/ForbiddenError"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitedError"
          },
          "500": {
            "$ref": "#/components/responses/UnexpectedError"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "AUTHORIZATION",
        "description": "API key required for this endpoint. Use `Bearer YOUR_SECRET_API_KEY`. Get your key from <https://play.ht/app/api-access>."
      },
      "XUserIdAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-USER-ID",
        "description": "User ID required for this endpoint. Get it from <https://play.ht/app/api-access>."
      }
    },
    "schemas": {
      "ErrorResponseObject": {
        "type": "object",
        "properties": {
          "error_message": {
            "type": "string"
          },
          "error_id": {
            "type": "string"
          }
        }
      },
      "VoiceId": {
        "description": "The unique ID for a PlayHT or Cloned Voice.",
        "type": "string",
        "example": "s3://voice-cloning-zero-shot/d9ff78ba-d016-47f6-b0ef-dd630f59414e/female-cs/manifest.json",
        "default": "s3://voice-cloning-zero-shot/d9ff78ba-d016-47f6-b0ef-dd630f59414e/female-cs/manifest.json"
      },
      "BatchTtsJobId": {
        "type": "string",
        "description": "Unique identifier for a batch TTS job.",
        "example": "bb-AbcDeFgHiJkLmNoPqRsTu"
      },
      "BatchTtsChildJobId": {
        "type": "string",
        "description": "Unique identifier for a child job within a batch.",
        "example": "bc-Xyz123Abc456Def789Ghi"
      },
      "BatchTtsJobCustomId": {
        "type": "string",
        "description": "User-defined custom identifier for a child job. Must contain only letters, numbers, dashes, or underscores. Max length 30.",
        "pattern": "^[a-zA-Z0-9_-]+$",
        "minLength": 1,
        "maxLength": 30,
        "example": "my-custom-job-id-123"
      },
      "WebhookURL": {
        "type": "string",
        "format": "url",
        "description": "URL to send webhook notifications to.",
        "example": "https://your.domain/webhook-receiver"
      },
      "WebhookResult": {
        "type": "object",
        "properties": {
          "called_at": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp of when the webhook was called."
          },
          "response_status": {
            "type": "integer",
            "description": "HTTP status code received from the webhook endpoint."
          }
        },
        "required": [
          "called_at",
          "response_status"
        ],
        "example": {
          "called_at": "2023-10-26T10:30:00Z",
          "response_status": 200
        }
      },
      "PlayDialogQuality": {
        "type": "string",
        "enum": [
          "draft",
          "low",
          "medium",
          "high",
          "premium"
        ],
        "description": "Quality of the generated audio.",
        "example": "medium"
      },
      "PlayDialogOutputFormat": {
        "type": "string",
        "enum": [
          "mp3",
          "wav",
          "ogg",
          "flac",
          "mulaw"
        ],
        "description": "Format of the generated audio.",
        "example": "mp3"
      },
      "PlayDialogLanguage": {
        "type": "string",
        "enum": [
          "afrikaans",
          "albanian",
          "amharic",
          "arabic",
          "bengali",
          "bulgarian",
          "catalan",
          "croatian",
          "czech",
          "danish",
          "dutch",
          "english",
          "french",
          "galician",
          "german",
          "greek",
          "hebrew",
          "hindi",
          "hungarian",
          "indonesian",
          "italian",
          "japanese",
          "korean",
          "malay",
          "mandarin",
          "polish",
          "portuguese",
          "russian",
          "serbian",
          "spanish",
          "swedish",
          "tagalog",
          "thai",
          "turkish",
          "ukrainian",
          "urdu",
          "xhosa"
        ],
        "description": "Language of the text/voice.",
        "example": "english"
      },
      "BatchTTSInputParams": {
        "type": "object",
        "description": "Input parameters for a single TTS child job within a batch.",
        "properties": {
          "voice_engine": {
            "type": "string",
            "enum": [
              "PlayDialog"
            ],
            "description": "The voice engine to use for synthesis.",
            "example": "PlayDialog"
          },
          "text": {
            "type": "string",
            "description": "The text to synthesize.",
            "example": "This is the audio content for this job."
          },
          "voice": {
            "$ref": "#/components/schemas/VoiceId"
          },
          "quality": {
            "$ref": "#/components/schemas/PlayDialogQuality",
            "nullable": true
          },
          "output_format": {
            "$ref": "#/components/schemas/PlayDialogOutputFormat",
            "nullable": true
          },
          "speed": {
            "type": "number",
            "format": "float",
            "minimum": 0.1,
            "maximum": 5,
            "nullable": true,
            "description": "Speed of the speech.",
            "example": 1
          },
          "sample_rate": {
            "type": "integer",
            "minimum": 8000,
            "maximum": 48000,
            "nullable": true,
            "description": "Sample rate of the audio in Hz.",
            "example": 24000
          },
          "seed": {
            "type": "integer",
            "minimum": 0,
            "nullable": true,
            "description": "Seed for reproducibility.",
            "example": 42
          },
          "temperature": {
            "type": "number",
            "format": "float",
            "minimum": 0,
            "maximum": 2,
            "nullable": true,
            "description": "Controls randomness. Higher values are more random.",
            "example": 0.75
          },
          "language": {
            "$ref": "#/components/schemas/PlayDialogLanguage",
            "nullable": true
          },
          "voice_2": {
            "$ref": "#/components/schemas/VoiceId",
            "nullable": true,
            "description": "Secondary voice for dialogs."
          },
          "turn_prefix": {
            "type": "string",
            "nullable": true,
            "description": "Prefix for the primary speaker in dialogs.",
            "example": "Speaker A:"
          },
          "turn_prefix_2": {
            "type": "string",
            "nullable": true,
            "description": "Prefix for the secondary speaker in dialogs.",
            "example": "Speaker B:"
          },
          "voice_conditioning_seconds": {
            "type": "integer",
            "nullable": true,
            "description": "Seconds of conditioning for the primary voice.",
            "example": 20
          },
          "voice_conditioning_seconds_2": {
            "type": "integer",
            "nullable": true,
            "description": "Seconds of conditioning for the secondary voice.",
            "example": 20
          }
        },
        "required": [
          "voice_engine",
          "text",
          "voice"
        ]
      },
      "BatchTTSOutput": {
        "type": "object",
        "nullable": true,
        "description": "Output details of a completed TTS child job.",
        "properties": {
          "duration": {
            "type": "number",
            "format": "float",
            "description": "Duration of the audio in seconds.",
            "example": 15.3
          },
          "size": {
            "type": "integer",
            "description": "Size of the audio file in bytes.",
            "example": 56843
          },
          "url": {
            "type": "string",
            "format": "url",
            "description": "URL to download the generated audio file.",
            "example": "https://playht-audio-outputs.s3.amazonaws.com/..."
          }
        },
        "required": [
          "duration",
          "size",
          "url"
        ]
      },
      "ResourceLink": {
        "type": "object",
        "properties": {
          "href": {
            "type": "string",
            "format": "uri"
          },
          "description": {
            "type": "string"
          }
        },
        "required": [
          "href",
          "description"
        ]
      },
      "BatchTtsChildJobResource": {
        "type": "object",
        "description": "Represents a single child job within a batch TTS operation.",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/BatchTtsChildJobId"
          },
          "custom_id": {
            "$ref": "#/components/schemas/BatchTtsJobCustomId",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp of when the child job was created."
          },
          "input": {
            "$ref": "#/components/schemas/BatchTTSInputParams"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "in_progress",
              "completed",
              "failed"
            ],
            "description": "Current status of the child job."
          },
          "output": {
            "$ref": "#/components/schemas/BatchTTSOutput"
          },
          "webhook_url": {
            "$ref": "#/components/schemas/WebhookURL",
            "nullable": true
          },
          "webhook_result": {
            "$ref": "#/components/schemas/WebhookResult",
            "nullable": true
          },
          "_links": {
            "type": "object",
            "properties": {
              "self": {
                "$ref": "#/components/schemas/ResourceLink"
              },
              "alternate": {
                "$ref": "#/components/schemas/ResourceLink",
                "nullable": true
              },
              "batch": {
                "$ref": "#/components/schemas/ResourceLink"
              }
            },
            "required": [
              "self",
              "batch"
            ]
          }
        },
        "required": [
          "id",
          "created_at",
          "input",
          "status",
          "_links"
        ]
      },
      "BatchTtsJobResource": {
        "type": "object",
        "description": "Represents a batch TTS job, containing multiple child jobs.",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/BatchTtsJobId"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp of when the batch job was created."
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "in_progress",
              "completed",
              "failed"
            ],
            "description": "Current overall status of the batch job."
          },
          "webhook_url": {
            "$ref": "#/components/schemas/WebhookURL",
            "nullable": true
          },
          "webhook_result": {
            "$ref": "#/components/schemas/WebhookResult",
            "nullable": true
          },
          "jobs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BatchTtsChildJobResource"
            }
          },
          "_links": {
            "type": "object",
            "properties": {
              "self": {
                "$ref": "#/components/schemas/ResourceLink"
              }
            },
            "required": [
              "self"
            ]
          }
        },
        "required": [
          "id",
          "created_at",
          "status",
          "jobs",
          "_links"
        ]
      },
      "BatchTtsChildJobCreationInput": {
        "allOf": [
          {
            "type": "object",
            "properties": {
              "custom_id": {
                "$ref": "#/components/schemas/BatchTtsJobCustomId",
                "nullable": true
              },
              "webhook_url": {
                "$ref": "#/components/schemas/WebhookURL",
                "nullable": true
              }
            }
          },
          {
            "$ref": "#/components/schemas/BatchTTSInputParams"
          }
        ]
      },
      "CreateBatchTtsRequestBody": {
        "type": "object",
        "properties": {
          "webhook_url": {
            "$ref": "#/components/schemas/WebhookURL",
            "nullable": true,
            "description": "A global webhook URL for the entire batch. Individual job webhooks take precedence if provided."
          },
          "jobs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BatchTtsChildJobCreationInput"
            },
            "minItems": 1,
            "maxItems": 50,
            "description": "An array of child jobs to be processed in this batch."
          }
        },
        "required": [
          "jobs"
        ]
      }
    },
    "responses": {
      "InvalidParametersError": {
        "description": "The provided payload contains one or more invalid parameters.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponseObject"
            },
            "example": {
              "error_message": "The 'text' parameter must be provided.",
              "error_id": "INVALID_PARAMETERS"
            }
          }
        }
      },
      "UnauthorizedError": {
        "description": "The request was not authorized. Please verity your authorization headers.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponseObject"
            },
            "example": {
              "error_message": "The authorization header must be provided in the format 'Bearer <YOUR-API-KEY>'",
              "error_id": "UNAUTHORIZED"
            }
          }
        }
      },
      "ForbiddenError": {
        "description": "The provided API key's plan does not have access to the requested resource.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponseObject"
            },
            "example": {
              "error_message": "API access is not available on your current plan.",
              "error_id": "UNSUPPORTED_PLAN"
            }
          }
        }
      },
      "RateLimitedError": {
        "description": "The server has received too many requests from your IP address within a certain time frame and has temporarily blocked your access to this resource. This error is used to prevent abuse of the server. Please refer to the [Rate-Limits](https://docs.play.ht/reference/api-rate-limits) section for more information.",
        "content": {
          "application/json": {
            "schema": {
              "type": "string"
            },
            "example": "Rate limit exceeded. Please wait a few moments and try again."
          }
        }
      },
      "UnexpectedError": {
        "description": "An unexpected error occurred.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "message": {
                  "type": "string"
                },
                "error": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true
  }
}
```