创建 Studio 项目

POST

/v1/studio/projects

POST

/v1/studio/projects

curl -X POST https://api.elevenlabs.io/v1/studio/projects \
     -H "Content-Type: multipart/form-data" \
     -F from_document=@<file1> \
     -F name="Project 1"

{
  "project": {
    "project_id": "aw1NgEzBg83R7vgmiJt6",
    "name": "My Project",
    "create_date_unix": 1714204800,
    "created_by_user_id": "Vbtgl3bRdj6lk79rYAgx",
    "default_title_voice_ref_id": "JBFqnCBsd6RMkjVDRZzb",
    "default_paragraph_voice_ref_id": "JBFqnCBsd6RMkjVDRZzb",
    "default_model_id": "eleven_multilingual_v2",
    "can_be_downloaded": true,
    "volume_normalization": true,
    "state": "default",
    "access_level": "viewer",
    "quality_check_on": false,
    "quality_check_on_when_bulk_convert": false,
    "default_title_voice_id": "JBFqnCBsd6RMkjVDRZzb",
    "default_paragraph_voice_id": "JBFqnCBsd6RMkjVDRZzb",
    "last_conversion_date_unix": 1714204800,
    "title": "My Project",
    "author": "John Doe",
    "description": "This is a description of my project.",
    "genres": [
      "Novel",
      "Short Story"
    ],
    "cover_image_url": "https://example.com/cover.jpg",
    "target_audience": "young adult",
    "language": "en",
    "content_type": "Novel",
    "original_publication_date": "2025-01-01",
    "mature_content": false,
    "isbn_number": "978-90-274-3964-2",
    "fiction": "fiction",
    "creation_meta": {
      "creation_progress": 0.5,
      "status": "pending",
      "type": "blank"
    },
    "public_share_id": "abc123def456789"
  }
}

创建新的 Studio 项目，可初始化为空白项目、从文档创建，或从 URL 创建。

请求

This endpoint expects a multipart form containing an optional file.

namestring必需

Studio 项目名称，仅用于识别。

default_title_voice_idstring or null可选

新标题默认音色对应的 voice_id。

default_paragraph_voice_idstring or null可选

新段落默认音色对应的 voice_id。

default_model_idstring or null可选

此 Studio 项目使用的模型 ID。可通过 GET /v1/models 查询所有可用模型。

from_urlstring or null可选

可选 URL，将从中提取内容以初始化 Studio 项目。设置此项时，‘from_url’ 和 ‘from_content’ 必须为 null。如果未提供 ‘from_url’、‘from_document’ 和 ‘from_content’ 中的任一项，Studio 项目将初始化为空白项目。

from_documentfile可选

可选提供 .epub、.pdf、.txt 或类似文件。提供后，将使用其内容初始化 Studio 项目。设置此项时，‘from_url’ 和 ‘from_content’ 必须为 null。如果未提供 ‘from_url’、‘from_document’ 和 ‘from_content’ 中的任一项，Studio 项目将初始化为空白项目。

from_content_jsonstring可选

用于初始化 Studio 项目的可选内容。设置此项后，‘from_url’ 和 ‘from_document’ 必须为 null。如果未提供 ‘from_url’、‘from_document’ 和 ‘from_content’，将初始化为空白 Studio 项目。

示例： [{“name”: “Chapter A”, “blocks”: [{“sub_type”: “p”, “nodes”: [{“voice_id”: “6lCwbsX1yVjD49QmpkT0”, “text”: “A”, “type”: “tts_node”}, {“voice_id”: “6lCwbsX1yVjD49QmpkT1”, “text”: “B”, “type”: “tts_node”}]}, {“sub_type”: “h1”, “nodes”: [{“voice_id”: “6lCwbsX1yVjD49QmpkT0”, “text”: “C”, “type”: “tts_node”}, {“voice_id”: “6lCwbsX1yVjD49QmpkT1”, “text”: “D”, “type”: “tts_node”}]}]}, {“name”: “Chapter B”, “blocks”: [{“sub_type”: “p”, “nodes”: [{“voice_id”: “6lCwbsX1yVjD49QmpkT0”, “text”: “E”, “type”: “tts_node”}, {“voice_id”: “6lCwbsX1yVjD49QmpkT1”, “text”: “F”, “type”: “tts_node”}]}, {“sub_type”: “h2”, “nodes”: [{“voice_id”: “6lCwbsX1yVjD49QmpkT0”, “text”: “G”, “type”: “tts_node”}, {“voice_id”: “6lCwbsX1yVjD49QmpkT1”, “text”: “H”, “type”: “tts_node”}]}]}]

用于初始化 Studio 项目的可选内容。设置此项后，'from_url' 和 'from_document' 必须为 null。如果未提供 'from_url'、'from_document' 和 'from_content'，将初始化为空白 Studio 项目。示例： [{"name": "Chapter A", "blocks": [{"sub_type": "p", "nodes": [{"voice_id": "6lCwbsX1yVjD49QmpkT0", "text": "A", "type": "tts_node"}, {"voice_id": "6lCwbsX1yVjD49QmpkT1", "text": "B", "type": "tts_node"}]}, {"sub_type": "h1", "nodes": [{"voice_id": "6lCwbsX1yVjD49QmpkT0", "text": "C", "type": "tts_node"}, {"voice_id": "6lCwbsX1yVjD49QmpkT1", "text": "D", "type": "tts_node"}]}]}, {"name": "Chapter B", "blocks": [{"sub_type": "p", "nodes": [{"voice_id": "6lCwbsX1yVjD49QmpkT0", "text": "E", "type": "tts_node"}, {"voice_id": "6lCwbsX1yVjD49QmpkT1", "text": "F", "type": "tts_node"}]}, {"sub_type": "h2", "nodes": [{"voice_id": "6lCwbsX1yVjD49QmpkT0", "text": "G", "type": "tts_node"}, {"voice_id": "6lCwbsX1yVjD49QmpkT1", "text": "H", "type": "tts_node"}]}]}]

quality_presetenum or null可选

生成音频的输出质量。必须为以下之一： ‘standard’ - 标准输出格式，采样率为 44.1kHz、比特率为 128kbps。 ‘high’ - 高质量输出格式，采样率为 44.1kHz、比特率为 192kbps，并采用我们显著改进的处理。 ‘ultra’ - 超高质量输出格式，采样率为 44.1kHz、比特率为 192kbps，并采用我们最高级别的处理。 ‘ultra_lossless’ - 超高质量输出格式，采样率为 44.1kHz、比特率为 705.6kbps，以完全无损格式采用我们最高级别的处理。未提供时，默认使用当前订阅版本可用的最高质量预设。

生成音频的输出质量。必须为以下之一： 'standard' - 标准输出格式，采样率为 44.1kHz、比特率为 128kbps。 'high' - 高质量输出格式，采样率为 44.1kHz、比特率为 192kbps，并采用我们显著改进的处理。 'ultra' - 超高质量输出格式，采样率为 44.1kHz、比特率为 192kbps，并采用我们最高级别的处理。 'ultra_lossless' - 超高质量输出格式，采样率为 44.1kHz、比特率为 705.6kbps，以完全无损格式采用我们最高级别的处理。未提供时，默认使用当前订阅版本可用的最高质量预设。

允许的值:

titlestring or null可选

Studio 项目作者的可选名称。下载 Studio 项目或章节时，该名称会作为元数据添加到 mp3 文件中。

authorstring or null可选

Studio 项目作者的可选名称。下载 Studio 项目或章节时，该名称会作为元数据添加到 mp3 文件中。

descriptionstring or null可选

可选的 Studio 项目描述。

genreslist of strings可选

与 Studio 项目关联的可选流派列表。

target_audienceenum or null可选

Studio 项目的可选目标受众。

允许的值:

languagestring or null可选=2 characters

可选的 Studio 项目语言。双字母语言代码（ISO 639-1）。

content_typestring or null可选

可选的 Studio 项目内容类型。

original_publication_datestring or null可选格式: "^\d{4}-\d{2}-\d{2}$|^\d{4}$"

Studio 项目的可选原始出版日期，格式为 YYYY-MM-DD 或 YYYY。

mature_contentboolean or null可选默认为 false

可选指定此 Studio 项目是否包含成人内容。

isbn_numberstring or null可选

要创建的 Studio 项目的可选 ISBN 编号。下载 Studio 项目或章节时，该编号会作为元数据添加到 mp3 文件中。

acx_volume_normalizationboolean可选默认为 false

[Deprecated] 下载 Studio 项目时，是否应对返回的音频进行后处理，以符合有声书响度标准化要求。

volume_normalizationboolean可选默认为 false

下载 Studio 项目时，是否应对返回的音频进行后处理，以符合有声书标准化音量要求

pronunciation_dictionary_locatorslist of strings可选

以 JSON 字符串列表编码的发音词典定位符（pronunciation_dictionary_id、version_id）列表，用于指定要应用于文本的发音词典。由于添加项目时可能通过 formData 而非 jsonBody，因此必须提供 JSON 编码字符串列表。若要指定多个词典，请在 curl 中使用多行 —form，例如 —form ‘pronunciation_dictionary_locators=”{“pronunciation_dictionary_id”:“Vmd4Zor6fplcA7WrINey”,“version_id”:“hRPaxjlTdR7wFMhV4w0b”}”’ —form ‘pronunciation_dictionary_locators=”{“pronunciation_dictionary_id”:“JzWtcGQMJ6bnlWwyMo7e”,“version_id”:“lbmwxiLu4q6txYxgdZqn”}”’。

以 JSON 字符串列表编码的发音词典定位符（pronunciation_dictionary_id、version_id）列表，用于指定要应用于文本的发音词典。由于添加项目时可能通过 formData 而非 jsonBody，因此必须提供 JSON 编码字符串列表。若要指定多个词典，请在 curl 中使用多行 --form，例如 --form 'pronunciation_dictionary_locators="{\"pronunciation_dictionary_id\":\"Vmd4Zor6fplcA7WrINey\",\"version_id\":\"hRPaxjlTdR7wFMhV4w0b\"}"' --form 'pronunciation_dictionary_locators="{\"pronunciation_dictionary_id\":\"JzWtcGQMJ6bnlWwyMo7e\",\"version_id\":\"lbmwxiLu4q6txYxgdZqn\"}"'。

callback_urlstring or null可选

Studio 项目转换时，服务将调用此 URL。请求将包含一个含有转换状态的 JSON 对象。消息：

项目转换成功时： { type: “project_conversion_status”, event_timestamp: 1234567890, data: { request_id: “1234567890”, project_id: “21m00Tcm4TlvDq8ikWAM”, conversion_status: “success”, project_snapshot_id: “22m00Tcm4TlvDq8ikMAT”, error_details: None, } }
项目转换失败时： { type: “project_conversion_status”, event_timestamp: 1234567890, data: { request_id: “1234567890”, project_id: “21m00Tcm4TlvDq8ikWAM”, conversion_status: “error”, project_snapshot_id: None, error_details: “Error details if conversion failed” } }
章节转换成功时： { type: “chapter_conversion_status”, event_timestamp: 1234567890, data: { request_id: “1234567890”, project_id: “21m00Tcm4TlvDq8ikWAM”, chapter_id: “22m00Tcm4TlvDq8ikMAT”, conversion_status: “success”, chapter_snapshot_id: “23m00Tcm4TlvDq8ikMAV”, error_details: None, } }
章节转换失败时： { type: “chapter_conversion_status”, event_timestamp: 1234567890, data: { request_id: “1234567890”, project_id: “21m00Tcm4TlvDq8ikWAM”, chapter_id: “22m00Tcm4TlvDq8ikMAT”, conversion_status: “error”, chapter_snapshot_id: None, error_details: “Error details if conversion failed” } }

Studio 项目转换时，服务将调用此 URL。请求将包含一个含有转换状态的 JSON 对象。消息： 1. 项目转换成功时： { type: "project_conversion_status", event_timestamp: 1234567890, data: { request_id: "1234567890", project_id: "21m00Tcm4TlvDq8ikWAM", conversion_status: "success", project_snapshot_id: "22m00Tcm4TlvDq8ikMAT", error_details: None, } } 2. 项目转换失败时： { type: "project_conversion_status", event_timestamp: 1234567890, data: { request_id: "1234567890", project_id: "21m00Tcm4TlvDq8ikWAM", conversion_status: "error", project_snapshot_id: None, error_details: "Error details if conversion failed" } } 3. 章节转换成功时： { type: "chapter_conversion_status", event_timestamp: 1234567890, data: { request_id: "1234567890", project_id: "21m00Tcm4TlvDq8ikWAM", chapter_id: "22m00Tcm4TlvDq8ikMAT", conversion_status: "success", chapter_snapshot_id: "23m00Tcm4TlvDq8ikMAV", error_details: None, } } 4. 章节转换失败时： { type: "chapter_conversion_status", event_timestamp: 1234567890, data: { request_id: "1234567890", project_id: "21m00Tcm4TlvDq8ikWAM", chapter_id: "22m00Tcm4TlvDq8ikMAT", conversion_status: "error", chapter_snapshot_id: None, error_details: "Error details if conversion failed" } }

fictionenum or null可选

可选指定此 Studio 项目内容是否为虚构作品。

允许的值:

apply_text_normalizationenum or null可选

此参数通过 4 种模式控制文本规范化：‘auto’、‘on’、‘apply_english’ 和 ‘off’。设为 ‘auto’ 时，系统会自动决定是否应用文本规范化（例如将数字拼写出来）。设为 ‘on’ 时，始终应用文本规范化；设为 ‘off’ 时则跳过。‘apply_english’ 与 ‘on’ 相同，但会假定文本为英语。

此参数通过 4 种模式控制文本规范化：'auto'、'on'、'apply_english' 和 'off'。设为 'auto' 时，系统会自动决定是否应用文本规范化（例如将数字拼写出来）。设为 'on' 时，始终应用文本规范化；设为 'off' 时则跳过。'apply_english' 与 'on' 相同，但会假定文本为英语。

允许的值:

auto_convertboolean可选默认为 false

是否自动将 Studio 项目转换为音频。

auto_assign_voicesboolean or null可选默认为 false

[Alpha Feature] 是否在创建项目时自动为短语分配音色。

source_typeenum or null可选

要创建的 Studio 项目类型。

voice_settingslist of strings可选

项目的可选音色设置覆盖项，以 JSON 字符串列表编码。

示例： [”{“voice_id”: “21m00Tcm4TlvDq8ikWAM”, “stability”: 0.7, “similarity_boost”: 0.8, “style”: 0.5, “speed”: 1.0, “use_speaker_boost”: true}”]

create_publishing_readboolean or null可选默认为 false

如果为 true，将创建对应的阅读内容，以草稿状态直接发布。

响应

成功响应

projectobject

错误

422

Unprocessable Entity Error

请求头

请求

响应

错误