IMA Studio TTS

LeoYeAI/openclaw-master-skillsText-to-SpeechAudit failedSnapshot c6526f7316be

Installs: 0

Summary

Use when generating speech from text (text-to-speech) via IMA Open API. Use for: voice synthesis, TTS,朗读, 语音合成, 配音, 有声内容. Output: audio URL (mp3/wav). Flow: query products → create task → poll until done. Requires IMA API key. This skill targets seed-tts-2.0 only (seed-tts-1.1 is not supported). Default model is seed-tts-2.0.

SKILL.md

IMA TTS (Text-to-Speech)

Overview

Call IMA Open API to create text-to-speech audio. Same flow as other IMA creation skills: query products → create task → poll until done. Task type is text_to_speech. This skill targets seed-tts-2.0 only — seed-tts-1.1 is not supported; the script defaults to seed-tts-2.0 when no model is specified.

⚙️ How This Skill Works

This skill uses a bundled Python script scripts/ima_tts_create.py to call the IMA Open API:

Sends text (prompt) to https://api.imastudio.com
Uses --user-id only locally for preference storage
Returns an audio URL when synthesis is complete
Reflection mechanism: on create failure, retries up to 3 times with parameter adjustments

What gets sent to IMA: prompt (text to speak), model selection, parameters (e.g. voice_id, speed). Not sent: API key in prompt body; user_id is local only.

Agent Execution

Use the bundled script:

# List available TTS models (optional; default is seed-tts-2.0)
python3 {baseDir}/scripts/ima_tts_create.py --api-key $IMA_API_KEY --list-models

# Generate speech (default model: seed-tts-2.0; omit --model-id to use default)
python3 {baseDir}/scripts/ima_tts_create.py \
  --api-key $IMA_API_KEY \
  --model-id seed-tts-2.0 \
  --prompt "Text to be spoken here." \
  --user-id {user_id} \
  --output-json

Script outputs JSON; parse it for url and pass to the user via the UX protocol below.

Environment

Base URL: https://api.imastudio.com

Header	Required	Value
`Authorization`	✅	`Bearer ima_your_api_key_here`
`x-app-source`	✅	`ima_skills`
`x_app_language`	recommended	`en` / `zh`

GET /open/v1/product/list?app=ima&platform=web&category=text_to_speech

1. GET /open/v1/product/list?app=ima&platform=web&category=text_to_speech
   → Get attribute_id, credit, model_version, form_config

2. POST /open/v1/tasks/create
   → task_type: "text_to_speech", parameters[].parameters.prompt = text to speak

3. POST /open/v1/tasks/detail  { "task_id": "..." }
   → Poll every 2–5s until medias[].resource_status == 1 and status != "failed"
   → Read medias[].url (and optional duration_str, format)

Field	Type	Meaning
`resource_status`	int or null	0=处理中, 1=可用, 2=失败, 3=已删除；null 视为 0
`status`	string	"pending" / "processing" / "success" / "failed"
`url`	string	Audio URL when resource_status=1 (mp3/wav)
`duration_str`	string	Optional, e.g. "30s"
`format`	string	Optional, e.g. "mp3", "wav"

{
  "id": "task_xxx",
  "medias": [{
    "resource_status": 1,
    "status": "success",
    "url": "https://cdn.../output.mp3",
    "duration_str": "12s",
    "format": "mp3"
  }]
}

POST /open/v1/tasks/create

{
  "task_type": "text_to_speech",
  "enable_multi_model": false,
  "src_img_url": [],
  "parameters": [{
    "attribute_id":  "<from credit_rules>",
    "model_id":      "<model_id>",
    "model_name":    "<model_name>",
    "model_version": "<version_id>",
    "app":           "ima",
    "platform":      "web",
    "category":      "text_to_speech",
    "credit":        "<points>",
    "parameters": {
      "prompt":       "Text to be spoken.",
      "n":            1,
      "input_images": [],
      "cast":         {"points": "<points>", "attribute_id": "<attribute_id>"}
    }
  }]
}

category	Capability	Input
`text_to_speech`	Text → Speech	prompt (text to speak)

Parameter	Type	Required	Description
`prompt`	string	✅	Text to speak (合成文本).
`n`	int	✅	Usually 1.
`model`	string	✅	Sub-model: `seed-tts-2.0-expressive` (default) or `seed-tts-2.0-standard`.
`speaker`	string	optional	Speaker ID / 发音人，e.g. `zh_male_sophie_uranus_bigtts`（音色列表 1257544 中原生 voice_type）. 注意：使用原生格式（如 `zh_male__uranus_bigtts`），不支持 `BV_streaming` 格式。
`audio_params`	object	optional	`emotion`（情感）、`speech_rate`（语速 [-50,100]）、`loudness_rate`（音量 [-50,100]）等，见 1598757 请求 Body.
`additions`	object	optional	e.g. `{"explicit_language": "crosslingual", "context_texts": []}`.
`cast`	object	✅	`{"points": <credit>, "attribute_id": <attribute_id>}` from product list.

python3 ima_tts_create.py --api-key $IMA_API_KEY --model-id seed-tts-2.0 \
  --prompt "阳光青年音色测试，你好世界。" \
  --extra-params '{"model":"seed-tts-2.0-expressive","speaker":"zh_male_sophie_uranus_bigtts","audio_params":{"emotion":"neutral"},"additions":{"explicit_language":"crosslingual","context_texts":[]}}' \
  --output-json

询问项	对应参数	说明
要朗读的内容 / 旁白文案	`prompt`	合成文本，必填。若用户只给主题，可请用户提供具体文案或由你生成后让用户确认。

询问项	对应参数	选项来源与示例
音色 / 发音人	`speaker`	从项目内 `volcengine_tts_timbre_list.json`（或音色列表 1257544）按场景推荐：通用场景（魅力苏菲 `zh_male_sophie_uranus_bigtts`、Vivi `zh_female_vv_uranus_bigtts`、云舟 `zh_male_m191_uranus_bigtts`）、视频配音（大壹 `zh_male_dayi_uranus_bigtts`、猴哥 `zh_male_sunwukong_uranus_bigtts`）、角色扮演（知性灿灿 `zh_female_cancan_uranus_bigtts`、撒娇学妹 `zh_female_sajiaoxuemei_uranus_bigtts`）。可简短列出 3–5 个候选让用户选，或问「要男声/女声？偏解说/读书/助手？」再缩小范围。⚠️ 使用原生格式（`*_uranus_bigtts`）。

询问项	对应参数	说明与取值
情感 / 情绪	`audio_params.emotion`	部分音色支持，如 neutral、sad、angry；详见音色列表-多情感音色。
语速	`audio_params.speech_rate`	范围 [-50, 100]，0 为正常，100 约 2 倍速。可通过 `--extra-params '{"audio_params":{"speech_rate":20}}'` 传入。
音量	`audio_params.loudness_rate`	范围 [-50, 100]，0 为正常（mix 音色不支持）。
模型风格	`model`	`seed-tts-2.0-expressive`（默认，表现力强）或 `seed-tts-2.0-standard`（更稳定）。

User intent / phrasing	Parameter (if in form_config)	Notes
旁白 / 配音 / 朗读 / 把这段读出来	prompt + speaker（建议问）	先问清内容与音色，再调用；见上方「当用户说制作旁白/配音时如何询问」。
女声 / 女声朗读 / female voice	voice_id / voice_type / speaker	Use value from form_config or e.g. speaker ID
男声 / 男声朗读 / male voice	voice_id / voice_type / speaker	Use value from form_config or e.g. speaker ID
发音人 / 音色 / speaker	speaker	seed-tts-2.0: e.g. zh_male_sophie_uranus_bigtts，见 volcengine_tts_timbre_list.json（原生格式）
情感 / 情绪 / emotion	audio_params.emotion	e.g. "neutral", "sad"；部分音色支持
语速快/慢 / speed up/slow	audio_params.speech_rate	范围 [-50, 100]，0 为正常
音调 / pitch	pitch	If supported
大声/小声 / volume	audio_params.loudness_rate	范围 [-50, 100]
风格 expressive/standard	model	seed-tts-2.0: seed-tts-2.0-expressive / seed-tts-2.0-standard

{
  "user_{user_id}": {
    "text_to_speech": {
      "model_id": "...",
      "model_name": "...",
      "credit": 2,
      "last_used": "..."
    }
  }
}

🔊 开始语音合成，请稍候…
• 模型：[Model Name]
• 预计耗时：[X ~ Y 秒]
• 消耗积分：[N pts]

⏳ 语音合成中… [P]%
已等待 [elapsed]s，预计最长 [max]s

✅ 语音合成成功！
• 模型：[Model Name]
• 耗时：[actual]s
• 消耗积分：[N pts]
🔗 原始链接：[url]

❌ 语音合成失败
• 原因：[自然语言原因]
• 建议：换个模型重试或检查文本长度/内容

需要我帮你用其他模型重试吗？

Technical	✅ Say (CN)	✅ Say (EN)
401 Unauthorized	密钥无效或未授权，请至 imaclaw.ai 生成新密钥	API key invalid; generate at imaclaw.ai
4008 Insufficient points	积分不足，请至 imaclaw.ai 购买积分	Insufficient points; buy at imaclaw.ai
Invalid product attribute	参数配置异常，请稍后重试	Configuration error, try again later
Error 6006 / 6010	积分或参数不匹配，请换模型或重试	Points/params mismatch, try another model
resource_status == 2 / status failed	合成失败，建议换模型或缩短文本	Synthesis failed, try another model or shorter text
timeout	合成超时，请稍后重试	Timed out, try again later
Network error	网络不稳定，请检查后重试	Network unstable, check and retry

Mistake	Fix
prompt at top level	Put prompt inside `parameters[].parameters`
Wrong or missing attribute_id	Always call product list first; use credit_rules[0]
Single poll	Poll until all medias have resource_status == 1
Ignoring status when resource_status=1	Check status != "failed"
Sending params not in form_config/credit_rules	Use only params from product list; script reflection will strip others on retry

import time
import requests

BASE = "https://api.imastudio.com"
HEADERS = {
    "Authorization": "Bearer ima_your_key",
    "Content-Type": "application/json",
    "x-app-source": "ima_skills",
}

# 1. Product list
r = requests.get(
    f"{BASE}/open/v1/product/list",
    headers=HEADERS,
    params={"app": "ima", "platform": "web", "category": "text_to_speech"},
)
tree = r.json()["data"]
# ... find type=3 node, get attribute_id, model_id, model_version, credit ...

# 2. Create task
body = {
    "task_type": "text_to_speech",
    "enable_multi_model": False,
    "src_img_url": [],
    "parameters": [{
        "attribute_id": attribute_id,
        "model_id": model_id,
        "model_name": model_name,
        "model_version": model_version,
        "app": "ima", "platform": "web",
        "category": "text_to_speech",
        "credit": credit,
        "parameters": {
            "prompt": "Hello, world.",
            "n": 1,
            "input_images": [],
            "cast": {"points": credit, "attribute_id": attribute_id},
        },
    }],
}
r = requests.post(f"{BASE}/open/v1/tasks/create", headers=HEADERS, json=body)
task_id = r.json()["data"]["id"]

# 3. Poll
while True:
    r = requests.post(f"{BASE}/open/v1/tasks/detail", headers=HEADERS, json={"task_id": task_id})
    task = r.json()["data"]
    medias = task.get("medias") or []
    if not medias:
        time.sleep(3)
        continue
    rs = medias[0].get("resource_status")
    if rs is None: rs = 0
    if rs == 2 or (medias[0].get("status") or "").lower() == "failed":
        raise RuntimeError(medias[0].get("error_msg") or "failed")
    if rs == 1 and (medias[0].get("url") or medias[0].get("watermark_url")):
        url = medias[0]["url"] or medias[0]["watermark_url"]
        print(url)  # e.g. https://cdn.../output.mp3
        break
    time.sleep(3)

Item	Value
Task type	`text_to_speech`
Product list	`GET /open/v1/product/list?category=text_to_speech`
Create	`POST /open/v1/tasks/create` (prompt inside parameters[].parameters)
Poll	`POST /open/v1/tasks/detail` every 2–5s
Done when	All medias: resource_status=1, status≠"failed", url present
Script	`scripts/ima_tts_create.py` (--list-models, --model-id, --prompt, --output-json)

IMA Studio TTS

Summary

SKILL.md

IMA TTS (Text-to-Speech)

Overview

⚙️ How This Skill Works

Agent Execution

Environment

⚠️ MANDATORY: Always Query Product List First

Core Flow

Task Detail API — Actual Response Shape

API 2: Create Task

Supported Task Type & Models

seed-tts-2.0 — Verified request parameters

🎤 当用户说「帮我制作旁白/配音」时如何询问

必问

建议问（让用户选择）

可选问（按需补充）

📥 User Input Parsing (Parameter Recognition)

🧠 User Preference Memory

💬 User Experience Protocol (IM / Feishu / Discord)

Step 0 — Initial Acknowledgment (Normal Reply)

Step 1 — Pre-Generation Notification (message tool)

Step 2 — Progress

Step 3 — Success (message tool)

Step 4 — Failure (message tool)

Step 5 — Done

Common Mistakes

Security & Local Data

Python Example (Minimal)

Quick Reference

Related skills