--- updatedAt: 2025-09-09T22:21:23.000Z --- # Create instant voice clone (via file upload) Create an instant voice clone by providing a sample audio file via file upload. The cloned voice will be based on the characteristics of the provided audio file. Upload the file using `multipart/form-data` and include the sample file. The created voice clone can be used for [text-to-speech (TTS) generation](https://docs.play.ht/reference/api-generate-audio). The audio file selected as the source for the voice clone should have a duration ranging from 2 seconds to 1 hour. It can be in any audio format, as long as it falls within the size range of `5kb` to `50MB`. # OpenAPI definition ```json { "openapi": "3.0.3", "info": { "title": "API", "version": "2.3.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/cloned-voices/instant": { "post": { "tags": [ "Hidden" ], "operationId": "api-create-instant-voice-clone", "summary": "Create Instant Voice Clone (via file upload)", "description": "Create an instant voice clone by providing a sample audio file via file upload.\n\nThe cloned voice will be based on the characteristics of the provided audio\nfile. Upload the file using `multipart/form-data` and include the sample file. The created\nvoice clone can be used for [text-to-speech (TTS) generation](https://docs.play.ht/reference/api-generate-audio).\n\nThe audio file selected as the source for the voice clone should have a\nduration ranging from 2 seconds to 1 hour. It can be in any audio\nformat, as long as it falls within the size range of `5kb` to `50MB`.\n", "security": [ { "ApiKeyAuth": [], "XUserIdAuth": [] } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "sample_file": { "type": "string", "format": "binary", "description": "The audio file selected as the source for the voice clone should have a duration ranging from 2 seconds to 1 hour. It can be in any audio format, as long as it falls within the size range of 5kb to 50 MB.\n\n`Content-Type: audio/*`\n" }, "voice_name": { "type": "string", "description": "The name for this new cloned voice.\n\n`Content-Type: text/plain`\n", "example": "sales-voice" } }, "required": [ "sample_file", "voice_name" ] }, "encoding": { "sample_file": { "contentType": "audio/*" }, "voice_name": { "contentType": "text/plain" } } } } }, "responses": { "201": { "$ref": "#/components/responses/ClonedVoicesInstantCreated" }, "400": { "$ref": "#/components/responses/InvalidParametersError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "415": { "$ref": "#/components/responses/UnsupportedMediaTypeError" }, "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 ." }, "XUserIdAuth": { "type": "apiKey", "in": "header", "name": "X-USER-ID", "description": "User ID required for this endpoint. Get it from ." } }, "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" }, "ClonedVoice": { "type": "object", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/VoiceId" } ], "example": "s3://voice-cloning-zero-shot/475accx8-67cz-9812-x966-rda588612534/myvoice/manifest.json" }, "name": { "type": "string", "example": "myvoice" }, "type": { "type": "string", "enum": [ "high-fidelity", "instant" ] } }, "required": [ "id", "name", "type" ] } }, "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 '", "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" } } } }, "UnsupportedMediaTypeError": { "description": "The server could not process your request because the format of the data you sent is not supported.\n\nCheck `Content-Type` header of your request and ensure that it is set to a supported media type. You may also need to update your request payload to match the expected media type for the resource you are trying to access.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseObject" }, "example": { "error_message": "Requests to this endpoint must be in example/media-type.", "error_id": "UNSUPPORTED_MEDIA_TYPE" } } } }, "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" } } } } } }, "ClonedVoicesInstantCreated": { "description": "Instant voice clone successfully created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClonedVoice" } } } } } }, "x-readme": { "explorer-enabled": true, "proxy-enabled": true } } ```