API 文档

流程概览

场景A：首次登录/注册（仅首次使用时执行一次）

场景B：已登录用户修改资料（token 有效期内随时可调）

资料编辑表单字段

保存资料请求示例

{
  "user_id": 12345,
  "user_info": {
    "username": "小明",
    "gender": "male",
    "age": 28,
    "city": "深圳",
    "profession": "软件工程师",
    "interests": "科技,旅行,摄影"
  }
}

资料标签接口

GET /api/user/profile-tags — 无需参数，返回两组标签供表单使用：

{
  "interests": [
    {"id": 1198, "name": "科技"},
    {"id": 1199, "name": "旅行"}
  ],
  "professions": [
    {"id": 2, "name": "学生"},
    {"id": 3, "name": "职场人士"}
  ]
}

三步音色创建流程

录音要求

步骤① 上传音频表单

步骤③ 保存表单

完整调用示例（JavaScript）

// 步骤①：上传音频（voice_id=0 表示新增模式）
const form1 = new FormData();
form1.append('user_id', '12345');
form1.append('voice_name', '我的声音');
form1.append('gender', 'male');
form1.append('description', '我的专属音色');
form1.append('voice_id', '0');  // 必填：0=新增，>0=编辑已有音色
form1.append('file', audioBlob, 'recording.wav');

const res1 = await fetch('/api/user/voices/upload', { method: 'POST', body: form1 });
const { id: voiceId } = await res1.json();  // voiceId = 5

// 步骤②：ASR识别（同一份音频，仅供前端展示，不可编辑）
const form2 = new FormData();
form2.append('file', audioBlob, 'recording.wav');
const res2 = await fetch('/api/user/voices/recognize', { method: 'POST', body: form2 });
const { text } = await res2.json();  // text = "今天天气真好，我们一起去公园散步吧"（仅展示）

// 步骤③：保存确认（传入步骤②识别的 transcript + 元信息；后端自动提取声纹并注册）
const res3 = await fetch('/api/user/voices/save', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    user_id: 12345,
    id: voiceId,
    voice_name: '我的声音',
    emoji: '🎙️',
    gender: 'male',
    description: '我的专属音色'
  })
});
const result = await res3.json();
if (result.success) {
  console.log('音色创建成功，声纹已录入');
  console.log('后端ASR识别的transcript:', result.transcript);
}

音频编辑器是音色管理中的核心功能，用于在音色上传后对音频进行编辑优化。以下为编辑器提供的核心能力及对应的 API 调用。

核心功能一览

编辑模式（重新上传）流程

创建AI角色所需表单字段

创建流程

标签选择说明

三类标签的含义：

创建请求示例

{
  "user_id": 12345,
  "name": "旅行达人小飞",
  "voice_id": "8",
  "podcast_type": "travel",
  "identity": [1, 3],
  "personality": [2, 5],
  "bio": [1, 4],
  "user_title": "旅伴",
  "role_config": "25岁户外旅行达人，走过全国30多个省份，擅长实用攻略与风土人情讲解，说话风格轻松活泼",
  "is_published": true
}

AI角色管理

系统中的标签分为两大类：用户资料标签（用于个人资料编辑）和 AI定向标签（用于AI角色创建和播客生成）。两类标签分别存储在不同的表中，通过不同的接口获取。

标签体系总览

UI 实现建议

标签获取流程

播客生成通过 WebSocket 流式协议进行（不支持 HTTP 同步请求）。以下为创建播客的完整表单字段和流程说明。

创建播客表单字段

创建流程

演播风格（play_types）

GET /api/play-types 返回所有演播风格列表，决定播客的文体形式：

{
  "play_types": [
    {"id": 1, "name": "播客对聊", "desc": "两个AI角色以对话形式展开节目"},
    {"id": 2, "name": "嘉宾访谈", "desc": "一人主持一人受访的访谈形式"},
    {"id": 3, "name": "电台讲述", "desc": "单人独白式电台讲述"},
    {"id": 4, "name": "相声", "desc": "双人相声表演形式"}
    // ...更多风格
  ]
}

WebSocket 消息流

生成播客的表单字段按以下顺序填写，部分字段存在条件显示逻辑（依赖前序字段的选择结果）。

播客场景（podcast_type）和标签维度通过 podcast_type_tag 关联表建立关联，标签的获取与场景选择严格绑定。

步骤1：上传或录制音频（只存内存）

步骤2：音频编辑器编辑

步骤3：点击"保存音色"（此时才上传落库）

后端校验（步骤④保存时，任一不通过直接返回失败）

第三方需要调用的接口

第三方不需要（也不应该）调用的接口

请求参数 (JSON Body)

响应示例

{
  "success": true,
  "message": "验证码已发送"
}

请求参数 (JSON Body)

响应示例

{
  "user_id": 12345,
  "username": "用户昵称",
  "phone": "138****0000",
  "avatar_url": "",
  "token": "a1b2c3d4e5f6..."
}

请求参数 (JSON Body)

响应示例

{
  "logged_in": true,
  "user_id": 12345,
  "username": "用户昵称",
  "phone": "138****0000",
  "avatar_url": ""
}

连接地址

wss://dev.nice-ai.cn/podcast/ws?api_key=sk-xxxxx

架构说明：应用端与服务端的职责划分

首帧请求参数 (JSON)

规则文档占位符与接口参数对应关系

首帧示例（完整参数）

{
  "user_id": 12345,
  "prompt": "深圳的早餐文化，尤其是肠粉",
  "ai_character_ids": [6, 7],
  "podcast_type_id": 1,             // 播客场景ID（必填，通过 /api/podcast-types 获取）
  "env_info": {                       // 应用端提交实时环境（替代服务端调高德/天气API）
    "location": "深圳市南山区科技园",
    "city": "深圳", "province": "广东",
    "lng": 113.9401, "lat": 22.5266,
    "weather": "晴", "temperature": "28"
  },
  "nearby_info": {                     // 应用端提交周边信息（替代服务端调景点/路线/美食API）
    "attractions": "世界之窗、欢乐谷、锦绣中华",
    "route": "从科技园地铁→世界之窗站→步行500米",
    "foods": "肠粉、煲仔饭、糖水"
  },
  "photo_description": "一张街边肠粉店的照片，蒸汽腾腾，老板正在制作肠粉，招牌写着'正宗石磨肠粉'",
  "system_context": "用户是一名35岁男士，当前在深圳旅游，喜欢探索本地美食",
  "podcast_tag_dims": {
    "12": [45],          // 主播身份（单选）
    "13": 52,             // 研究方向（单选）
    "14": [60, 61]       // 擅长内容风格（多选）
  },
  "play_type_id": 1,                   // 演播风格ID（可选，通过 /api/podcast-type-play-types?type_id=1 获取该场景可用风格）
  "word_count": 800,
  "audio_format": "mp3",
  "speed": 1.0,
  "public": true
}
// 注意：chat_summary 无需应用端提交，由 S2S 语音服务自动总结并写入 message 表，
// 播客生成时服务端自动按 (user_id, ai_character_ids[0]) 读取最新对话总结注入 {chat_summary} 占位符

首帧示例（匿名调用，无 user_id）

{
  "prompt": "深圳的早餐文化",
  "ai_character_ids": [6],
  "podcast_type_id": 1,
  "photo_description": "街边肠粉店照片，蒸汽腾腾",
  "system_context": "用户是一名35岁男士，在深圳工作，喜欢旅游和美食，当前时间是上午",
  "word_count": 800,
  "audio_format": "mp3"
}

服务端响应消息类型

meta 帧示例

{
  "type": "meta",
  "podcast_id": "a1b2c3d4e5f6a7b8",
  "title": "深圳肠粉：一碗烟火里的城市记忆",
  "intro": "探寻深圳早餐文化的灵魂——肠粉",
  "cover_desc": "清晨的深圳街边，蒸汽腾腾的肠粉店招牌",
  "hosts": [
    {"label": "A", "voice": "8", "name": "如意", "emoji": "🎤", "gender": "female"},
    {"label": "B", "voice": "12", "name": "小松", "emoji": "🎧", "gender": "male"}
  ],
  "format": "mp3",
  "sample_rate": 48000,
  "channels": 1,
  "word_count_target": 800
}

segment 帧示例

{
  "type": "segment",
  "speaker": "A",
  "voice": "8",
  "name": "如意",
  "emoji": "🎤",
  "text": "今天呢，我们来说说深圳人最爱吃的早餐"
}

done 帧示例

{
  "type": "done",
  "podcast_id": "a1b2c3d4e5f6a7b8",
  "title": "深圳肠粉：一碗烟火里的城市记忆",
  "intro": "探寻深圳早餐文化的灵魂——肠粉",
  "script_text": "A：今天呢，我们来说说深圳人最爱吃的早餐\nB：你说的是肠粉吧...\nA：对对对...",
  "duration_sec": 245.3,
  "word_count": 856,
  "audio_file": "a1b2c3d4e5f6a7b8.mp3",
  "audio_url": "/podcast/audio/a1b2c3d4e5f6a7b8.mp3",
  "audio_size": 2943600,
  "cover_url": "/podcast/cover/a1b2c3d4e5f6a7b8.jpg",
  "format": "mp3",
  "tokens_in": 1280,
  "tokens_out": 920,
  "segments": [
    {"speaker": "A", "voice": "8", "name": "如意", "emoji": "🎤", "text": "今天呢，我们来说说深圳人最爱吃的早餐", "start_sec": 0.0, "end_sec": 3.2},
    {"speaker": "B", "voice": "12", "name": "小松", "emoji": "🎧", "text": "你说的是肠粉吧", "start_sec": 3.2, "end_sec": 6.5}
  ]
            }

客户端中断

客户端可在任意时刻发送中断帧来终止生成：

{
  "type": "abort"
}

JavaScript 调用示例

// 连接 WebSocket（携带 API Key）
const ws = new WebSocket('wss://dev.nice-ai.cn/podcast/ws?api_key=sk-xxxxx');
ws.binaryType = 'arraybuffer';

// 连接成功后发送首帧
ws.onopen = () => {
  ws.send(JSON.stringify({
    user_id: 12345,
    prompt: '深圳的早餐文化',
    ai_character_ids: [6, 7],
    podcast_type_id: 1,          // 播客场景ID（必填，通过 GET /api/podcast-types 获取）
    word_count: 800,
    audio_format: 'mp3',
    speed: 1.0,
    public: true,
    system_context: '用户是一名35岁男士，当前在深圳旅游...'
  }));
};

// 接收消息
ws.onmessage = (event) => {
  if (event.data instanceof ArrayBuffer) {
    // 二进制 PCM 音频数据（48kHz/16bit/单声道），送入 AudioContext 播放
    playAudioChunk(event.data);
  } else {
    const msg = JSON.parse(event.data);
    switch (msg.type) {
      case 'meta':
        console.log('播客标题:', msg.title, '封面描述:', msg.cover_desc);
        break;
      case 'segment':
        console.log(`[${msg.speaker}] ${msg.text}`);
        break;
      case 'opening_line':
        console.log('AI 开场白:', msg.text);
        break;
      case 'done':
        console.log('生成完成, 音频:', msg.audio_url, '时长:', msg.duration_sec);
        console.log('分段字幕:', msg.segments);  // 含 start_sec/end_sec 时间戳
        break;
      case 'aborted':
        console.log('已中断生成');
        break;
      case 'warning':
        console.warn('警告[' + msg.stage + ']:', msg.message);  // 非致命，主流程继续
        break;
      case 'error':
        console.error('生成失败:', msg.message, msg.stage || '');
        ws.close();
        break;
    }
  }
};

// 中断生成
// ws.send(JSON.stringify({ type: 'abort' }));

Query 参数

响应示例

{
  "podcasts": [
    {
      "id": 1,
      "title": "深圳肠粉",
      "content": "深圳的早餐文化",
      "hosts": [
        {"voice_id": "8", "name": "如意", "emoji": "🎀"},
        {"voice_id": "12", "name": "晓松", "emoji": "🎙️"}
      ],
      "audio_url": "/audio/a1b2c3d4.mp3",
      "cover_url": "/cover/a1b2c3d4.jpg",
      "duration": 245,
      "tokens": 0,
      "address": "",
      "prompt": "深圳的早餐文化",
      "public": true,
      "created_at": 1719500000,
      "likes": 42,
      "favorites": 18,
      "username": "播客创作者"
    }
  ]
}

无需认证，返回已发布到广场的随机公开播客列表。支持传入 user_id 查当前用户的点赞/收藏状态。

Query 参数

响应示例

{
  "podcasts": [
    {
      "id": 1,
      "title": "深圳肠粉",
      "content": "深圳的早餐文化",
      "hosts": [
        {"voice_id": "8", "name": "如意", "emoji": "🎀"},
        {"voice_id": "12", "name": "晓松", "emoji": "🎙️"}
      ],
      "audio_url": "/audio/a1b2c3d4.mp3",
      "cover_url": "/cover/a1b2c3d4.jpg",
      "duration": 245,
      "prompt": "深圳的早餐文化",
      "username": "播客创作者",
      "created_at": 1719500000,
      "likes": 42,
      "favorites": 18,
      "downloads": 56,
      "user_liked": true,
      "user_favorited": false
    }
  ],
  "total": 56,
  "page": 1
}

路径参数

响应示例

{
  "podcast_id": "a1b2c3d4e5f6a7b8",
  "title": "深圳肠粉",
  "intro": "探寻深圳早餐文化",
  "prompt": "深圳的早餐文化",
  "hosts": [...],
  "audio_file": "a1b2c3d4e5f6a7b8.mp3",
  "cover_url": "/cover/a1b2c3d4e5f6a7b8.jpg",
  "duration_sec": 245.3,
  "format": "mp3",
  "created_at": 1719500000
}

路径参数

使用示例

// 直接下载
fetch('https://dev.nice-ai.cn/audio/a1b2c3d4e5f6a7b8.mp3')
  .then(res => res.blob())
  .then(blob => {
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = 'podcast.mp3';
    a.click();
  });

// 或嵌入 audio 标签
// <audio src="https://dev.nice-ai.cn/audio/a1b2c3d4e5f6a7b8.mp3" controls></audio>

路径参数

使用示例

// 直接展示封面
<img src="https://dev.nice-ai.cn/cover/a1b2c3d4e5f6a7b8.jpg"
     alt="播客封面" style="width:300px;height:300px;">

// 下载封面
fetch('https://dev.nice-ai.cn/cover/a1b2c3d4e5f6a7b8.jpg')
  .then(res => res.blob())
  .then(blob => {
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = 'cover.jpg';
    a.click();
  });

路径参数

Query 参数

响应示例

{
  "liked": true,
  "likes": 42
}

重复请求会切换点赞状态。liked 表示当前是否已点赞，likes 为最新点赞总数。

调用示例

fetch('/api/podcast/123/like?user_id=456', { method: 'POST' })

路径参数

Query 参数

响应示例

{
  "favorited": true,
  "favorites": 18
}

重复请求切换收藏状态。

调用示例

fetch('/api/podcast/123/favorite?user_id=456', { method: 'POST' })

路径参数

Query 参数

响应示例

{
  "downloads": 56
}

调用示例

fetch('/api/podcast/123/download?user_id=456', { method: 'POST' })

Query 参数

响应示例

{
  "ranking": [
    {
      "rank": 1,
      "id": 123,
      "title": "深圳早餐文化",
      "username": "创作者",
      "likes": 42,
      "favorites": 18,
      "audio_url": "/audio/a1b2c3d4.mp3",
      "duration": 245,
      "cover_url": "/cover/a1b2c3d4.jpg"
    }
  ],
  "period": "daily"
}

按 likes + favorites 综合热度降序排列。

调用示例

fetch('/api/podcasts/ranking?period=weekly&limit=10')

随机返回一条精选置顶播客（public=2），用于 APP 播客列表置顶展示。无需认证。

响应示例

{
  "podcast": {
    "id": 100,
    "title": "精选播客标题",
    "intro": "播客内容简介...",
    "hosts": [
      {"voice_id": "1", "name": "小美", "emoji": "🎤"}
    ],
    "audio_url": "https://.../xxx.mp3",
    "duration": 300,
    "cover_url": "https://.../cover.jpg",
    "likes": 10,
    "favorites": 5,
    "username": "作者名",
    "word_count": 1500,
    "featured": true
  }
}

无需认证，返回所有可用的预置音色。

响应示例

{
  "voices": [
    {
      "id": "8",
      "name": "如意",
      "emoji": "🎀",
      "gender": "female",
      "tags": ["活泼", "开朗", "贴心"],
      "description": "26岁，女，深圳人，纯正普通话，声音清脆柔和，感情丰富，性格活泼开朗",
      "language": "zh",
      "accent": "#a855f7"
    },
    {
      "id": "12",
      "name": "晓松",
      "emoji": "🎙️",
      "gender": "male",
      "tags": ["厚实", "磁实", "北京话"],
      "description": "51岁，北京人，公众认知学者、评论员，声音厚实有磁性",
      "language": "zh",
      "accent": "#3b82f6"
    },
    {
      "id": "mina",
      "name": "米娜",
      "emoji": "🌟",
      "gender": "female",
      "tags": ["新闻", "讲述", "穿透力"],
      "description": "30岁，北京大妞，节目主持与播音工作，声音成熟活泼，精通30多种语言",
      "language": "zh",
      "accent": "#3b82f6"
    },
    {
      "id": "xiaoxiong",
      "name": "小熊",
      "emoji": "📺",
      "gender": "male",
      "tags": ["短视频口播", "深刻讲述", "挖掘价值"],
      "description": "36岁，自媒体博主，深圳创业者，声音成熟稳重，声线厚实深刻",
      "language": "zh",
      "accent": "#3b82f6"
    },
    {
      "id": "17",
      "name": "迪丽",
      "emoji": "🔬",
      "gender": "female",
      "tags": ["深度", "哲理", "看透营销本质"],
      "description": "34岁，新疆人，青年女声，柔和清甜的中系声线，自带轻微软糯感",
      "language": "zh",
      "accent": "#ec4899"
    }
  ]
}

Query 参数

响应示例

{
  "voices": [
    {
      "id": 1,
      "voice_name": "我的声音",
      "audio_file": "abc123.mp3",
      "transcript": "识别出的文本内容",
      "emoji": "🎙️",
      "public": 0,
      "created_at": "2026-06-28 10:30:00"
    }
  ]
}

请求参数 (multipart/form-data)

响应示例

{
  "id": 1,
  "voice_name": "我的声音",
  "audio_file": "/root/.../user_voices/abc123.wav"
}

管理员创建音色，音频一律保存到 voices/user_voices/（存储统一目录铁律，不按类型分目录）：system→user_id=0；star→user_id=管理员ID。仅支持 system 和 star，不接受 user 类型。

请求参数 (multipart/form-data)

响应示例

{
  "id": 42,
  "voice_name": "周杰伦音色",
  "voice_type": "star",
  "audio_file": "/root/nice_ai/voices/user_voices/star_abc123.wav"
}

Query 参数

响应示例

{
  "user_id": 12345,
  "username": "用户昵称",
  "phone": "138****0000",
  "avatar_url": "",
  "role": "user"
}

Query 参数

响应示例

{
  "quota": 10,
  "podcast_quota": 10,
  "voice_quota": 3,
  "ai_quota": 2,
  "plan": "free",
  "plan_name": "免费版"
}

字段说明

请求参数 (JSON Body)

请求示例（方式A：token 鉴权）

POST /api/user/profile HTTP/1.1
Authorization: Bearer a1b2c3d4e5f6...
X-User-Id: 12345
Content-Type: application/json

{
  "user_id": 12345,
  "user_info": {
    "username": "小明",
    "gender": "male",
    "age": 28
  },
  "tag_ids": [37, 38, 74]
}

请求示例（方式B：api_key 鉴权，第三方应用用）

POST /api/user/profile HTTP/1.1
X-Api-Key: sk-xxxxxxxx
Content-Type: application/json

{
  "user_id": 12345,
  "user_info": {
    "username": "小明",
    "gender": "male",
    "age": 28
  },
  "tag_ids": [37, 38, 74]
}

响应示例

{ "success": true }

由 S2S 等服务调用：AI 与用户聊天对话后，将用户透露的特征信息整理成完整的信息描述句写入用户标签表。

请求参数 (JSON Body)

请求示例

{
  "user_id": 12345,
  "tag": "用户老家在佛山，现居深圳，从事互联网创业",
  "embedding": "[0.12, 0.85, 0.33, -0.21, ...]",
  "weight": 2
}

响应示例（写入成功）

{
  "ok": true,
  "action": "created",
  "message": "标签「用户老家在佛山，现居深圳，从事互联网创业」已写入",
  "tag": "用户老家在佛山，现居深圳，从事互联网创业",
  "id": 244
}

响应示例（相似跳过）

{
  "ok": true,
  "action": "skipped",
  "message": "已有相似标签「用户老家在佛山，现居深圳」（相似度 0.82），未重复写入",
  "tag": "用户老家在佛山，现居深圳"
}

错误响应（embedding 误传文本）

{
  "error": "embedding 必须是向量值（浮点数组序列化字符串，如 [0.1,-0.2,...]），不是标签文本"
}

调用示例（Python）

import requests

resp = requests.post("https://dev.nice-ai.cn/podcast/api/user/ai-tag", json={
    "user_id": 12345,
    "tag": "用户老家在佛山，现居深圳，从事互联网创业",
    "embedding": "",  # 可选，向量值（由向量化服务生成）
    "weight": 2,
})
data = resp.json()
if data["action"] == "created":
    print(f"信息已写入: {data['tag']}")
elif data["action"] == "skipped":
    print(f"已存在相似信息，跳过: {data['tag']}")

返回个人资料编辑页所需的两组标签：兴趣偏好（多选，来自 user_tag_def 表）和 职业/身份（单选，来自 ai_tag_audience 表）。无需认证参数。

响应示例

{
  "interests": [
    {"id": 1198, "name": "科技"},
    {"id": 1199, "name": "旅行"},
    {"id": 1200, "name": "摄影"}
  ],
  "professions": [
    {"id": 2, "name": "学生"},
    {"id": 3, "name": "职场人士"},
    {"id": 4, "name": "自由职业者"}
  ]
}

根据是否传入 podcast_type 返回两种不同的标签树：

• 不传 podcast_type：返回用户资料标签（如"人生状态""兴趣偏好"），从 user_tag_def 表读取，结构为 分类(parent_id=0) → 标签项(parent_id=分类id)，用于用户资料编辑页。
• 传 podcast_type=<code>：返回该播客场景的 AI 标签树（3类定向维度：主播身份/擅长领域/粉丝受众），从 podcast_type_tag 关联表 + ai_tag_identity / ai_tag_expertise / ai_tag_audience 三张枚举表读取，用于 AI 角色创建/播客生成时的标签选择。

Query 参数

响应示例（不传 podcast_type 时，返回用户资料标签）

{
  "categories": [
    {
      "id": 918,
      "name": "人生状态",
      "parent_id": 0,
      "sort_order": 10,
      "tag_type": "mutlabel",
      "children": [
        { "id": 919, "name": "学生时期", "parent_id": 918, "sort_order": 10, "tag_type": "mutlabel" },
        { "id": 920, "name": "职场新人", "parent_id": 918, "sort_order": 20, "tag_type": "mutlabel" }
      ]
    }
  ],
  "total": 2
}

响应示例（传 podcast_type=travel 时，返回 AI 标签树）

{
  "podcast_type": "travel",
  "categories": [
    {
      "id": 1,
      "name": "旅游播客",
      "children": [
        {
          "id": "identity",
          "name": "主播身份",
          "tag_category": "identity",
          "children": [
            { "id": 1, "name": "专业导游" },
            { "id": 2, "name": "年长者游客" }
          ]
        },
        {
          "id": "expertise",
          "name": "擅长领域及创作偏好",
          "tag_category": "expertise",
          "children": [ ... ]
        },
        {
          "id": "audience",
          "name": "粉丝受众/播客收听对象",
          "tag_category": "audience",
          "children": [ ... ]
        }
      ]
    }
  ],
  "total": 1
}

返回所有演播风格列表，用于前端创建播客表单的演播风格选择器。无需认证参数。

Query 参数

响应示例

{
  "play_types": [
    {"id": 1, "name": "播客对聊", "desc": "两个AI角色以对话形式展开节目"},
    {"id": 2, "name": "嘉宾访谈", "desc": "一人主持一人受访的访谈形式"},
    {"id": 3, "name": "电台讲述", "desc": "单人独白式电台讲述"},
    {"id": 4, "name": "相声", "desc": "双人相声表演形式"}
  ]
}

返回所有预置 AI（is_preset=1），含 voice_id（音色ID，数字字符串）与 voice_description（音色描述）。生成播客时必须传 ai_character_ids（音色由 AI 角色自动关联，客户端无需也无法传 voices）。外部应用拿到 AI 列表后，将用户所选 AI 的 id 组成 ai_character_ids 数组传入 /ws 即可生成播客；也可用 voice_id 调用 TTS / S2S 等模型服务复用其声音。

Query 参数

响应字段说明

响应示例

{
  "ai_characters": [
    {
      "id": 6,
      "name": "小雅",
      "avatar_url": "https://dev.nice-ai.cn/static/ai/xiaoya.png",
      "voice_id": "8",
      "voice_name": "如意",
      "voice_description": "温柔知性的女声主播，擅长旅行与生活话题",
      "emoji": "🌸",
      "podcast_type": "travel",
      "identity": ["知性女主播"],
      "personality": [],
      "bio": [],
      "user_title": "",
      "role_config": "30岁知性女性，曾是旅行杂志编辑，擅长用细腻笔触描绘风土人情，说话节奏舒缓，喜欢在叙述中穿插诗意比喻"
    }
  ],
  "total": 1
}

外部应用调用示例（Python）

import requests

API_BASE = "https://dev.nice-ai.cn/podcast"
API_KEY = "sk-your-api-key"

resp = requests.get(
    f"{API_BASE}/api/v1/ai-characters",
    params={"api_key": API_KEY},
    timeout=10,
)
data = resp.json()
for ai in data["ai_characters"]:
    print(ai["id"], ai["name"], ai["voice_id"], ai["voice_description"], ai["emoji"], ai["role_config"])

# 拿到 voice_id 后即可调用 TTS 服务使用该音色合成语音
# role_config 是 AI 的身份描述，可用于在第三方应用中展示 AI 人设或作为 prompt 注入

错误码

使用说明

• 本接口只返回 is_preset=1 的系统 AI，不暴露用户私有 AI。
• 调用频率建议 ≤ 1 次/分钟，AI 列表更新频率低，建议在应用侧做缓存。
• 拿到 voice_id 后，调用 TTS / S2S 等模型服务时把 voice_id 作为 voice 参数传入即可复用该 AI 的声音。
• 系统模块级 Key（sk-opencity-xxx / sk-podcast-xxx）直接放行，无需在 api_keys 表登记。

本服务器所有语音业务（播客 / S2S 对话 / MDN / 生日祝福 ai_birth）共享同一套数据模型，四大系统关联关系如下（已统一优化，各应用不得再按旧逻辑自建关联）：

┌───────────┐    拥有/下单     ┌───────────┐    绑定音色(voice_id)    ┌───────────┐
│ 用户      │ ──────────────→ │ AI 分身   │ ─────────────────────→ │ 音色      │
│ xd_users  │                 │ xd_ais    │                        │ xd_voices │
└───────────┘                 └─────┬─────┘                        └───────────┘
        ▲                           │ star_id（一明星多AI分身）          ▲
        │ 拥有音色(user_id)          ▼                                   │ 预置:user_id=0
┌───────────┐                 ┌───────────┐                            │ 用户:user_id>0
│ 用户音色  │                 │ 明星      │ ─── 明星音色 = 被 star 类  │
│ (user_id) │                 │ xd_stars  │     AI 绑定(ai_type=star)  │
└───────────┘                 └───────────┘                            │
                                                                       │
              合成链：明星 → AI分身(voice_id) → TTS/Seed-VC 合成祝福/生日歌

各实体归属规则（优化后）

调用星来啦（ai_birth）服务的生日祝福歌合成能力：按 AI 分身 id（ai_id）合成该 AI 用自己音色领唱的《生日快乐》歌（Seed-VC 歌声音色转换：源曲 + 明星说话参考音色 → 领唱曲）。幂等：歌曲已就绪直接返回播放地址，不重复合成。

请求

完整地址：https://dev.nice-ai.cn/birth/api/external/birthday_song

POST /birth/api/external/birthday_song
X-Api-Key: sk-xxxxxxxx
Content-Type: application/json

{
  "ai_id": 208
}

请求参数

响应示例

{
  "code": 0,
  "data": {
    "ai_id": 208,
    "ai_name": "朱时茂",
    "voice_id": "214",
    "status": "ready",      // ready | generating | pending | error
    "error": "",
    "song_url": "https://dev.nice-ai.cn/birth/song/208?v=1787556361"
  }
}

status 取值

音频播放地址

GET https://dev.nice-ai.cn/birth/song/{ai_id} — 公开无需鉴权（需嵌入 <audio> 播放器），带 ?v= 版本号（歌曲重生成后 URL 变化自动绕开缓存）。song_url 即此地址的绝对形式。

完整调用示例（Python）

import requests, time

API = "https://dev.nice-ai.cn/birth/api/external/birthday_song"
API_KEY = "sk-your-api-key"

def get_birthday_song(ai_id):
    r = requests.post(API, json={"ai_id": ai_id},
                      headers={"X-Api-Key": API_KEY}, timeout=10)
    j = r.json()
    status = j["data"]["status"]
    while status in ("generating", "pending"):
        time.sleep(5)
        r = requests.get(API + "/status",
                         params={"ai_id": ai_id, "api_key": API_KEY}, timeout=10)
        status = r.json()["data"]["status"]
    if status == "error":
        raise RuntimeError(r.json()["data"]["error"])
    return r.json()["data"]["song_url"]

错误码

返回当前用户自己创建的 AI 角色（仅 user_id=当前用户，不包含预置角色和收藏的AI）。预置角色、收藏列表、AI广场请分别使用独立接口获取。

Query 参数

响应字段说明

响应示例

{
  "ai_characters": [
    {
      "id": 42,
      "user_id": 12345,
      "name": "旅行达人小飞",
      "voice_id": "5",
      "podcast_type": "travel",
      "identity": "资深驴友",
      "personality": "",
      "bio": "",
      "user_title": "旅伴",
      "is_preset": 0,
      "is_published": 1,
      "tag_ids": [10, 11],
      "tag_names": ["专业导游", "历史人文"],
      "voice_description": "温暖男声",
      "emoji": "🎙️",
      "role_config": "25岁户外旅行达人，走过全国30多个省份，擅长实用攻略与风土人情讲解"
    }
  ],
  "total": 1
}