异步任务接口使用指南
概述
对于生成时长较长的任务(如 3D 建模、视频生成、长语音合成等),平台提供了专门的异步任务接口,让您能够高效地处理耗时操作而无需长时间等待响应。
接口架构
异步任务接口采用提交-查询模式:
- 提交接口:用于创建异步任务,例如文本生成音乐的提交接口为
/async/music/generations
- 查询接口:统一的任务状态查询接口
https://ai.gitee.com/api/v1/task/<task_id>
- 任务取消接口:
https://ai.gitee.com/api/v1/task/<task_id>/cancel
- 配额查询接口:
https://ai.gitee.com/v1/tasks/available-quota
- 任务状态接口:
https://ai.gitee.com/v1/task/<task_id>/status
- 任务记录接口:
https://ai.gitee.com/v1/task/<task_id>
工作流程
- 提交任务 → 获取
task_id
和查询 URL - 轮询查询 → 检查任务状态
- 获取结果 → 下载生成 的文件
完整示例:音乐生成
以下示例演示如何使用 ACE-Step 音乐大模型生成音乐:
Python 实现
python
import os
import requests
import base64
from PIL import Image
from io import BytesIO
from requests_toolbelt.multipart.encoder import MultipartEncoder
API_URL = "https://ai.gitee.com/v1/async/music/generations"
headers = {
"Authorization": "Bearer <your token>",
}
def query(payload):
data = {}
for key, value in payload.items():
if value is None:
data[key] = ""
elif isinstance(value, list):
data[key] = ",".join(map(str, value))
elif isinstance(value, bool):
data[key] = str(value).lower()
else:
data[key] = str(value)
multipart_data = MultipartEncoder(fields=data)
headers["Content-Type"] = multipart_data.content_type
response = requests.post(API_URL, headers=headers, data=multipart_data)
return response.json()
output = query({
"model": "ACE-Step-v1-3.5B",
"task": "text2music",
"duration": 60,
"prompt": "pop, synth, drums, guitar, 120 bpm, upbeat, catchy, vibrant, female vocals, polished vocals",
"lyrics": """[Verse]
Neon lights across the sky
Every moment passing by
Your smile catches in my mind
Like a snapshot frozen time
[Chorus]
We're dancing through the night
Under these electric lights
Don't need to think about tomorrow
Just feel this moment right
[Verse]
City pulse beneath our feet
Hearts aligned to steady beat
Take my hand and follow me
Into who we're meant to be
[Bridge]
One life, one chance
One perfect night romance
Our story's just beginning
In this magical dance""",
"infer_steps": 60,
"lora_name": 'None',
"guidance_scale": 15,
"guidance_scale_text": 0,
"guidance_scale_lyric": 0,
"scheduler_type": "euler",
"cfg_type": "apg",
"omega_scale": 10,
"guidance_interval": 0.5,
"guidance_interval_decay": 0,
"min_guidance_scale": 3,
"use_erg_tag": True,
"use_erg_lyric": True,
"use_erg_diffusion": True,
})
query_url = output["urls"]["get"]
while True:
resp = requests.get(query_url, headers=headers).json()
print("task status: ", resp["status"])
if resp["status"] == "failure":
print(resp)
print("task failed")
os._exit(1)
if resp["status"] == "success":
break
file_url = resp["output"]["file_url"]
print('final url ', file_url)
resp = requests.get(file_url)
with open("output.mp3", "wb") as f:
f.write(resp.content)
主要参数说明
通用参数
model
: 使用的模型名称(如 "ACE-Step-v1-3.5B"