文生语音 API

https://cp.compshare.cn

Authorization: Bearer <YOUR_API_KEY>

POST https://cp.compshare.cn/audio/v1/speech/jobs

curl -X POST 'https://cp.compshare.cn/audio/v1/speech/jobs' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: speech-preset-001' \
  -d '{
    "text": "你好，欢迎使用优云智算文生语音服务。",
    "language": "ZH",
    "voice": {"source": "preset", "voice_id": "<PRESET_VOICE_ID>"},
    "speed": 1.0,
    "auto_emotion": true
  }'

curl -X POST 'https://cp.compshare.cn/audio/v1/speech/jobs' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: speech-custom-001' \
  -d '{
    "text": "欢迎来到重庆，这是一段温柔的城市介绍。",
    "language": "ZH",
    "voice": {"source": "custom", "voice_id": "<CUSTOM_VOICE_ID>"},
    "speed": 0.9,
    "auto_emotion": false,
    "emotion_description": "温柔、自然，像朋友在介绍自己的家乡",
    "emotion_strength": 0.8,
    "pronunciations": [
      {"word": "重庆", "kind": "pinyin", "value": "chong2 qing4"}
    ]
  }'

{
  "auto_emotion": false,
  "emotion_vector": [0.4, 0, 0, 0, 0, 0, 0, 0.2],
  "emotion_vector_mode": "mixed",
  "emotion_strength": 0.8
}

{"task_id": "019xxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}

GET https://cp.compshare.cn/audio/v1/speech/jobs/{task_id}

curl 'https://cp.compshare.cn/audio/v1/speech/jobs/<TASK_ID>' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'

{
  "task": {
    "task_id": "019xxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "type": "text_to_speech",
    "input": {
      "text": "你好，欢迎使用优云智算。",
      "language": "ZH",
      "voice": {"source": "preset", "voice_id": "<PRESET_VOICE_ID>"},
      "auto_emotion": true,
      "emotion_strength": 0.8,
      "speed": 1
    },
    "status": "succeeded",
    "attempt": 1,
    "max_attempts": 3,
    "point_cost": 2,
    "point_status": "consumed",
    "error_message": "",
    "output_url": "https://example.com/generated/output.wav",
    "output_size": 240000,
    "created_at": 1789459200,
    "started_at": 1789459203,
    "finished_at": 1789459215
  }
}

GET https://cp.compshare.cn/audio/v1/speech/jobs

curl 'https://cp.compshare.cn/audio/v1/speech/jobs?offset=0&limit=20&statuses=queued&statuses=generating' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'

{"items": [], "total": 0, "status_counts": {"succeeded": 3}}

POST https://cp.compshare.cn/audio/v1/speech/jobs/{task_id}/cancel

curl -X POST 'https://cp.compshare.cn/audio/v1/speech/jobs/<TASK_ID>/cancel' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'

{"task_id": "019xxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "status": "cancelled"}

DELETE https://cp.compshare.cn/audio/v1/speech/jobs/{task_id}

curl -X DELETE 'https://cp.compshare.cn/audio/v1/speech/jobs/<TASK_ID>' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'

{"task_id": "019xxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "deleted": true}

GET https://cp.compshare.cn/audio/v1/voices

curl 'https://cp.compshare.cn/audio/v1/voices?kind=preset' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'
 
curl 'https://cp.compshare.cn/audio/v1/voices?kind=custom' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'

{
  "items": [{
    "voice_id": "<PRESET_VOICE_ID>",
    "kind": "preset",
    "name": "示例旁白",
    "style_tags": ["自然"],
    "audio_url": "https://example.com/voice-sample.wav",
    "created_at": 1789459200
  }],
  "total": 1
}

POST https://cp.compshare.cn/audio/v1/upload_urls

curl -X POST 'https://cp.compshare.cn/audio/v1/upload_urls' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"file_name":"reference.wav","content_type":"audio/wav","file_size":240000}'

{
  "object_key": "ai-audio/production/uploads/<OWNER>/<UPLOAD_ID>/staging/reference.wav",
  "upload_url": "https://example.com/upload/reference.wav?UCloudPublicKey=...&Signature=...&Expires=1789460100",
  "public_url": "https://example.com/upload/reference.wav",
  "authorization": "",
  "bucket": "<BUCKET>",
  "region": "<REGION>",
  "expires_at": 1789460100
}

curl --fail-with-body -X PUT '<UPLOAD_URL>' \
  -H 'Content-Type: audio/wav' \
  --data-binary '@reference.wav'

POST https://cp.compshare.cn/audio/v1/assets

curl -X POST 'https://cp.compshare.cn/audio/v1/assets' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "object_key": "<OBJECT_KEY>",
    "file_name": "reference.wav",
    "content_type": "audio/wav",
    "file_size": 240000,
    "duration_ms": 5000
  }'

{
  "asset": {
    "asset_id": "<ASSET_ID>",
    "purpose": "speech_reference",
    "file_name": "reference.wav",
    "content_type": "audio/wav",
    "file_size": 240000,
    "duration_ms": 5000,
    "public_url": "https://example.com/reference/reference.wav",
    "created_at": 1789459200
  }
}

curl -X POST 'https://cp.compshare.cn/audio/v1/speech/jobs' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: speech-reference-001' \
  -d '{
    "text": "这是使用参考音频生成的语音。",
    "voice": {"source": "asset", "asset_id": "<ASSET_ID>"},
    "save_voice": true,
    "voice_name": "我的旁白音色"
  }'

POST https://cp.compshare.cn/audio/v1/voices

curl -X POST 'https://cp.compshare.cn/audio/v1/voices' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: custom-voice-001' \
  -d '{"asset_id":"<ASSET_ID>","name":"我的旁白音色"}'

{
  "voice": {
    "voice_id": "<CUSTOM_VOICE_ID>",
    "kind": "custom",
    "name": "我的旁白音色",
    "style_tags": [],
    "audio_url": "https://example.com/custom-voice/reference.wav",
    "created_at": 1789459200
  }
}

DELETE https://cp.compshare.cn/audio/v1/voices/{voice_id}

curl -X DELETE 'https://cp.compshare.cn/audio/v1/voices/<CUSTOM_VOICE_ID>' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'

{"voice_id": "<CUSTOM_VOICE_ID>", "deleted": true}

GET https://cp.compshare.cn/audio/v1/pricing

curl 'https://cp.compshare.cn/audio/v1/pricing' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'

{
  "enabled": true,
  "pricing_version": 3,
  "unit_characters": 10,
  "costs": {"text_to_speech": 2},
  "balance": {"total_points": 100, "reserved_points": 20, "available_points": 80}
}

积分费用 = ceil(正文计费字符数 × costs.text_to_speech / 10)

GET https://cp.compshare.cn/minimax/v2/query/point_packages

curl 'https://cp.compshare.cn/minimax/v2/query/point_packages' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'

{
  "items": [{
    "id": "<PACKAGE_ID>",
    "code": "<PACKAGE_CODE>",
    "name": "示例积分包",
    "status": "active",
    "total_points": 100,
    "remaining_points": 80,
    "reserved_points": 10,
    "available_points": 70,
    "created_at": 1789459200
  }],
  "total": 1
}

{
  "type": "error",
  "error": {
    "type": "bad_request_error",
    "message": "Idempotency-Key is required and must contain 1 to 128 characters",
    "http_code": "400"
  },
  "request_id": "<REQUEST_ID>"
}

import json
import os
import time
import uuid
from pathlib import Path
from urllib.request import Request, urlopen
 
BASE_URL = "https://cp.compshare.cn"
API_KEY = os.environ["COMPSHARE_API_KEY"]
 
 
def api(method, path, body=None, idempotency_key=None):
    headers = {"Authorization": f"Bearer {API_KEY}", "Accept": "application/json"}
    data = None
    if body is not None:
        headers["Content-Type"] = "application/json"
        data = json.dumps(body, ensure_ascii=False).encode("utf-8")
    if idempotency_key:
        headers["Idempotency-Key"] = idempotency_key
    request = Request(BASE_URL + path, data=data, headers=headers, method=method)
    # 非 2xx 响应由 urlopen 抛出 HTTPError；2xx 响应仍需检查业务错误。
    with urlopen(request, timeout=60) as response:
        result = json.load(response)
    if result.get("RetCode", 0) != 0 or "error" in result:
        raise RuntimeError(result)
    return result
 
 
text = "你好，欢迎使用优云智算文生语音服务。"
pricing = api("GET", "/audio/v1/pricing")
if not pricing["enabled"]:
    raise RuntimeError("语音生成当前不可用")
characters = sum(character.isalpha() or character.isdecimal() for character in text)
unit = pricing["unit_characters"]
cost = (characters * pricing["costs"]["text_to_speech"] + unit - 1) // unit
if pricing["balance"]["available_points"] < cost:
    raise RuntimeError("可用积分不足")
 
voice_id = os.environ.get("COMPSHARE_VOICE_ID")
if not voice_id:
    voices = api("GET", "/audio/v1/voices?kind=preset")["items"]
    if not voices:
        raise RuntimeError("当前没有可用的预设音色")
    voice_id = voices[0]["voice_id"]
 
# 保存此键；若创建请求超时，应使用同一键和相同请求重试。
idempotency_key = str(uuid.uuid4())
print("Idempotency-Key:", idempotency_key)
result = api("POST", "/audio/v1/speech/jobs", {
    "text": text,
    "language": "ZH",
    "voice": {"source": "preset", "voice_id": voice_id},
    "speed": 1.0,
    "auto_emotion": True,
}, idempotency_key=idempotency_key)
task_id = result["task_id"]
print("task_id:", task_id)
 
deadline = time.monotonic() + 1200
while time.monotonic() < deadline:
    task = api("GET", f"/audio/v1/speech/jobs/{task_id}")["task"]
    if task["status"] == "succeeded":
        # 下载公共结果地址时无需携带模型 API Key。
        with urlopen(task["output_url"], timeout=60) as audio:
            Path("speech.wav").write_bytes(audio.read())
        print("已保存 speech.wav，消耗积分：", task["point_cost"])
        break
    if task["status"] in {"failed", "cancelled"}:
        raise RuntimeError(task["error_message"] or task["status"])
    time.sleep(3)
else:
    raise TimeoutError(f"轮询超时，可继续查询任务 {task_id}")