> ## Documentation Index > Fetch the complete documentation index at: https://docs.apistable.ai/llms.txt > Use this file to discover all available pages before exploring further. # Upload a Voice sample > Upload a voice sample and select a segment, then request a phrase, record verification, and check the created Voice. > Operations are enabled individually by server configuration. Disabled operations return 503 without a task. Music credit deduction is currently disabled. ## Using this operation Upload a voice sample and select a segment, then request a phrase, record verification, and check the created Voice. * 1. Prepare the fields shown in the example below. Replace sample URLs and IDs with resources you can access. * 2. Set model to suno\_voice\_upload and place the parameters inside input. Submit once and save the returned task\_id. * 3. Query the saved task or receive its callback. A processing result is not a reason to submit the operation again. * After result.ready is true, pass result.voice\_upload\_task\_id to the verification-phrase endpoint. ## Create task Send model and input to the common task endpoint. callback\_url is an optional top-level public HTTPS address. All resource IDs are APIstable IDs owned by your account. Music credit deduction is currently disabled. ```json theme={null} { "model": "suno_voice_upload", "input": { "voice_url": "https://example.com/voice.wav", "vocal_start_s": 0, "vocal_end_s": 20 } } ``` ## Acceptance response HTTP 200 confirms acceptance, not completion. Query GET /api/v1/tasks/\{task\_id} until data.status is succeeded or failed. Read data.result only after success; a failed task has its error in data.message. ```json theme={null} { "code": 200, "msg": "success", "data": { "task_id": "YOUR_TASK_ID" } } ``` ## Parameter reference | Field | Type | Required | Description and limits | | - | - | - | - | | voice\_url | string | Yes | Public HTTPS original voice recording: MP3/WAV/FLAC/OGG/M4A/AAC, up to 500 MiB, with a positive duration. | | vocal\_start\_s | number | Yes | Selected vocal start in seconds, at most two decimal places. Use the original recording for Voice upload and the prepared vocal timeline for song Persona. min: 0 | | vocal\_end\_s | number | Yes | Selected vocal end in seconds, at most two decimal places; after start and within the audio. Song Voice Persona requires a 10–30 second range. min: 0 | | name | string | No / conditional | Voice or Persona display name. maxLength: 100 | | description | string | No / conditional | Voice or Persona description. maxLength: 1000 | ## Inputs and limits The schema lists supported fields, types and basic limits. Also follow Important conditions: cross-field and source-resource checks are not fully represented in JSON Schema. Unknown parameters are rejected. URL fields accept public HTTPS URLs, never file objects. ```json theme={null} { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "voice_url": { "type": "string", "format": "uri", "description": "Public HTTPS original voice recording: MP3/WAV/FLAC/OGG/M4A/AAC, up to 500 MiB, with a positive duration." }, "vocal_start_s": { "type": "number", "minimum": 0, "description": "Selected vocal start in seconds, at most two decimal places. Use the original recording for Voice upload and the prepared vocal timeline for song Persona." }, "vocal_end_s": { "type": "number", "minimum": 0, "description": "Selected vocal end in seconds, at most two decimal places; after start and within the audio. Song Voice Persona requires a 10–30 second range." }, "name": { "type": "string", "maxLength": 100, "description": "Voice or Persona display name." }, "description": { "type": "string", "maxLength": 1000, "description": "Voice or Persona description." } }, "required": [ "voice_url", "vocal_start_s", "vocal_end_s" ], "additionalProperties": false } ``` ## Important conditions * Select 0 ≤ vocal\_start\_s \< vocal\_end\_s ≤ the recording duration, with at most two decimal places. Wait for ready:true before requesting a phrase. The successful upload session lasts 24 hours. * Upload name/description are not automatically copied to the final Voice. Set them again in suno\_voice\_create if required. * Audio URL inputs must contain readable MP3/WAV/FLAC/OGG/M4A/AAC audio with positive duration; the limit is 500 MiB per file. URLs must be publicly accessible HTTPS on port 443, without embedded credentials or private-network addresses. Keep them accessible until the task finishes. * Uploaded files last 24 hours, generated files 14 days and task details 30 days. Reused files keep their original expiry. Valid Voice/Persona identity mappings are separate from task-log cleanup. Download files you need to retain. ## Result schema The creation response is \{code:200,msg:"success",data:\{task\_id}}. Poll GET /api/v1/tasks/\{task\_id}. On success, data.result is an object matching the schema below; it is otherwise null. input remains a JSON string. ```json theme={null} { "type": "object", "required": [ "voice_upload_task_id", "ready" ], "properties": { "voice_upload_task_id": { "type": "string" }, "ready": { "const": true } }, "additionalProperties": false } ``` ## Related workflows [Voice: all four steps](https://docs.apistable.ai/suno-voice-workflow.md) [File uploads](https://docs.apistable.ai/file-upload.md) [Callbacks](https://docs.apistable.ai/webhooks.md) ## OpenAPI ````yaml openapi-suno-voice-upload.json POST /api/v1/tasks/create_task openapi: 3.1.0 info: title: APIstable API version: 1.0.0-preview description: >- Public /api/v1 protocol. Valid API keys have the same account-scoped access. Read the selected model documentation for its ID, supported inputs, result format and availability before submitting. No client submission idempotency or max_credits. Availability, pricing, file retention and callback formats follow the selected model contract. Unconfigured operations return 503. servers: - url: https://apistable.ai description: APIstable API security: [] paths: /api/v1/tasks/create_task: post: summary: Upload a Voice sample description: >- Upload a voice sample and select a segment, then request a phrase, record verification, and check the created Voice. operationId: suno_voice_upload requestBody: required: true content: application/json: schema: type: object required: - model - input additionalProperties: false properties: model: type: string enum: - suno_voice_upload example: suno_voice_upload input: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: voice_url: type: string format: uri description: >- Public HTTPS original voice recording: MP3/WAV/FLAC/OGG/M4A/AAC, up to 500 MiB, with a positive duration. vocal_start_s: type: number minimum: 0 description: >- Selected vocal start in seconds, at most two decimal places. Use the original recording for Voice upload and the prepared vocal timeline for song Persona. vocal_end_s: type: number minimum: 0 description: >- Selected vocal end in seconds, at most two decimal places; after start and within the audio. Song Voice Persona requires a 10–30 second range. name: type: string maxLength: 100 description: Voice or Persona display name. description: type: string maxLength: 1000 description: Voice or Persona description. required: - voice_url - vocal_start_s - vocal_end_s additionalProperties: false callback_url: type: string format: uri description: >- Optional public HTTPS endpoint for signed completion callbacks; no redirects or private IPs. example: model: suno_voice_upload input: voice_url: https://example.com/voice.wav vocal_start_s: 0 vocal_end_s: 20 responses: '200': description: Accepted task. Poll the common task endpoint or use callback_url. content: application/json: schema: type: object required: - code - msg - data additionalProperties: false properties: code: const: 200 msg: const: success data: type: object required: - task_id additionalProperties: false properties: task_id: type: string '400': description: >- 40001 invalid JSON, 40002 invalid input/callback, 40003 unsupported parameter. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Invalid or revoked API key. content: application/json: schema: $ref: '#/components/schemas/Error' '402': description: '40201: Insufficient credits (live acceptance).' content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: '40401: Unknown model or resource not found in this account.' content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: '40901: Resource belongs to a different provider account.' content: application/json: schema: $ref: '#/components/schemas/Error' '410': description: '41001: Source audio or temporary resource has expired.' content: application/json: schema: $ref: '#/components/schemas/Error' '413': description: '41301: Request too large.' content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: '42201: Requested capability combination is not enabled.' content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: '42901: Rate/concurrency limit (live acceptance).' content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: '50301: Service/provider unavailable. No live submission or charge.' content: application/json: schema: $ref: '#/components/schemas/Error' security: - bearerAuth: [] components: schemas: Error: type: object required: - code - msg - data properties: code: type: integer msg: type: string data: type: 'null' securitySchemes: bearerAuth: type: http scheme: bearer description: >- Every valid key can submit and query its own account. Revoked keys are rejected. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.