使用文档

PineSound 提供多种集成方式，从标准 REST API 到 MCP 协议、CLI Skill，满足不同场景的接入需求。选择适合您的集成模式开始使用 PineSound 的 AI 音频能力。

OpenAI 兼容

对话/语音/量化对齐 OpenAI，官方 SDK 改 base_url 即可直连

标准 API

RESTful HTTP 接口，适合任意语言和平台

MCP

Model Context Protocol，适合 AI 智能体与 IDE 集成

Skill

CLI 命令行技能，适合脚本与自动化工作流

SDK 安装

PineSound 提供 Node.js、Python 和 Rust 三种语言的 SDK，选择您的开发语言查看安装方式。

Shell


# 使用npm安装
npm install @pinesound/sdk

# 使用pnpm安装
pnpm add @pinesound/sdk

# 使用yarn安装
yarn add @pinesound/sdk

认证

所有 API 请求均需通过 Bearer Token 进行认证。在请求头中携带您的 API Key：

HTTP

curl https://api.pinesound.cn/v1/audio/recognize \ -H "Authorization: Bearer YOUR_API_KEY"

请妥善保管您的 API Key，不要在客户端代码或公开仓库中暴露。

OpenAI

OpenAI 兼容

对话 / 语音生成 / 文本量化严格对齐 OpenAI 接口，用官方 openai SDK 改 base_url = https://api.pinesound.cn/v1 即可直连。模型：PineCC(对话) / PineSP(语音) / PineET(文本量化)。

POST/v1/chat/completions

AI 对话（PineCC），OpenAI Chat Completions 兼容，支持流式。

curl https://api.pinesound.cn/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "PineCC",
    "messages": [{"role": "user", "content": "帮我找雨声素材"}]
  }'

# Response
{
  "choices": [{"message": {"role": "assistant", "content": "..."}}],
  "usage": {"prompt_tokens": 8, "completion_tokens": 30, "total_tokens": 38}
}

POST/v1/audio/speech

语音生成/配音（PineSP），OpenAI Audio Speech 兼容，默认主播。

curl https://api.pinesound.cn/v1/audio/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "PineSP",
    "input": "欢迎使用 PineSound",
    "voice": "anchor_001"
  }' --output out.mp3

POST/v1/embeddings

文本量化（PineET），OpenAI Embeddings 兼容。

curl https://api.pinesound.cn/v1/embeddings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "PineET", "input": "激昂的交响乐"}'

GET/v1/models

模型列表：PineCC / PineRA / PineEA / PineMS / PineMM / PineET / PineSP。

curl https://api.pinesound.cn/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"
# → PineCC / PineRA / PineEA / PineMS / PineMM / PineET / PineSP

REST

标准 API

自定义能力（搜索/识别/配乐/音效/主播音色/项目/余额）。Base URL：https://api.pinesound.cn/v1。所有请求需携带 Bearer Token。选择下方语言标签切换代码示例。

POST/v1/audio/search

音频搜索（关键词/智能语义/相似），返回匹配素材列表。

curl https://api.pinesound.cn/v1/audio/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "激昂的交响乐", "search_type": "smart", "limit": 10}'

POST/v1/audio/recognize

识别音频内容，返回声音类别、乐器、人声等标签及置信度。

curl https://api.pinesound.cn/v1/audio/recognize \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"audio_url": "https://example.com/a.wav"}'

POST/v1/audio/embeddings

音频 → 512 维向量嵌入（PineEA），用于相似度与指纹。

curl https://api.pinesound.cn/v1/audio/embeddings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "https://.../a.wav", "model": "PineEA"}'

POST/v1/audio/music/generate

根据文本描述生成背景配乐（异步任务，轮询 job_get）。

curl https://api.pinesound.cn/v1/audio/music/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "温暖的钢琴曲", "duration": 60}'
# → {"id": "job_xxx", "status": "queued"}
# 轮询 GET /v1/audio/generate/job_xxx

POST/v1/audio/sfx/generate

根据文本描述生成音效（异步任务）。

curl https://api.pinesound.cn/v1/audio/sfx/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "大雨倾盆的雨声", "duration": 10}'
# → {"id": "job_xxx", "status": "queued"}

GET/v1/voices

开放主播列表，支持音色克隆/设计。

curl https://api.pinesound.cn/v1/voices \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/v1/projects/{id}/prepare

获取/整备项目。

curl -X POST https://api.pinesound.cn/v1/projects/prj_001/prepare \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/v1/balance

查询余额与用量。

curl https://api.pinesound.cn/v1/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

余额

余额与计费

所有 API 调用按模型定价从账户余额扣费。余额不足返回 402 insufficient_balance，请前往平台 → 充值用微信扫码充值。

GET/v1/balance

余额查询（CNY，1:1 充值）。

curl https://api.pinesound.cn/v1/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

MCP

本地 MCP

需安装桌面应用

前提条件：需安装 PineSound 桌面应用 v1.0+。本地 MCP 通过 http://localhost:18001/mcp 连接，由桌面应用内置的 MCP Server 提供服务（Streamable HTTP），无需单独认证。

启动 MCP 模式

在 PineSound 桌面应用中，进入「设置 → MCP 服务」开启本地 MCP Server。启动后默认监听 localhost:18001。

安装

在支持 MCP 的客户端（如 Claude Code、VS Code 等）中添加 PineSound MCP 配置：

JSON.claude/mcp.json 或 VS Code settings.json

{ "mcpServers": { "pinesound": { "type": "streamable-http", "url": "http://localhost:18001/mcp" } } }

TOOLaudio_search_local

在本地素材库按关键词检索（离线）

// Tool: audio_search
{ "name": "audio_search", "arguments": { "query": "激昂的交响乐", "search_type": "smart", "limit": 10 } }

TOOLaudio_similarity_search

按参考音频在本地库找相似（离线）

// Tool: audio_similarity_search
{ "name": "audio_similarity_search", "arguments": { "top_k": 10 } }

TOOLaudio_import

将音频文件导入本地素材库（离线）

// Tool: audio_import
{ "name": "audio_import", "arguments": { "file_path": "/Users/me/music/bgm.wav", "tags": "背景音乐,钢琴" } }

TOOLaudio_list

列出本地素材库（离线）

// Tool: audio_list
{ "name": "audio_list", "arguments": { "limit": 50 } }

TOOLaudio_info

获取本地音频基本信息（离线）

// Tool: audio_info
{ "name": "audio_info", "arguments": { "file_path": "/Users/me/music/bgm.wav" } }

TOOLmodel_status

查询本地向量模型状态（离线）

// Tool: model_status
{ "name": "model_status", "arguments": {} }

MCP

云 MCP

无需安装桌面应用

云 MCP 通过 PineSound 云端服务器提供 MCP 服务，无需安装桌面应用。连接地址：https://api.pinesound.cn/mcp。需要 API Key 进行身份验证。

安装

在 MCP 客户端配置中指定 PineSound 云端 MCP 地址：

JSON.claude/mcp.json

{ "mcpServers": { "pinesound": { "type": "streamable-http", "url": "https://api.pinesound.cn/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } }

或用 Claude Code 命令配置

在 Claude Code 中直接用一行命令添加 PineSound 云端 MCP：

Shell

claude mcp add --scope user --transport http pinesound "https://api.pinesound.cn/mcp" -H "Authorization: Bearer YOUR_API_KEY"

把 YOUR_API_KEY 换成你的 API Key。添加后用 claude mcp list 验证，即可在 Claude Code 中直接调用 audio_search / music_generate 等 PineSound 工具。

身份验证

云 MCP 需要有效的 API Key。通过内测申请获取 API Key 后，在 MCP 配置的 headers 中设置 Authorization 头。

TOOLaudio_search

搜索云端公共素材库

// Tool: audio_search
{ "name": "audio_search", "arguments": { "query": "激昂的交响乐", "search_type": "smart", "limit": 10 } }

TOOLaudio_recognize

识别音频内容（云端处理）

// Tool: audio_recognize
{ "name": "audio_recognize", "arguments": { "audio_url": "https://.../a.wav" } }

TOOLvoice_list

开放主播/音色列表与克隆

// Tool: voice_list
{ "name": "voice_list", "arguments": {} }

TOOLmusic_generate

根据描述生成配乐（异步）

// Tool: music_generate
{ "name": "music_generate", "arguments": { "prompt": "温暖的钢琴曲", "duration": 60 } }

TOOLsfx_generate

根据描述生成音效（异步）

// Tool: sfx_generate
{ "name": "sfx_generate", "arguments": { "prompt": "大雨倾盆的雨声", "duration": 10 } }

TOOLchat

与 PineSound AI 助手对话

// Tool: chat
{ "name": "chat", "arguments": { "prompt": "帮我找雨声素材" } }

TOOLbalance

查询余额与用量

// Tool: balance
{ "name": "balance", "arguments": {} }

Skill

本地 Skill

需安装桌面应用

前提条件：需安装 PineSound 桌面应用 v1.0+。本地 Skill 通过 CLI 模式调用，由桌面应用提供本地音频处理能力，处理速度快且支持离线使用。

启动 CLI

安装 PineSound 桌面应用时，pinesound CLI 会自动装到 PATH。验证：

Shell

# 验证 CLI 是否可用 pinesound --help

安装技能

在支持 Skill 的 AI 客户端（如 Claude Code）中，通过 /skill 命令安装 PineSound 本地 Skill。桌面端安装时已自动把 pinesound CLI 装到 PATH。

Shell

# 安装本地音频处理技能 pinesound --help # 校验 CLI pinesound model-status

CLIpinesound search "背景音乐" --top 10

在本地素材库按关键词检索（离线）。

CLIpinesound import --file ./bgm.wav --tags 背景音乐,钢琴

将音频文件导入本地素材库并添加标签（离线）。

CLIpinesound list --top 50

列出本地素材库（离线）。

CLIpinesound info --file /path/to/a.wav

获取本地音频基本信息（离线）。

CLIpinesound model-status

查询本地向量模型状态（离线）。

Skill

无需安装桌面应用

云端 Skill 无需安装桌面应用，直接通过 API Key 使用 PineSound 全部音频能力。适合轻量集成和快速原型开发。

安装技能

通过 pip 安装 PineSound Skill 包，并在客户端注册：

Shell

# 安装 PineSound Skill 包 pip install pinesound-skill # 在 AI 客户端中注册 Skill pinesound-skill register --api-key YOUR_API_KEY # 验证安装 pinesound-skill balance

安装完成后，即可在支持 Skill 的 AI 客户端中使用 PineSound 的全部音频能力，包括搜索、识别、量化、对话、配音、配乐/音效生成、主播音色和项目管理。处理在云端完成。

错误码

HTTP 状态码	错误码	说明
400	`invalid_request_error`	请求参数语义错误（互斥/缺失）
401	`invalid_api_key`	API Key 无效或已过期
403	`permission_error`	无权限（scope 不匹配）
404	`not_found_error`	资源/任务不存在
402	`insufficient_balance`	余额不足，请先充值（Web 端微信扫码充值）
426	`api_version_error`	SDK 版本与服务端不兼容
429	`rate_limit_error`	请求频率超过限制
500	`server_error`	服务器内部错误
503	`service_unavailable`	服务暂时不可用

速率限制

套餐	请求数/分钟	请求数/天	并发数
基础版（免费）	30	1,000	1
专业版	300	50,000	5
团队版	1,000	200,000	20
企业版	自定义	自定义	自定义