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. 按一下 Add to Claude。Claude 會開啟並預先填入名稱和 URL。按一下 Add。
2. 登入 soundza 並核准。免費帳戶就足夠了。
3. 在對話中，按一下 +，開啟 Connectors，然後開啟 Soundza。

Add to Claude 或使用 https://mcp.soundza.com/mcp/oauth 新增自訂連接器

ChatGPT

1. 開啟 ChatGPT plugins 並新增自訂 MCP 伺服器。將其命名為 Soundza，並保留 OAuth。
2. 貼上下方的 URL，然後登入 soundza。
3. 在新對話中，從工具選單中選擇 Soundza。

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

自訂伺服器取決於您的 ChatGPT 方案；某些方案需要在設定中開啟 Developer 模式。

Claude Code

新增它，然後執行 /mcp，選擇 soundza 並在瀏覽器中登入。

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

比較想用金鑰？設定 SOUNDZA_API_KEY，並使用 Authorization 標頭新增 https://mcp.soundza.com/mcp。金鑰頁面 會顯示此指令，並已填入您的金鑰：

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

Codex、Cursor 和其他代理程式

任何支援 streamable HTTP 的用戶端。如果支援登入，請使用 https://mcp.soundza.com/mcp/oauth，否則使用帶有 Authorization 標頭的 https://mcp.soundza.com/mcp。對於 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_ 開頭。請將金鑰保存在您的伺服器上或 gitignored 的 .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（請參閱 Type and facts）。不區分大小寫。如果 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 秒的廣告。會對能填補該長度的音效（至少該長度的音軌，或無縫循環）進行排名，並為每個結果新增 fit 提示。它不會過濾掉任何內容。
pack	string	音效包的 id 或 slug：僅該音效包中的音效。
loop_seamless	boolean	true：僅限能無縫循環的音效，根據音訊測量（結尾回到開頭而沒有爆音或跳躍）。適用於在場景下重複的遊戲音樂和氛圍底音。
category	string	Universal Category System 頂層類別（「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)

「無人聲的商業背景音樂」是 type=music&vocals=none&q=corporate。使用 type=music 時，除非您設定 parts，否則 full mixes 會排在前面，然後是 loops，最後是 single 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 或標記 @soundza_audio，告訴我們你做了什麼。我們會轉發用 soundza 製作的好作品。

我可以使用 soundza 標誌嗎？

可以，我們希望你將它與「Powered by soundza」連結一起展示，但這是選配。請勿將其用作應用程式的圖示。下載完整標誌（soundza.com/logo-wordmark.png）或單獨的標記（soundza.com/logo.svg）。

限制是什麼？

免費金鑰每分鐘可搜尋 60 次、每小時下載 250 次、每天 350 次，由帳戶上的所有金鑰共享。預覽不計入。每個回應都包含 X-RateLimit-* 標頭。

如何提高限制？

免費限制足以涵蓋製作遊戲、編輯影片或帶音效選取器的小型應用程式。若你要在流量較大的應用程式中加入音效選取器，請在金鑰頁面使用「Request higher limits」，並簡單說明情況，或寄信至 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，傳送一個連結供你核准，然後儲存金鑰。