Soundza

npx add-mcp 'https://mcp.soundza.com/mcp/oauth'

如何连接

从 AI 助手或你自己的代码中使用 soundza。两者都免费，并且获得相同的声音。

在 AI 助手中

在 Claude、ChatGPT、Claude Code 或任何 MCP 应用中，添加 soundza MCP 服务器，并使用免费账户登录一次。具体步骤见下文。

在你自己的代码中

在应用、游戏、脚本和构建工具中，使用免费 API 密钥调用 REST API。获取密钥。

REST

https://api.soundza.com/v1

MCP，登录

https://mcp.soundza.com/mcp/oauth

MCP，API 密钥

https://mcp.soundza.com/mcp

OpenAPI

soundza.com/openapi.json

面向智能体

soundza.com/llms.txt

MCP 服务器有五个工具：search_sounds、get_sound、search_packs、get_pack 和 download_sound，后者返回一个 15 分钟的链接、一条现成的 curl 命令以及该声音的页面。

Claude

1. 点击 添加到 Claude。Claude 会打开并预填名称和 URL。点击“添加”。
2. 登录 soundza 并批准。免费账户就足够了。
3. 在聊天中，点击 +，打开“连接器”，然后开启 Soundza。

添加到 Claude 或使用 https://mcp.soundza.com/mcp/oauth 添加自定义连接器

ChatGPT

1. 打开 ChatGPT 插件 并添加自定义 MCP 服务器。将其命名为 Soundza，并保留 OAuth。
2. 粘贴下面的 URL，然后登录 soundza。
3. 在新聊天中，从工具菜单中选择 Soundza。

URL https://mcp.soundza.com/mcp/oauth

自定义服务器取决于你的 ChatGPT 套餐；有些需要在设置中开启开发者模式。

Claude Code

添加它，然后运行 /mcp，选择 soundza 并在浏览器中登录。

claude mcp add --transport http soundza https://mcp.soundza.com/mcp/oauth

更想用密钥？设置 SOUNDZA_API_KEY 并添加 https://mcp.soundza.com/mcp，附带 Authorization 请求头。密钥页面 会显示已填入你的密钥的命令：

claude mcp add --transport http soundza https://mcp.soundza.com/mcp --header "Authorization: Bearer $SOUNDZA_API_KEY"

Codex、Cursor 及其他智能体

任何支持流式 HTTP 的客户端都可以。如果支持登录，请使用 https://mcp.soundza.com/mcp/oauth；否则使用 https://mcp.soundza.com/mcp 并附带 Authorization 请求头。对于 Cursor，请将其添加到 ~/.cursor/mcp.json；它会从你的环境中读取密钥，因此密钥不会出现在你可能提交的文件中。

{
  "mcpServers": {
    "soundza": {
      "url": "https://mcp.soundza.com/mcp",
      "headers": { "Authorization": "Bearer ${env:SOUNDZA_API_KEY}" }
    }
  }
}

获取 API 密钥

在你自己的代码中使用密钥。将其作为 Authorization: Bearer <key> 发送。密钥以 sz_live_ 开头。请将其保存在你的服务器上或已加入 gitignore 的 .env 中，切勿放在客户端代码中。

自行创建

登录并在密钥页面上创建密钥。密钥只显示一次，并已填入 MCP 命令。

或让智能体替你登录

让你的编码智能体在 soundza.com 上查找声音。它会读取 llms.txt，向你发送一个待批准的链接，并自行保存密钥。

Soundza is free, but every call needs an API key tied to a person's account. Get one with a one-click sign-in:

1. Start the sign-in. Include what the person is building, if you know it from the project: project_kind (one of game, video_tool, own_content, app, agent, music, trying, other) and project, one plain line about it. After approving, the person sees both and can change them; leave out anything you'd have to guess.
   curl -s -X POST https://api.soundza.com/v1/auth/device -H "content-type: application/json" -d '{"client_name":"<your tool> on <this machine>","project_kind":"game","project":"<one line, e.g. A retro sci-fi shooter in Godot>"}'
   It returns device_code, user_code, verification_uri_complete, expires_in (600 seconds) and interval (5 seconds).
2. Tell the human: "Open <verification_uri_complete> and approve code <user_code> (sign in with Google if it asks)." Nothing else is needed from them.
3. Right after telling them, poll every <interval> seconds until they approve. Run the polling loop in the foreground and wait for it; don't end your turn while the sign-in is pending (the code lasts 10 minutes).
   curl -s -X POST https://api.soundza.com/v1/auth/token -H "content-type: application/json" -d '{"device_code":"<device_code>"}'
   While it returns {"error":"authorization_pending"} keep polling; on "slow_down" wait the "interval" it returns. On approval it returns {"access_token":"sz_live_...","token_type":"Bearer",...} once: access_token is the API key. "expired_token" or "access_denied" means stop (start again only if the human asks).
4. Save the key as SOUNDZA_API_KEY in the project's .env and make sure .env is in .gitignore. Never commit the key or put it in a project-scope .mcp.json.
5. Optional: connect this MCP server with the key. The command reads $SOUNDZA_API_KEY from the shell, so load .env first (set -a; . ./.env; set +a). It stores the key in Claude Code's own settings (local scope), not in the project. If soundza is already added without a key, run "claude mcp remove soundza" first.
   claude mcp add --transport http soundza https://mcp.soundza.com/mcp --header "Authorization: Bearer $SOUNDZA_API_KEY"
   The tools load in the next session (or after /mcp). Until then, and in any tool that can't add MCP servers, use the REST API at https://api.soundza.com/v1 with the header "Authorization: Bearer $SOUNDZA_API_KEY". It does everything the MCP tools do.

A person can also create a key at https://soundza.com/developers/keys and set it the same way.

快速开始

搜索，然后下载你使用的内容。先设置 SOUNDZA_API_KEY。

curl -s "https://api.soundza.com/v1/sounds/search?type=sound_effect&q=whoosh&per_page=5" \
  -H "Authorization: Bearer $SOUNDZA_API_KEY"

# download_url redirects to the file: -L follows it, -OJ saves it under its own name
curl -LOJ "https://api.soundza.com/v1/sounds/SOUND_ID/file" \
  -H "Authorization: Bearer $SOUNDZA_API_KEY"

每个结果都有 preview_files、128 kbps 的 MP3 文件，可直接从我们的 CDN 播放，无需密钥，以及一个用于获取全质量文件的 download_url。

端点

每个端点都是 https://api.soundza.com/v1 下的 GET 请求。完整规范位于 /openapi.json。

端点	功能
GET /sounds/search	按词语和筛选条件搜索。返回一页声音和 search_id。
GET /sounds/{id}	按 id 获取单个声音。
GET /sounds/{id}/file	全质量文件，通常为 WAV，已与目录进行电平匹配；?variant=original 可获取未经处理的原始文件。返回 302 跳转，链接有效期为 5 分钟。可选参数 search_id 和 user。
GET /packs	公开音效包，按最佳优先排序。可选参数 q、page 和 per_page。
GET /packs/{id}	获取单个音效包，然后获取其声音的一页。每个声音都会标明所属音效包。
GET /removals?since=	获取自某个 ISO 日期以来被移除的声音，适用于存储文件的用户。

搜索参数

提供 q、至少一个筛选条件，或两者都提供。时长以秒为单位。

参数	类型	描述
q	string	要匹配的词语，例如“door slam”或“lofi drum loop”。拼写错误会被宽容处理。
type	string	声音的类型：music、sound_effect 或 ambience（参见“类型与事实”）。不区分大小写。如果带 q 的搜索在其类型内找不到结果，则会搜索所有类型，并在 relaxed_filters 中说明。
form	string	仅音乐：track、excerpt、loop、one_shot 或 stem。
parts	string	仅音乐：full_mix 或 single_part。未设置时，type=music 会先排列 full mixes，然后是 loops，最后是 single parts。
vocals	string	仅音乐：none、backing 或 lead。
style	string	仅音效：retro 或 cartoon。按音效包设置，因此大多数声音没有此属性；如果带 q 的搜索找不到结果，则会丢弃该属性并在 relaxed_filters 中列出。
min_duration	number	最短时长，以秒为单位。
max_duration	number	最长时长，以秒为单位。
min_bpm	number	最慢速度。只有音乐有速度。
max_bpm	number	最快速度。
key	string	音乐调性，例如“C”、“F# minor”或“Bbm”。仅匹配声音显示的调性：由来源或人工标注，或以高置信度自动检测。
chord	string	和弦单音所演奏的和弦，例如“Am”、“C#m7”或“Fmaj7”。
note	string	带音高的单音所演奏的音符：“D3”表示该八度（C3 为中央 C），或“D”表示任意八度。
mood	list	逗号分隔的情绪词；匹配任意一个的声音都会返回，匹配越多排名越高。可选值：airy、heavy、metallic、bright、dark、punchy、soft、warm、glitchy、organic、cinematic、cartoony、retro。
good_for	list	逗号分隔的声音适用场景。仅影响排名：匹配的声音排名更高，不会过滤掉任何内容。可选值：transition、reveal、build_up、impact_on_beat、title_or_logo、notification、ui_click、menu、game_pickup、game_hit、game_power_up、footsteps、background_bed、intro、outro。
fit_seconds	number	声音需要填充的时长，例如 20 表示 20 秒的广告。会优先排列能够填充该时长的声音（至少同样长的音轨，或无缝循环），并为每个结果添加适配提示。不会过滤掉任何内容。
pack	string	音效包的 id 或 slug：仅返回该音效包的声音。
loop_seamless	boolean	true：仅返回可无缝循环的声音，根据音频测量（结尾无缝回到开头，无爆音或跳跃）。适用于游戏音乐和场景下重复播放的氛围底垫。
category	string	通用分类系统（UCS）顶级类别（“CROWDS”）或 CatID（“CRWDCheer”）。适用于音效和氛围声。
page	integer	页码，从 1 开始。
per_page	integer	每页结果数：默认 15，最多 50。每次查询最多返回 500 条结果。

响应

一页结果，附带下一页的链接。bpm 和 key 描述音乐；当声音没有公开创作者时，creator 为 null。

文件已进行电平匹配，因此声音可以放在一起而无需逐个调整：每个声音一个增益，无压缩，峰值不超过 −1 dBTP。氛围声目标为 −20 LUFS，音乐、底垫和长循环目标为 −16，其他所有声音以其最响的 400 毫秒为目标 −13。lufs、true_peak_db 和 loudness 描述原始文件；gain_db 是默认文件在其基础上添加的内容。在文件路由中添加 ?variant=original 可获取上传时的原始文件。

{
  "page": 1,
  "per_page": 5,
  "total_results": 38,
  "next_page": "https://api.soundza.com/v1/sounds/search?q=whoosh&type=SOUND_EFFECT&per_page=5&page=2",
  "search_id": "x7k2m9q4r1t8v3w6y0z5a2b4",
  "sounds": [
    {
      "id": "cm9w2k4e30001",
      "url": "https://soundza.com/sounds/fast-air-whoosh",
      "title": "Fast Air Whoosh",
      "description": "A quick, bright air whoosh that sweeps left to right.",
      "type": "sound_effect",
      "form": null,
      "parts": null,
      "vocals": null,
      "style": null,
      "good_for": ["transition"],
      "duration": 0.84,
      "bpm": null,
      "key": null,
      "chord": null,
      "note": null,
      "mood": ["airy", "bright"],
      "tags": ["whoosh", "swipe", "air", "airy", "bright"],
      "sync_ms": 310,
      "lufs": -19.4,
      "true_peak_db": -6.1,
      "loudness": { "value": -18.2, "basis": "momentary_max" },
      "gain_db": 5.1,
      "loop_seamless": null,
      "file_type": "audio/wav",
      "file_extension": "wav",
      "sample_rate": 48000,
      "bit_depth": 24,
      "channels": 2,
      "size_bytes": 322604,
      "category": { "id": "WHSH", "label": "Swooshes › Whoosh" },
      "pack": {
        "id": "cm8p1x7a20004",
        "name": "Air and Motion",
        "slug": "air-and-motion",
        "sound_count": 42,
        "url": "https://soundza.com/packs/air-and-motion"
      },
      "creator": null,
      "preview_files": [
        { "type": "audio/mpeg", "bitrate": 128, "link": "https://media.soundza.com/public/previews/4fJ9aQx2LmP0sT7vKc1Rb8Ze.mp3" }
      ],
      "download_url": "https://api.soundza.com/v1/sounds/cm9w2k4e30001/file",
      "license": { "name": "Soundza Standard License", "url": "https://soundza.com/license" },
      "attribution": "\"Fast Air Whoosh\" on Soundza (https://soundza.com/sounds/fast-air-whoosh)"
    }
  ]
}

类型与事实

type 说明声音的类型。先按类型筛选，再按你已知的事实筛选，然后将其余内容放入 q。

类型	包含内容	事实
music	音轨、片段、循环、单音、分轨、短促音、片头音和声乐切片，包括游戏音乐。	form（track、excerpt、loop、one_shot、stem）、parts（full_mix、single_part）、vocals（none、backing、lead）、bpm、key、note、chord
sound_effect	嗖嗖声、冲击声、拟音、UI 和游戏声音、作为效果的人声。	category（UCS）、style（retro、cartoon；按音效包设置）
ambience	场所、房间氛围和噪声底垫。	category（UCS）

“无 vocals 的企业背景音乐”即 type=music&vocals=none&q=corporate。使用 type=music 时，full mixes 优先，然后是 loops，最后是 single parts，除非你设置了 parts。good_for 会将适合某场景的声音（transition、ui_click、background_bed 等）在结果中上移，而不会过滤掉任何内容。带 q 的搜索如果在其类型内找不到结果，则会搜索所有类型，并在 relaxed_filters 中列出 type。

限制

免费密钥可获得：

• 每分钟 60 次搜索
• 每小时 250 次下载
• 每天 350 次下载

每个响应都包含以下响应头。429 还包含 Retry-After，以秒为单位：

• X-RateLimit-Limit
• X-RateLimit-Remaining
• X-RateLimit-Reset
• X-RateLimit-Policy

同一账户上的所有密钥共享这些限制。使用声音的 preview_files 进行试听，这些试听免费且不计入限制，并且只下载你实际使用的声音。

只有不同的声音才计入下载次数，因此在 24 小时内重复获取同一声音是免费的。总文件获取次数上限为下载限制的两倍。每个文件保存一次，并通过声音的 id 重复使用。查询单个声音或音效包有单独的限制，为搜索限制的五倍。

想在应用中加入声音选择器？没问题：免费密钥足以覆盖每天少量用户的小型应用。一旦流量增大，请从密钥页面申请更高的限制并简要说明情况，或写信至 admin@soundza.com。我们会通过电子邮件回复。

申请更高限制

署名

一切完全免费。我们唯一的要求是，在项目中合适的位置注明 soundza.com（以及适用的原始声音创作者）。理想情况下，请在网站/博客/itch 页面某处包含指向 soundza.com 的链接（例如“感谢 soundza.com 提供的免费声音”）。如果你没有网站，我们也欢迎在社交媒体或 YouTube 视频描述中提及我们。帮助我们传播！

以下是一些示例。我们对署名方式很灵活，但请求你以某种自然的方式完成。

你制作的内容	署名方式
带声音选择器的应用或工具	在选择器中加入 Powered by soundza，并在网站页脚、关于页面、博客或其他合适位置添加指向 soundza.com 的链接。
游戏，即使是小型游戏	在你分享的任何地方（Reddit 或 Discord 帖子、X、开发日志或网站、itch.io 或 Steam），简要感谢 soundza.com，并在可能的地方附上链接。
视频	在 YouTube 描述中加入 Sound effects: soundza.com。在 TikTok 或 Instagram 上，如果可以，请标记 @soundza_audio。
机器人、智能体或开源工具	在 README、帮助文本或列表页面中添加一行。
仅供自己使用的内容	无需署名。

想使用我们的标志？欢迎将其与你的链接一起展示：完整标志（PNG）或独立标记（SVG）。只是不要将其用作你的应用图标。

用 soundza 制作了什么？我们很乐意看到。发送邮件至 admin@soundza.com 或标记 @soundza_audio。我们会转发精彩的项目。

错误

错误以 JSON 格式返回：{"error": {"code", "message", "details"?}}。

状态	代码	含义
400	invalid_request	参数有误。details 会列出每个错误参数。
401	missing_key	缺少 Authorization: Bearer 请求头。
401	invalid_key	密钥不存在。
401	revoked_key	密钥已被撤销。
404	not_found	没有公开声音使用该 id。
429	rate_limited	已达到限制。请等待 Retry-After 秒。
500	server_error	我们这边出了问题。请稍后重试。

许可

每个声音均依据 Soundza 标准许可 提供，该许可从其 license 字段链接而来：可用于个人和商业项目的免版税用途，声音本身无需署名（关于我们希望您如何回馈，请参阅致谢说明）。我们会仔细审核声音，但按“原样”提供，不保证声音不涉及第三方权利主张。完整条款见许可协议。

指南

• 当团队之外的人看到您的作品时，请以合适的方式链接回 soundza.com：在您的网站上的声音选择器旁标注“Powered by soundza”并附上链接，在分享游戏的地方致谢，或在视频描述中加一行说明。参见 soundza.com/developers#credit。
• 当声音添加到项目时，请求其 download_url，将文件保存一次，并通过声音的 id 重复使用。
• 预览仅供试听。成品作品请使用下载的文件。
• 请勿复制 Soundza 的核心功能，或构建竞争性的声音库或 API。
• 免费密钥最多可存储 500 个已下载的声音。删除 GET /v1/removals 中列出的任何声音，并至少每月检查一次。
• 遵守速率限制，如需更多请提出申请。我们可能随时以任何理由暂停或终止任何人的 API 访问权限。

API 的使用受服务条款和许可协议约束。

Soundza 选择器

为您的产品提供一个声音选择器，包含三个文件：两个保持密钥私密的服务器路由，以及一个包含标签、预览和致谢链接的组件。可按您的应用风格进行样式定制。

// app/api/sounds/route.ts: search, with your key kept on the server
export async function GET(req: Request) {
  const params = new URL(req.url).searchParams;
  const res = await fetch(\`https://api.soundza.com/v1/sounds/search?${params}\`, {
    headers: { Authorization: \`Bearer ${process.env.SOUNDZA_API_KEY}\` },
  });
  return new Response(res.body, { status: res.status, headers: { "Content-Type": "application/json" } });
}

// app/api/sounds/[id]/file/route.ts: call it from your server when a user adds a sound
export async function GET(req: Request, { params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  const query = new URL(req.url).searchParams; // search_id, and your own user id as user
  const res = await fetch(\`https://api.soundza.com/v1/sounds/${encodeURIComponent(id)}/file?${query}\`, {
    headers: { Authorization: \`Bearer ${process.env.SOUNDZA_API_KEY}\` },
    redirect: "manual",
  });
  const location = res.headers.get("location");
  return location ? Response.redirect(location, 302) : new Response(res.body, { status: res.status });
}

当用户添加声音时，从您的服务器获取文件路由，并将文件保存到您自己的存储中。这会计入下载次数。该路由会重定向到一个有效期为 5 分钟且无法从其他网站的浏览器中读取的签名链接，因此请勿在客户端获取该链接或保留该链接。如果您需要按用户统计报告，请将您自己的用户 ID 作为 user 传递。

常见问题

API 免费吗？

是的。API 和密钥均免费。作为回报，我们希望您在合适的地方链接回 soundza。

我需要为 soundza 署名吗？

当团队之外的人看到您的作品时，我们希望您以合适的形式致谢：在您的网站、商店页面或视频描述中加链接。在构建或测试期间，或仅用于个人用途时，无需署名。

什么算作致谢？

在人们可以看到的地方链接到 soundza.com。对于应用，在声音选择器旁标注 Powered by soundza，并在网站页脚、关于页面、博客或其他合适位置加链接。对于游戏，在分享处致谢：Reddit 或 Discord 帖子、开发日志或网站、itch.io 或 Steam 页面。对于视频，在描述中添加 Sound effects: soundza.com。在 X、Discord 或 YouTube 上公开致谢也很棒。

你们会分享我的作品吗？

我们很乐意了解您构建的内容。请发送邮件至 admin@soundza.com，或在 X 上标记 @soundza_audio，告诉我们您做了什么。我们会转发使用 soundza 制作的精彩项目。

我可以使用 soundza 标志吗？

可以，我们很乐意您将其与“Powered by soundza”链接一起展示，但这不是必须的。请不要将其用作您应用的图标。下载完整标志（soundza.com/logo-wordmark.png）或单独的标志（soundza.com/logo.svg）。

限制是什么？

免费密钥每分钟可进行 60 次搜索，每小时 250 次下载，每天 350 次，由您账户下的所有密钥共享。预览不计入限制。每个响应都包含 X-RateLimit-* 标头。

如何获得更高限制？

免费限制足以支持构建游戏、编辑视频或带有声音选择器的小型应用。如果您要在有实际流量的应用中集成声音选择器，请在密钥页面使用“请求更高限制”并简要说明情况，或发送邮件至 admin@soundza.com，附上您的密钥前缀和正在构建的内容。我们会通过邮件回复。

我可以在商业项目中使用这些声音吗？

可以。每个声音均依据 Soundza 标准许可，可用于个人和商业项目的免版税用途，在您制作的游戏或应用中包含声音也是允许的。

我可以存储文件吗？

可以。将每个文件保存一次，并通过声音的 id 重复使用。免费密钥最多可存储 500 个已下载的声音。请勿保留 download_url 重定向到的签名链接；其有效期为 5 分钟。

如果声音被移除怎么办？

请定期（至少每月）调用 GET /v1/removals?since=<date>，并删除其列出的任何声音。

我可以使用这些声音训练 AI 吗？

不可以。这些声音不得用于训练、微调或构建 AI 或机器学习模型。

我可以基于 API 构建声音库吗？

不可以。请勿将声音作为独立文件或采样包重新分发，或构建竞争性的声音库或 API。

REST 还是 MCP？

两者使用相同的密钥、限制和目录。在代码中使用 REST，并使用 MCP（mcp.soundza.com/mcp），以便 Claude Code 或 Cursor 等代理为您搜索和下载。

我的编码代理可以自行获取密钥吗？

可以。请让它在 soundza.com 上查找声音。它会读取 llms.txt，向您发送一个链接供您批准，然后保存密钥。