# 自定义音色上传

> 音频生成

上传自定义声音素材。请求中包含音频文件和声音信息，响应返回声音 ID。

## 请求地址

`POST https://api.modelverse.cn/v1/audio/voice/upload`

## 请求体

## 响应

- **200** — Custom voice created successfully.
- **400** — Invalid upload request or audio constraint violation.
- **401** — Bearer token 无效或缺失。
- **default** — 错误响应。

## OpenAPI 定义

```json
{
  "openapi": "3.1.0",
  "x-language": "zh-CN",
  "info": {
    "title": "custom_voice_api接口文档",
    "version": "1.0.0",
    "description": "这是 ModelVerse 自定义声音管理接口文档，说明如何上传、查询和删除声音，以及处理请求错误。\n接口路径包括 `POST /v1/audio/voice/upload`、`GET /v1/audio/voice/list`、`POST /v1/audio/voice/delete`。\n"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "ModelVerse API endpoint documented for custom voice management."
    }
  ],
  "tags": [
    {
      "name": "Custom Voice",
      "description": "Upload, list, and delete organization-scoped custom voices."
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/audio/voice/upload": {
      "post": {
        "tags": [
          "Custom Voice"
        ],
        "operationId": "uploadCustomVoice",
        "summary": "自定义音色上传",
        "description": "上传自定义声音素材。请求中包含音频文件和声音信息，响应返回声音 ID。\n",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/CustomVoiceUploadMultipartRequest"
              },
              "encoding": {
                "speaker_file": {
                  "contentType": "audio/wav, audio/mpeg"
                },
                "emotion_file": {
                  "contentType": "audio/wav, audio/mpeg"
                }
              },
              "examples": {
                "multipartFileUpload": {
                  "$ref": "#/components/examples/CustomVoiceUploadMultipartExample"
                },
                "multipartBase64Upload": {
                  "$ref": "#/components/examples/CustomVoiceUploadBase64Example"
                },
                "multipartUrlUpload": {
                  "$ref": "#/components/examples/CustomVoiceUploadUrlExample"
                }
              }
            },
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/CustomVoiceUploadFormRequest"
              },
              "examples": {
                "base64Upload": {
                  "$ref": "#/components/examples/CustomVoiceUploadBase64Example"
                },
                "urlUpload": {
                  "$ref": "#/components/examples/CustomVoiceUploadUrlExample"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Custom voice created successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomVoiceUploadResponse"
                },
                "examples": {
                  "uploaded": {
                    "$ref": "#/components/examples/CustomVoiceUploadResponseExample"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid upload request or audio constraint violation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomVoiceErrorResponse"
                },
                "examples": {
                  "missingSpeaker": {
                    "$ref": "#/components/examples/CustomVoiceMissingSpeakerErrorExample"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Bearer token 无效或缺失。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomVoiceErrorResponse"
                },
                "examples": {
                  "authError": {
                    "$ref": "#/components/examples/CustomVoiceAuthErrorExample"
                  }
                }
              }
            }
          },
          "default": {
            "description": "错误响应。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomVoiceErrorResponse"
                },
                "examples": {
                  "error": {
                    "$ref": "#/components/examples/CustomVoiceErrorExample"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/audio/voice/list": {
      "get": {
        "tags": [
          "Custom Voice"
        ],
        "operationId": "listCustomVoices",
        "summary": "自定义音色列表",
        "description": "查询自定义声音列表。可按分页参数读取已上传的声音资源。\n",
        "responses": {
          "200": {
            "description": "Custom voice list for the current organization.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomVoiceListResponse"
                },
                "examples": {
                  "listed": {
                    "$ref": "#/components/examples/CustomVoiceListResponseExample"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Bearer token 无效或缺失。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomVoiceErrorResponse"
                },
                "examples": {
                  "authError": {
                    "$ref": "#/components/examples/CustomVoiceAuthErrorExample"
                  }
                }
              }
            }
          },
          "default": {
            "description": "错误响应。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomVoiceErrorResponse"
                },
                "examples": {
                  "error": {
                    "$ref": "#/components/examples/CustomVoiceErrorExample"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/audio/voice/delete": {
      "post": {
        "tags": [
          "Custom Voice"
        ],
        "operationId": "deleteCustomVoice",
        "summary": "自定义音色删除",
        "description": "删除指定的自定义声音。请求中传入声音 ID，响应返回删除结果。\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CustomVoiceDeleteRequest"
              },
              "examples": {
                "deleteVoice": {
                  "$ref": "#/components/examples/CustomVoiceDeleteRequestExample"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Custom voice deleted successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomVoiceDeleteResponse"
                },
                "examples": {
                  "deleted": {
                    "$ref": "#/components/examples/CustomVoiceDeleteResponseExample"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid custom voice ID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomVoiceErrorResponse"
                },
                "examples": {
                  "invalidVoiceId": {
                    "$ref": "#/components/examples/CustomVoiceInvalidVoiceIdErrorExample"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Bearer token 无效或缺失。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomVoiceErrorResponse"
                },
                "examples": {
                  "authError": {
                    "$ref": "#/components/examples/CustomVoiceAuthErrorExample"
                  }
                }
              }
            }
          },
          "default": {
            "description": "错误响应。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomVoiceErrorResponse"
                },
                "examples": {
                  "error": {
                    "$ref": "#/components/examples/CustomVoiceErrorExample"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key"
      }
    },
    "schemas": {
      "CustomVoiceName": {
        "type": "string",
        "minLength": 1,
        "description": "指定的自定义声音。请求中传入声音 ID，响应返回删除结果。\n",
        "examples": [
          "温柔女声",
          "客服音色A"
        ]
      },
      "CustomVoiceModel": {
        "type": "string",
        "minLength": 1,
        "description": "指定的自定义声音。请求中传入声音 ID，响应返回删除结果。\n",
        "examples": [
          "IndexTeam/IndexTTS-2"
        ]
      },
      "CustomVoiceId": {
        "type": "string",
        "minLength": 1,
        "pattern": "^uspeech:.+",
        "description": "指定的自定义声音。请求中传入声音 ID，响应返回删除结果。\n",
        "examples": [
          "uspeech:xxxx-xxxx-xxxx-xxxx"
        ]
      },
      "CustomVoiceAudioFile": {
        "type": "string",
        "format": "binary",
        "maxLength": 20971520,
        "description": "指定的自定义声音。请求中传入声音 ID，响应返回删除结果。\n"
      },
      "CustomVoiceAudioBase64": {
        "type": "string",
        "contentEncoding": "base64",
        "minLength": 1,
        "description": "指定的自定义声音。请求中传入声音 ID，响应返回删除结果。\n",
        "examples": [
          "UklGRiQAAABXQVZFZm10IBAAAAABAAEAgD4AAAB9AAACABAAZGF0YQAAAAA="
        ]
      },
      "CustomVoiceAudioUrl": {
        "type": "string",
        "format": "uri",
        "minLength": 1,
        "description": "指定的自定义声音。请求中传入声音 ID，响应返回删除结果。\n",
        "examples": [
          "https://example.com/audio/speaker.wav"
        ]
      },
      "CustomVoiceUploadMultipartRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "name",
          "model"
        ],
        "properties": {
          "name": {
            "$ref": "#/components/schemas/CustomVoiceName"
          },
          "model": {
            "$ref": "#/components/schemas/CustomVoiceModel"
          },
          "speaker_file": {
            "$ref": "#/components/schemas/CustomVoiceAudioFile"
          },
          "speaker_file_base64": {
            "$ref": "#/components/schemas/CustomVoiceAudioBase64"
          },
          "speaker_url": {
            "$ref": "#/components/schemas/CustomVoiceAudioUrl"
          },
          "emotion_file": {
            "$ref": "#/components/schemas/CustomVoiceAudioFile"
          },
          "emotion_file_base64": {
            "$ref": "#/components/schemas/CustomVoiceAudioBase64"
          },
          "emotion_url": {
            "$ref": "#/components/schemas/CustomVoiceAudioUrl"
          }
        },
        "anyOf": [
          {
            "required": [
              "speaker_file"
            ]
          },
          {
            "required": [
              "speaker_file_base64"
            ]
          },
          {
            "required": [
              "speaker_url"
            ]
          }
        ],
        "description": "指定的自定义声音。请求中传入声音 ID，响应返回删除结果。\n"
      },
      "CustomVoiceUploadFormRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "name",
          "model"
        ],
        "properties": {
          "name": {
            "$ref": "#/components/schemas/CustomVoiceName"
          },
          "model": {
            "$ref": "#/components/schemas/CustomVoiceModel"
          },
          "speaker_file_base64": {
            "$ref": "#/components/schemas/CustomVoiceAudioBase64"
          },
          "speaker_url": {
            "$ref": "#/components/schemas/CustomVoiceAudioUrl"
          },
          "emotion_file_base64": {
            "$ref": "#/components/schemas/CustomVoiceAudioBase64"
          },
          "emotion_url": {
            "$ref": "#/components/schemas/CustomVoiceAudioUrl"
          }
        },
        "anyOf": [
          {
            "required": [
              "speaker_file_base64"
            ]
          },
          {
            "required": [
              "speaker_url"
            ]
          }
        ],
        "description": "指定的自定义声音。请求中传入声音 ID，响应返回删除结果。\n"
      },
      "CustomVoiceUploadResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/CustomVoiceId"
          }
        }
      },
      "CustomVoiceListItem": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/CustomVoiceId"
          },
          "name": {
            "$ref": "#/components/schemas/CustomVoiceName"
          }
        }
      },
      "CustomVoiceListResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "list"
        ],
        "properties": {
          "list": {
            "type": "array",
            "maxItems": 1000,
            "description": "Custom voices available to the current organization.",
            "items": {
              "$ref": "#/components/schemas/CustomVoiceListItem"
            }
          }
        }
      },
      "CustomVoiceDeleteRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/CustomVoiceId"
          }
        }
      },
      "CustomVoiceDeleteResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "const": true,
            "description": "Indicates that the custom voice was deleted."
          }
        }
      },
      "CustomVoiceErrorObject": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "message",
          "type",
          "code",
          "param"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "Human-readable error description.",
            "examples": [
              "错误描述信息"
            ]
          },
          "type": {
            "type": "string",
            "description": "Error category.",
            "examples": [
              "invalid_request_error"
            ]
          },
          "code": {
            "type": "string",
            "description": "机器可读的错误码。",
            "enum": [
              "missing_name",
              "missing_speaker",
              "invalid_speaker_base64",
              "unsupported_audio_format",
              "file_too_large",
              "duration_out_of_range",
              "sample_rate_too_low",
              "missing_id",
              "invalid_voice_id",
              "server_error",
              "auth_error"
            ],
            "examples": [
              "missing_speaker"
            ]
          },
          "param": {
            "type": [
              "string",
              "null"
            ],
            "description": "Request ID or parameter name associated with the error.",
            "examples": [
              "speaker_file"
            ]
          }
        }
      },
      "CustomVoiceErrorResponse": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "$ref": "#/components/schemas/CustomVoiceErrorObject"
          }
        }
      }
    },
    "examples": {
      "CustomVoiceUploadMultipartExample": {
        "summary": "Multipart file upload带speaker and emotion files",
        "value": {
          "name": "温柔女声",
          "model": "IndexTeam/IndexTTS-2",
          "speaker_file": "/path/to/speaker.wav",
          "emotion_file": "/path/to/emotion.wav"
        }
      },
      "CustomVoiceUploadBase64Example": {
        "summary": "Form upload带Base64 speaker audio",
        "value": {
          "name": "温柔女声",
          "model": "IndexTeam/IndexTTS-2",
          "speaker_file_base64": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAgD4AAAB9AAACABAAZGF0YQAAAAA=",
          "emotion_file_base64": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAgD4AAAB9AAACABAAZGF0YQAAAAA="
        }
      },
      "CustomVoiceUploadUrlExample": {
        "summary": "Form upload带public音频URLs",
        "value": {
          "name": "客服音色A",
          "model": "IndexTeam/IndexTTS-2",
          "speaker_url": "https://example.com/audio/speaker.wav",
          "emotion_url": "https://example.com/audio/emotion.wav"
        }
      },
      "CustomVoiceUploadResponseExample": {
        "summary": "Upload 响应",
        "value": {
          "id": "uspeech:xxxx-xxxx-xxxx-xxxx"
        }
      },
      "CustomVoiceListResponseExample": {
        "summary": "List 响应",
        "value": {
          "list": [
            {
              "id": "uspeech:xxxx",
              "name": "温柔女声"
            },
            {
              "id": "uspeech:yyyy",
              "name": "沉稳男声"
            }
          ]
        }
      },
      "CustomVoiceDeleteRequestExample": {
        "summary": "Delete 请求",
        "value": {
          "id": "uspeech:xxxx"
        }
      },
      "CustomVoiceDeleteResponseExample": {
        "summary": "Delete 响应",
        "value": {
          "success": true
        }
      },
      "CustomVoiceErrorExample": {
        "summary": "文档中的error响应format",
        "value": {
          "error": {
            "message": "错误描述信息",
            "type": "invalid_request_error",
            "code": "missing_speaker",
            "param": "<请求 ID 或参数名>"
          }
        }
      },
      "CustomVoiceMissingSpeakerErrorExample": {
        "summary": "Missing speaker音频source",
        "value": {
          "error": {
            "message": "No speaker audio source was provided.",
            "type": "invalid_request_error",
            "code": "missing_speaker",
            "param": "speaker_file"
          }
        }
      },
      "CustomVoiceInvalidVoiceIdErrorExample": {
        "summary": "Voice ID does not exist or was deleted",
        "value": {
          "error": {
            "message": "The specified custom voice ID does not exist in the current organization or has been deleted.",
            "type": "invalid_request_error",
            "code": "invalid_voice_id",
            "param": "id"
          }
        }
      },
      "CustomVoiceAuthErrorExample": {
        "summary": "Invalid bearer token",
        "value": {
          "error": {
            "message": "Validate Certification failed.",
            "type": "invalid_request_error",
            "code": "auth_error",
            "param": null
          }
        }
      }
    }
  }
}
```