[{"data":1,"prerenderedAt":181},["ShallowReactive",2],{"reference-detail-zh-align_audio_api_v1_audio_align_post":3,"developer-code-wi7nsr":179,"developer-code-13vk4c6":180},{"tag":4,"sourceTag":4,"tagSlug":5,"method":6,"path":7,"slug":8,"summary":9,"description":10,"operationId":11,"groupOrder":12,"descriptionHtml":13,"parameters":14,"requestBody":22,"responses":63,"security":166,"codeSamples":169},"Audio","audio","POST","\u002Fapi\u002Fv1\u002Faudio\u002Falign","align-audio","对齐文本与音频","将已知 `text` 与其对应的语音音频强制对齐，获得逐词时间戳。例如，将脚本与 POST \u002Fapi\u002Fv1\u002Ftts 生成的 MP3 对齐，为任意声音制作准确字幕。按音频每 5 分钟 1 点计费，不足 5 分钟按 5 分钟计算，仅成功时扣费。此接口同步执行，音频最长 30 分钟。Beta 期间每个 API Key 的并发数受限，超限请求会被拒绝，不会排队。","align_audio_api_v1_audio_align_post",999,"\u003Cp>将已知 \u003Ccode>text\u003C\u002Fcode> 与其对应的语音音频强制对齐，获得逐词时间戳。例如，将脚本与 POST \u002Fapi\u002Fv1\u002Ftts 生成的 MP3 对齐，为任意声音制作准确字幕。按音频每 5 分钟 1 点计费，不足 5 分钟按 5 分钟计算，仅成功时扣费。此接口同步执行，音频最长 30 分钟。Beta 期间每个 API Key 的并发数受限，超限请求会被拒绝，不会排队。\u003C\u002Fp>",[15],{"name":16,"in":17,"required":18,"description":19,"type":20,"example":21},"X-API-Key","header",true,"你的 VisionStory API Key（`sk-vs-...`），请仅保存在服务端。可在 [API Key 管理](\u002Fapi-keys) 中创建或管理，需要 Pro 或更高方案。","string","sk-vs-your-api-key",{"required":18,"contentType":23,"schema":24,"example":59},"application\u002Fjson",{"type":25,"description":26,"nullable":27,"properties":28},"AlignRequest","",false,[29,55],{"name":5,"required":18,"type":30,"description":31,"nullable":27,"properties":32},"MediaRef","媒体引用，必须且只能提供以下一种：`asset_id`（素材库中的素材，可跨请求复用）、`url`（单次使用的公开 URL）或 `inline_data`（单次使用的 base64 数据，不保存）。",[33,38,51],{"name":34,"required":27,"type":35,"description":36,"nullable":18,"properties":37},"asset_id","string | null","POST \u002Fapi\u002Fv1\u002Fasset 返回的素材 ID，用于跨请求复用素材。",[],{"name":39,"required":27,"type":40,"description":41,"nullable":18,"properties":42},"inline_data","InlineDataModel | null","仅供本次使用的内嵌 base64 媒体数据，不会加入素材库。图像支持 image\u002Fjpeg、image\u002Fjpg、image\u002Fpng、image\u002Fwebp、image\u002Fbmp、image\u002Ftiff、image\u002Fgif；音频支持 audio\u002Fwav、audio\u002Fx-wav、audio\u002Fwave、audio\u002Fmpeg、audio\u002Fmp3；视频支持 video\u002Fmp4、video\u002Fquicktime、video\u002Fmov。",[43,47],{"name":44,"required":18,"type":20,"description":45,"nullable":27,"properties":46},"data","文件原始字节编码后的 base64 字符串，不包含 `data:` URI 前缀。",[],{"name":48,"required":18,"type":20,"description":49,"nullable":27,"properties":50},"mime_type","内嵌数据的 MIME 类型，网关据此区分图像、音频和视频。可接受的类型取决于具体接口，请参阅包含此对象的字段说明。数字人视频接受音频 ['audio\u002Favi', 'audio\u002Fmpeg', 'audio\u002Fmp3', 'audio\u002Fmp4', 'audio\u002Fm4a', 'audio\u002Fwav'] 和图像 ['image\u002Fjpeg', 'image\u002Fjpg', 'image\u002Fpng', 'image\u002Fwebp', 'image\u002Fheic']。",[],{"name":52,"required":27,"type":35,"description":53,"nullable":18,"properties":54},"url","仅供本次使用的公开可访问媒体 URL，不会加入素材库。",[],{"name":56,"required":18,"type":20,"description":57,"nullable":27,"properties":58},"text","音频实际朗读的完整原文，例如通过 POST \u002Fapi\u002Fv1\u002Ftts 合成的脚本。时间戳将与此文本对齐。",[],{"audio":60,"text":62},{"asset_id":61},"asset_audio_123456","Welcome to VisionStory.",[64,138],{"status":65,"description":66,"contentType":23,"schema":67,"example":118,"examples":129,"headers":137},"200","请求成功",{"type":68,"description":26,"nullable":27,"properties":69},"BaseSuccessResponse_AlignResponse_",[70,108,113],{"name":44,"required":18,"type":71,"description":72,"nullable":18,"properties":73},"AlignResponse | null","当前接口的响应数据，字段定义见该接口的响应结构。仅当操作不返回数据时为 null。",[74,80,85],{"name":75,"required":27,"type":76,"description":77,"nullable":27,"default":78,"properties":79},"cost_credit","integer","本次请求扣除的点数。",0,[],{"name":81,"required":27,"type":82,"description":83,"nullable":27,"default":78,"properties":84},"duration_sec","number","输入音频的时长，单位为秒。",[],{"name":86,"required":27,"type":87,"description":88,"nullable":27,"properties":89,"items":90},"words","WordDto[]","给定文本对应的逐词时间戳。",[],{"type":91,"description":26,"nullable":27,"properties":92},"WordDto",[93,97,101,105],{"name":94,"required":18,"type":82,"description":95,"nullable":27,"properties":96},"end_sec","单词结束时间，单位为秒。",[],{"name":98,"required":27,"type":35,"description":99,"nullable":18,"properties":100},"speaker","说话人标签，仅在请求启用 `diarize` 时返回。",[],{"name":102,"required":18,"type":82,"description":103,"nullable":27,"properties":104},"start_sec","单词开始时间，单位为秒。",[],{"name":56,"required":18,"type":20,"description":106,"nullable":27,"properties":107},"单词的文本内容。",[],{"name":109,"required":27,"type":20,"description":110,"nullable":27,"default":111,"properties":112},"message","便于阅读的状态消息；调用成功时为 `\"success\"`。","success",[],{"name":114,"required":18,"type":115,"description":116,"nullable":27,"properties":117},"server_time","string · date-time","服务端生成响应时的时间戳，使用 ISO 8601 格式（UTC）。",[],{"data":119,"message":111,"server_time":128},{"cost_credit":120,"duration_sec":120,"words":121},1,[122,126],{"end_sec":123,"speaker":124,"start_sec":78,"text":125},0.5,null,"Hello",{"end_sec":120,"speaker":124,"start_sec":123,"text":127},"world","2026-09-04T00:00:00Z",[130],{"name":111,"description":131,"summary":66,"value":132},"示例仅用于说明响应结构，不代表实时账户数据或实际报价。ID 和 URL 均为占位内容。请调用模型查询及费用估算接口，获取当前可用模型和价格。",{"data":133,"message":111,"server_time":128},{"cost_credit":120,"duration_sec":120,"words":134},[135,136],{"end_sec":123,"speaker":124,"start_sec":78,"text":125},{"end_sec":120,"speaker":124,"start_sec":123,"text":127},[],{"status":139,"description":140,"contentType":23,"schema":141,"example":163,"headers":165},"default","错误响应。所有失败均使用统一结构：`error` 对象包含数字错误码 `code`、便于阅读的 `message`、可选的 `details` 字符串，以及提供后续处理建议的可选 `hint`（便于 AI Agent 使用）。",{"type":142,"description":26,"nullable":27,"properties":143},"ErrorResponse",[144],{"name":145,"required":18,"type":146,"description":26,"nullable":27,"properties":147},"error","ErrorDetail",[148,152,156,160],{"name":149,"required":18,"type":76,"description":150,"nullable":27,"properties":151},"code","机器可读的错误码。传输层失败时对应 HTTP 状态码（例如 401、404、422、500），其他情况可能使用业务专用错误码。",[],{"name":153,"required":27,"type":35,"description":154,"nullable":18,"properties":155},"details","可选的结构化错误详情，例如 422 响应中逐字段校验错误的 JSON 字符串。无补充信息时不返回。",[],{"name":157,"required":27,"type":35,"description":158,"nullable":18,"properties":159},"hint","供用户和 AI Agent 参考的错误处理建议，例如如何修正请求或在哪里获取 API Key。可能不返回此字段。",[],{"name":109,"required":18,"type":20,"description":161,"nullable":27,"properties":162},"便于阅读的错误原因说明，可安全记录到日志或展示给最终用户；此返回值未本地化。",[],{"error":164},{"code":120,"message":20,"details":20,"hint":20},[],[167],{"APIKeyHeader":168},[],[170,173,176],{"lang":171,"source":172},"SDK","from visionstory import VisionStoryClient\n\nclient = VisionStoryClient.from_env()\nalignment = client.align_audio(\n    text=\"Welcome to VisionStory.\",\n    asset_id=\"asset_audio_123456\",\n)\nprint(alignment)",{"lang":174,"source":175},"REST","import os\nimport requests\n\nresponse = requests.post(\n    \"https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Faudio\u002Falign\",\n    headers={\"X-API-Key\": os.environ[\"VISIONSTORY_API_KEY\"]},\n    json={\n      \"audio\": {\n        \"asset_id\": \"asset_audio_123456\"\n      },\n      \"text\": \"Welcome to VisionStory.\"\n    },\n)\nresponse.raise_for_status()\nprint(response.json())",{"lang":177,"source":178},"cURL","curl --request POST 'https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Faudio\u002Falign' \\\n  --header 'X-API-Key: $VISIONSTORY_API_KEY' \\\n  --header 'Content-Type: application\u002Fjson' \\\n  --data '{\n  \"audio\": {\n    \"asset_id\": \"asset_audio_123456\"\n  },\n  \"text\": \"Welcome to VisionStory.\"\n}'","\u003Cpre class=\"shiki github-dark-default\" style=\"background-color:#0d1117;color:#e6edf3\" tabindex=\"0\">\u003Ccode>\u003Cspan class=\"line\">\u003Cspan style=\"color:#FF7B72\">from\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> visionstory \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">import\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> VisionStoryClient\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">client \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> VisionStoryClient.from_env()\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">alignment \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> client.align_audio(\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FFA657\">    text\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"Welcome to VisionStory.\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FFA657\">    asset_id\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"asset_audio_123456\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">)\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#79C0FF\">print\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">(alignment)\u003C\u002Fspan>\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Fpre>","\u003Cpre class=\"shiki github-dark-default\" style=\"background-color:#0d1117;color:#e6edf3\" tabindex=\"0\">\u003Ccode>\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">{\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">  \"data\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: {\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">    \"cost_credit\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\">1\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">    \"duration_sec\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\">1\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">    \"words\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: [\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">      {\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">        \"end_sec\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\">0.5\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">        \"speaker\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\">null\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">        \"start_sec\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\">0\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">        \"text\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"Hello\"\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">      },\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">      {\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">        \"end_sec\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\">1\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">        \"speaker\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\">null\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">        \"start_sec\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\">0.5\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">        \"text\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"world\"\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">      }\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">    ]\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">  },\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">  \"message\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"success\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">  \"server_time\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"2026-09-04T00:00:00Z\"\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">}\u003C\u002Fspan>\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Fpre>",1788547144633]