文档中心

音视频理解与处理

API接入

查询任务

注意

发起请求前，必须在请求中添加公共字段部分的内容。

接口信息：

API：https://open.volcengineapi.com?Action=QuerySong&Version=2024-08-12

Method：POST

Aciton：QuerySong

Version：2024-08-12

请求参数：

Query：

参数
类型
是否必填
参数内容
Action
String
必选
QuerySong
Version
String
必选
2024-08-12

Body：

参数
类型
是否必填
描述
TaskID
String
必选
任务ID

请求示例：

Request Body：

{
"TaskID": "202408308513817850019840"
}

Response：

{
"Code": 0,
"Message": "success",
"Result": {
"TaskID": "202408308513817850019840",
"Status": 3, // 任务状态 0->等待中, 1->处理中, 2->成功, 3->失败
"Progress": 100, // 生成进度
"FailureReason": { // 任务失败原因，任务执行成功时为null
"Code": 300061,
"Msg": "InputLyricsPlagiarized"
},
"SongDetail": {
"AudioUrl": "xxxxx", // 音频地址 URL域名规则：v{1-50}-default.douyinvod.com
"Captions": "{}", // 歌词字幕
"Lyrics": "xxxxxxx", // 生成歌曲所使用的歌词
"Duration": 46.0024375, // 音频时长，单位秒（关联后付费按时长计费）
"Genre": "", // 曲风
"Mood": "", // 情绪
"Gender": "", // 性别
"TosPath": "", // 用户自定义tos保存路径
"CallbackURL": "", // 回调地址
"Timbre": "", // 音色
"Prompt": "xxxxxxx", // 生成纯音乐的提示词
"Instrument": "Saxophone,Guitar,Synthesizers", // 乐器
"GenreExtra": "Metal,City Pop", // 次级曲风
"Key": "A#", // 音乐调性
"Kmode": "Minor", // 音乐调式
"Tempo": "Grave", // 音乐节拍
"Scene": "Danceable,Funeral,Winter,Dance,Roadtrip,Sport", // 音乐场景
"Lang": "Chinese", // 语言
"StyleInfo":"{\"style_tags\":{\"genre\":[\"Easy Listening\"],\"genre_extra\":[\"Easy Listening\"],\"extra\":[\"non-canned music\"],\"mood\":[\"Romantic\"],\"scene\":[\"Flirt\",\"Coffee Shop\",\"Dating\",\"Love\",\"Valentine's day\"],\"speaker\":[\"nonvocal nongender\"],\"voice\":[\"nonvocal nontimbre\"],\"lang\":[\"Instrumental/Non-vocal\"],\"sinking\":[\"non-Sinking\"],\"instrument\":[\"Acoustic_Guitar\",\"Drums\",\"Percussion\",\"Percussive\",\"Strings\",\"Guitar\",\"nonvocal\"],\"tempo\":[\"empty tempo\"],\"mode\":[\"empty mode\"],\"key\":[\"empty key\"]},\"speaker_id\":38,\"duration\":40,\"freeform_text\":\"Drums, Love, non-canned music, romantic music, loving, acoustic guitar, Coffee Shop, Acoustic Guitar, sultry, acoustic, soft, Washboard, Guitar, peaceful, Percussive, Easy Listening, Riq or Rik, Flirt, Loving, affectionate, Percussion, seductive, relaxed, Military Drums, beautiful, Talking Drums, Strings, alluring, Romantic, Req, romantic, calm, gentle, Valentine's day, Dating\",\"lyrics_display\":\"[verse]\<20.00\>\\n[chorus]\<20.00\>\"}"
// StyleInfo 信息展示如下 v5.0才会返回StyleInfo：
// {
// "style_tags": { // 音频风格信息
// "genre": ["Easy Listening"],
// "genre_extra": ["Easy Listening"],
// "extra": ["non-canned music"],
// "mood": ["Romantic"],
// "scene": ["Flirt", "Coffee Shop", "Dating", "Love", "Valentine's day"],
// "speaker": ["nonvocal nongender"],
// "voice": ["nonvocal nontimbre"],
// "lang": ["Instrumental/Non-vocal"],
// "sinking": ["non-Sinking"],
// "instrument": ["Acoustic_Guitar", "Drums", "Percussion", "Percussive", "Strings", "Guitar", "nonvocal"],
// "tempo": ["empty tempo"],
// "mode": ["empty mode"],
// "key": ["empty key"]
// },
// "speaker_id": 38,
// "duration": 40, // 生成的音乐时长
// "freeform_text": "Drums, Love, non-canned music, romantic music, loving, acoustic guitar, Coffee Shop, Acoustic Guitar, sultry, acoustic, soft, Washboard, Guitar, peaceful, Percussive, Easy Listening, Riq or Rik, Flirt, Loving, affectionate, Percussion, seductive, relaxed, Military Drums, beautiful, Talking Drums, Strings, alluring, Romantic, Req, romantic, calm, gentle, Valentine's day, Dating",
// "lyrics_display": "[verse]<20.00>\n[chorus]<20.00>" // 各段结构时长
// }
}
},
"ResponseMetadata": {
"RequestId": "02172492501059326050340cd5020003c070b82113f9c52a42fa4",
"Action": "QuerySong",
"Version": "2024-08-12",
"Service": "imagination",
"Region": "cn-beijing",
"Error": null
}
}

注意

接口默认不提供歌词文件，如需要歌词时间戳可以通过解析“歌词字幕”实现

默认提供wav音频文件（因视频云链路有默认转码逻辑，可能出现mp4等格式情况），该url仅供参考您转存使用、请勿直接用在应用中，您需要拿到url后自行做转存并转化成您预期的音频格式，url有效期为1年。

curl：

curl --location --request POST 'https://open.volcengineapi.com/?Action=QuerySong&Version=2024-08-12' \
--header 'Host: open.volcengineapi.com' \#Api Host，详见请求Host说明
--header 'Content-Type: application/json' \
--header 'X-Date: 20251201T103833Z' \ #请求时间戳，详见请求Header X-Date说明
--header 'X-Content-Sha256: ******' \ #对完整请求Body的加密结果，详见请求Header X-Content-Sha256说明
--header 'Authorization: ******' \ #签名信息，详见请求Header Authorization说明
--data-raw '{
"TaskID": "202408308513817850019840"
}

demo：

Golang：

QuerySong.zip

Java：

QuerySong.zip

Python：

QuerySong.zip

注：未提供demo的编程语言，烦请根据文档说明和参照curl示例、已有语言demo示例自行编写。

最近更新时间：2026.01.16 19:01:22

这个页面对您有帮助吗？

有用

无用

参数	类型	是否必填	参数内容
Action	String	必选	QuerySong
Version	String	必选	2024-08-12