{ "openapi": "3.1.0", "info": { "title": "SFXMint Sound Effects API", "version": "1.0.0", "summary": "Free CC0 sound effects for apps and games, no API key.", "description": "JSON API for 9,400+ AI-generated CC0 sound effects: search by description, look up a sound by the event it is for, fetch a set for a whole app or game, and download WAV or MP3 files. The library needs no key or signup. Generating a sound the library lacks needs an API key from https://sfxmint.com/dashboard/keys. The same tools are an MCP server at https://sfxmint.com/mcp.", "termsOfService": "https://sfxmint.com/terms", "contact": { "name": "SFXMint", "url": "https://sfxmint.com/contact", "email": "hello@sfxmint.com" }, "license": { "name": "CC0-1.0 (the sounds)", "identifier": "CC0-1.0" }, "x-logo": { "url": "https://sfxmint.com/icon.png" } }, "externalDocs": { "description": "API documentation", "url": "https://sfxmint.com/api/docs" }, "servers": [ { "url": "https://sfxmint.com" } ], "tags": [ { "name": "library", "description": "Keyless library endpoints." }, { "name": "generation", "description": "Generating with an API key." } ], "paths": { "/api/v1/search": { "get": { "tags": [ "library" ], "operationId": "searchSounds", "summary": "Search sounds by description", "description": "Keyword search over sound titles and tags, backed by a semantic layer. Constraints are applied before the limit. The default response is an array: sounds showing every word first (fit: full), then the closest ones that meet every condition but not every word (fit: closest, with missing_terms). response=structured returns parsed constraints, per-candidate checks, closest sounds, library_fit and diagnostics.", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "What the sound is, in plain words.", "schema": { "type": "string" }, "example": "coin pickup" }, { "name": "category", "in": "query", "required": false, "description": "Library category slug.", "schema": { "type": "string" }, "example": "ui" }, { "name": "limit", "in": "query", "required": false, "description": "Number of results.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "response", "in": "query", "required": false, "description": "structured for the detailed response object.", "schema": { "type": "string", "enum": [ "legacy", "structured" ], "default": "legacy" } }, { "name": "max_duration_ms", "in": "query", "required": false, "description": "Longest the sound itself may be, in milliseconds (a longer file with near-silence after the sound qualifies).", "schema": { "type": "number", "exclusiveMinimum": 0 }, "example": 1000 }, { "name": "loop", "in": "query", "required": false, "description": "Only sounds made to loop (true) or only one-shots (false).", "schema": { "type": "boolean" } }, { "name": "format", "in": "query", "required": false, "description": "Only sounds that have this file format.", "schema": { "type": "string", "enum": [ "wav", "mp3", "ogg" ] } } ], "responses": { "200": { "description": "Matching sounds (an array), or the structured response.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" } }, { "$ref": "#/components/schemas/StructuredSearch" } ] } } } }, "400": { "description": "Invalid parameter values (invalid_parameters).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/sounds/{slug}": { "get": { "tags": [ "library" ], "operationId": "getSound", "summary": "Get one sound", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "The sound's id.", "schema": { "type": "string" }, "example": "ui-click-30" } ], "responses": { "200": { "description": "The sound's metadata and file URLs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoundDetail" } } } }, "404": { "description": "No such sound (not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/roles": { "get": { "tags": [ "library" ], "operationId": "listRoles", "summary": "List sound roles", "description": "Every role: what a sound is for in an app, game or video (button-click, purchase-success, coin-pickup).", "responses": { "200": { "description": "All roles.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Role" } } } } } } } }, "/api/v1/roles/{role}": { "get": { "tags": [ "library" ], "operationId": "getRoleSound", "summary": "Get the default sound for a role", "description": "One deterministic default sound for the role, with alternates. The role may be its id or an alias.", "parameters": [ { "name": "role", "in": "path", "required": true, "description": "Role id or alias.", "schema": { "type": "string" }, "example": "button-click" }, { "name": "style", "in": "query", "required": false, "description": "balanced is the most typical variant; the others re-rank by measured acoustics.", "schema": { "type": "string", "enum": [ "balanced", "crisp", "soft", "spacious" ], "default": "balanced" } }, { "name": "max_duration_ms", "in": "query", "required": false, "description": "Longest the sound itself may be, in milliseconds (a longer file with near-silence after the sound qualifies).", "schema": { "type": "number", "exclusiveMinimum": 0 }, "example": 1000 }, { "name": "loop", "in": "query", "required": false, "description": "Only sounds made to loop (true) or only one-shots (false).", "schema": { "type": "boolean" } }, { "name": "format", "in": "query", "required": false, "description": "Only sounds that have this file format.", "schema": { "type": "string", "enum": [ "wav", "mp3", "ogg" ] } } ], "responses": { "200": { "description": "The role's default sound.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleSound" } } } }, "400": { "description": "Invalid parameter values (invalid_parameters).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown role (not_found, with roles_url).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/sets": { "get": { "tags": [ "library" ], "operationId": "listSets", "summary": "List sound sets", "description": "Sound sets grouped by event and style: style kits, scenario kits and one-shot kits.", "responses": { "200": { "description": "All sets.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SetSummary" } } } } } } } }, "/api/v1/sets/{id}": { "get": { "tags": [ "library" ], "operationId": "getSoundSet", "summary": "Get a sound set", "description": "One sound per role with alternates, a role → URL map (urls, MP3) and download_urls in the chosen format; missing_roles lists events the set cannot fill.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Set id.", "schema": { "type": "string", "enum": [ "ui-crisp", "ui-soft", "ui-spacious", "retro-game", "chat-app", "saas-app", "checkout", "learning", "puzzle-game", "platformer", "horror-game", "video-editing", "smart-device", "wellness", "ai-coding-tool", "acoustic-drum-kit", "animal-calls", "dungeon-traps" ] }, "example": "platformer" }, { "name": "format", "in": "query", "required": false, "description": "File format of download_urls.", "schema": { "type": "string", "enum": [ "wav", "mp3", "ogg" ], "default": "mp3" } } ], "responses": { "200": { "description": "The set.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoundSet" } } } }, "404": { "description": "No such set (not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/dl/{file}": { "get": { "tags": [ "library" ], "operationId": "downloadSound", "summary": "Download a sound file", "description": "Permanent, immutable, CORS-enabled audio URL, free to hotlink. Playing a file in a browser is never counted; downloads by scripts, the API and MCP are limited to 20 different sounds a day per network without an API key, 50 with a free account's key. Past the limit the answer is 429 download_limit with Retry-After. Never append query parameters.", "parameters": [ { "name": "file", "in": "path", "required": true, "description": "The sound's id and format: .wav, .mp3 or .ogg (OGG for older sounds only).", "schema": { "type": "string" }, "example": "ui-click-30.mp3" } ], "responses": { "200": { "description": "The audio file.", "content": { "audio/mpeg": { "schema": { "type": "string", "format": "binary" } }, "audio/wav": { "schema": { "type": "string", "format": "binary" } }, "audio/ogg": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "No such file." }, "429": { "description": "The day's download allowance is used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DownloadLimit" } } } } } } }, "/api/v1/orders": { "post": { "tags": [ "generation" ], "operationId": "generateSound", "summary": "Generate a sound the library lacks", "description": "Uses the account's free tries, then its credits (one per generation, given back when nothing is made) or its plan. Each take is a CC0 WAV. An agent never pays: on 402 pass the message and buy_url to the user.", "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderRequest" } } } }, "responses": { "201": { "description": "The generation has started; poll GET /api/v1/orders/{id}.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCreated" } } } }, "400": { "description": "Invalid request (invalid_body, invalid_duration, invalid_variations, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key (sign_in_required, with website_url) or a wrong key (invalid_api_key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "No credits or plan (payment_required, with message, buy_url, website_url and plans).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Today's plan generations are used (plan_day_used) or too many active orders.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/orders/{id}": { "get": { "tags": [ "generation" ], "operationId": "getGeneration", "summary": "Get a generation and its takes", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order id.", "schema": { "type": "string" }, "example": "ord_0123456789abcdef01234567" } ], "responses": { "200": { "description": "The order and its files.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderDetail" } } } }, "401": { "description": "No key or a wrong key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such order for this key (not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "An SFXMint API key (sfx_live_…). X-API-Key is accepted too." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } }, "DownloadLimit": { "type": "object", "properties": { "error": { "const": "download_limit" }, "message": { "type": "string" }, "limit": { "type": "integer" }, "used": { "type": "integer" }, "tier": { "type": "string" }, "upgrade_url": { "type": "string", "format": "uri" } } }, "Acoustics": { "type": [ "object", "null" ], "description": "Measured from the WAV; null when not measured. Numbers, not a judgement of how a sound suits its use: listen.", "properties": { "onset_ms": { "type": "number", "description": "Silence before the sound starts." }, "peak_ms": { "type": "number", "description": "The loudest sample, from the start of the file. Align this with an event." }, "audible_ms": { "type": "number", "description": "First to last moment within 40 dB of the peak." }, "attack_ms": { "type": [ "number", "null" ], "description": "Rise from the sound's start to its loudest window; does not count silence before it." }, "tail_ms": { "type": [ "number", "null" ], "description": "Fall from the loudest window to -40 dB." }, "centroid_hz": { "type": [ "number", "null" ], "description": "Spectral brightness." }, "peak_dbfs": { "type": "number" }, "rms_dbfs": { "type": "number", "description": "Average level across the audible span." }, "character": { "type": "array", "items": { "type": "string" } } } }, "SearchResult": { "type": "object", "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "category": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "duration_ms": { "type": "integer", "description": "Length of the file." }, "loopable": { "type": "boolean", "description": "Legacy flag; use loop_status=prepared for a checked loop." }, "loop_status": { "type": "string" }, "license": { "type": "string", "example": "CC0-1.0" }, "acoustics": { "$ref": "#/components/schemas/Acoustics" }, "format_metadata": { "type": "object", "description": "Per format (wav, mp3, ogg): sha256, bytes, duration_ms, sample_rate, channels, codec and decode checks." }, "mp3_url": { "type": "string", "format": "uri" }, "wav_url": { "type": "string", "format": "uri" }, "ogg_url": { "type": "string", "format": "uri", "description": "Sounds published before 2026-10-14." }, "page_url": { "type": "string", "format": "uri" }, "fit": { "type": "string", "enum": [ "full", "closest" ] }, "missing_terms": { "type": "array", "items": { "type": "string" } }, "audible_ms": { "type": "integer", "description": "Length of the sound itself." }, "score": { "type": "number", "description": "Ranking signal, not a probability." }, "match": { "type": "string" } } }, "StructuredSearch": { "type": "object", "properties": { "request_id": { "type": "string" }, "query": { "type": "object" }, "constraints": { "type": "object" }, "candidates": { "type": "array", "items": { "type": "object" } }, "closest": { "type": "array", "items": { "type": "object" } }, "near_matches": { "type": "array", "items": { "type": "object" } }, "library_fit": { "type": "string", "enum": [ "full", "close", "weak", "none" ] }, "unverified_requirements": { "type": "array", "items": {} }, "diagnostics": { "type": "object" } } }, "SoundDetail": { "type": "object", "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "category": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "duration_ms": { "type": "integer", "description": "Length of the file." }, "loopable": { "type": "boolean", "description": "Legacy flag; use loop_status=prepared for a checked loop." }, "loop_status": { "type": "string" }, "license": { "type": "string", "example": "CC0-1.0" }, "acoustics": { "$ref": "#/components/schemas/Acoustics" }, "format_metadata": { "type": "object", "description": "Per format (wav, mp3, ogg): sha256, bytes, duration_ms, sample_rate, channels, codec and decode checks." }, "mp3_url": { "type": "string", "format": "uri" }, "wav_url": { "type": "string", "format": "uri" }, "ogg_url": { "type": "string", "format": "uri", "description": "Sounds published before 2026-10-14." }, "page_url": { "type": "string", "format": "uri" }, "license_url": { "type": "string", "format": "uri" }, "peaks_url": { "type": "string", "format": "uri" }, "created_at": { "type": "integer" } } }, "Role": { "type": "object", "properties": { "role": { "type": "string" }, "label": { "type": "string" }, "aliases": { "type": "array", "items": { "type": "string" } }, "families": { "type": "array", "items": { "type": "string" } }, "audiences": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string", "format": "uri" } } }, "RoleSound": { "type": "object", "properties": { "role": { "type": "string" }, "label": { "type": "string" }, "aliases": { "type": "array", "items": { "type": "string" } }, "audiences": { "type": "array", "items": { "type": "string" } }, "style": { "type": "string", "enum": [ "balanced", "crisp", "soft", "spacious" ] }, "slug": { "type": "string" }, "title": { "type": "string" }, "duration_ms": { "type": "integer" }, "audible_ms": { "type": "integer" }, "loopable": { "type": "boolean" }, "license": { "type": "string" }, "acoustics": { "$ref": "#/components/schemas/Acoustics" }, "format_metadata": { "type": "object" }, "mp3_url": { "type": "string", "format": "uri" }, "wav_url": { "type": "string", "format": "uri" }, "ogg_url": { "type": "string", "format": "uri", "description": "Sounds published before 2026-10-14." }, "page_url": { "type": "string", "format": "uri" }, "alternates": { "type": "array", "items": { "type": "object" } }, "family": { "type": "string" }, "family_url": { "type": "string", "format": "uri" }, "url": { "type": "string", "format": "uri" } } }, "SetSummary": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "tagline": { "type": "string" }, "use_for": { "type": "string" }, "style": { "type": "string" }, "roles": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string", "format": "uri" }, "page_url": { "type": "string", "format": "uri" } } }, "SoundSet": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "tagline": { "type": "string" }, "use_for": { "type": "string" }, "style": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3", "ogg" ] }, "license": { "type": "string" }, "page_url": { "type": "string", "format": "uri" }, "sounds": { "type": "object", "additionalProperties": { "type": "object" }, "description": "Role → the role's sound, with alternates." }, "urls": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" }, "description": "Role → MP3 URL." }, "download_urls": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" }, "description": "Role → URL in the chosen format." }, "missing_roles": { "type": "array", "items": { "type": "string" } } } }, "OrderRequest": { "type": "object", "required": [ "prompt" ], "properties": { "prompt": { "type": "string", "description": "The sound in plain words, in any language: what it is for and what should be heard. Leave lengths to duration_s." }, "variations": { "type": "integer", "enum": [ 1, 2, 4 ], "default": 4, "description": "Takes to make." }, "duration_s": { "description": "Longest a take may be, in seconds; left out or \"auto\", SFXMint chooses.", "oneOf": [ { "type": "number", "enum": [ 0.2, 0.5, 1, 1.5, 2, 2.5, 3, 4, 5, 6, 7, 8, 9, 10 ] }, { "const": "auto" } ] }, "enhance": { "type": "boolean", "default": false, "description": "Write the prompt into a full sound description first." }, "refine": { "type": "object", "description": "Change a take instead of making a new one (free): {from: , take, change}." } } }, "OrderCreated": { "type": "object", "properties": { "order_id": { "type": "string" }, "free": { "type": "boolean" }, "held": { "type": "boolean" } } }, "OrderDetail": { "type": "object", "properties": { "order": { "type": "object" }, "files": { "type": "array", "items": { "type": "object" } }, "license": { "type": [ "string", "null" ] }, "license_id": { "type": [ "string", "null" ] } } } } } }