# Sound effects (/docs/gateway/sfx) codai Studio sound-effects library — search curated CC0 sounds, import them as assets for free and use them in renders. codai Studio ships a **sound-effects library**: hits, whooshes, clicks, notifications, sci-fi beeps, foley, jingles and more, ready to drop into a [render](./renders.mdx). The public model id is `codai-sfx`. Searching and importing are **free**; search counts against your key's normal rate limit. | Method | Path | Result | | --- | --- | --- | | `GET` | `/v1/studio/sfx?q=&category=&tags=&max_duration=&limit=` | `{ object: "list", data: [sound…], source }`, best match first | | `POST` | `/v1/studio/sfx/{sfx_id}/import` | The sound copied into your [assets](./assets.mdx) (`kind: "sfx"`) | ## What is in the library [#what-is-in-the-library] The library is a curated set of **CC0** sounds stored by codai in europe-west1 — today the [Kenney](https://kenney.nl) packs *Impact Sounds*, *Interface Sounds*, *UI Audio*, *Digital Audio*, *Sci-fi Sounds*, *RPG Audio* (foley), *Casino Audio* and *Music Jingles*. When the library returns fewer than half of the `limit` you asked for and the gateway has a Freesound key, the rest of the page is filled with **Creative Commons 0** sounds from [Freesound](https://freesound.org) (`source: "library+freesound"`, ids starting with `fs-`). Only CC0 Freesound sounds are ever returned or imported. Keys with EU data residency never use the Freesound fallback. If Freesound is slow or down you still get the library results, with the response header `x-codai-sfx-fallback: unavailable`. ### Categories [#categories] | `category` | Typical sounds | | --- | --- | | `impact` | Hits, punches, metal and wood impacts | | `whoosh` | Swishes, swooshes, fast movement | | `ui` | Clicks, toggles, button presses | | `notification` | Alerts, pings, confirmations, errors | | `transition` | Risers, sweeps, scene changes | | `ambience` | Loops and room tones | | `foley` | Footsteps, doors, cloth, handling objects | | `scifi` | Lasers, engines, computer beeps | | `cartoon` | Boings, pops, comic effects | | `nature` | Water, wind, animals | | `crowd` | Applause, cheers, voices | | `other` | Jingles, casino sounds and everything else | ## Licence [#licence] Every sound is licensed **CC0-1.0** (public-domain dedication): you can use it in commercial videos, modify it and redistribute it, and **no attribution is needed**. Each result carries `license: "CC0-1.0"`; Freesound sounds are re-checked when you import them and refused with `400 license_not_allowed` if their licence is not exactly CC0. ## Searching [#searching] | Parameter | Meaning | | --- | --- | | `q` | Free text matched against name, tags, category and pack (web-search syntax: `metal hit`, `"coin pickup"`, `laser -gun`). | | `category` | One of the categories above. | | `tags` | Comma-separated tags; a sound matches when it has at least one. | | `max_duration` | Only sounds at most this many seconds long. | | `limit` | 1–50, default 20. | ```bash curl "https://ai.codai.ro/v1/studio/sfx?q=metal%20hit&category=impact&max_duration=2&limit=5" \ -H "Authorization: Bearer $CODAI_API_KEY" ``` ```json { "object": "list", "source": "library", "data": [ { "sfx_id": "kenney-impact-metal-heavy-001", "name": "Metal heavy 1", "category": "impact", "tags": ["metal", "heavy", "impact"], "duration_seconds": 0.62, "mime_type": "audio/ogg", "license": "CC0-1.0", "source": "kenney", "preview_url": "https://storage.googleapis.com/…&X-Goog-Signature=…" } ] } ``` `preview_url` lets you listen before importing: a 1-hour signed URL for library sounds, the Freesound HQ MP3 preview for `fs-` sounds. ## Importing and using a sound in a render [#importing-and-using-a-sound-in-a-render] `POST /v1/studio/sfx/{sfx_id}/import` copies the sound into your assets and returns the [asset object](./assets.mdx#the-asset-object) with `kind: "sfx"` and `model: "codai-sfx"`. It is kept 90 days like every asset and also appears in `GET /v1/assets?kind=sfx`. Reference it in a render's HTML as `asset:`: ```bash ASSET_ID=$(curl -s -X POST "https://ai.codai.ro/v1/studio/sfx/kenney-impact-metal-heavy-001/import" \ -H "Authorization: Bearer $CODAI_API_KEY" | jq -r .asset_id) ``` ```html ``` ## Errors [#errors] | HTTP | `code` | When | | --- | --- | --- | | 400 | `bad_request` | Invalid `category`, `max_duration` or `limit`. | | 400 | `license_not_allowed` | A Freesound sound whose licence is not CC0. | | 404 | `not_found` | Unknown `sfx_id`. | | 503 | `assets_unavailable` | Asset storage is not configured on this gateway. | ## SDKs [#sdks] ```ts import { Codai } from 'codai-sdk'; const client = new Codai({ apiKey: process.env.CODAI_API_KEY! }); const { data, source } = await client.sfx.search({ q: 'whoosh', category: 'whoosh', max_duration: 1.5, limit: 5 }); const asset = await client.sfx.import(data[0]!.sfx_id); // asset.kind === 'sfx' const render = await client.renders.render({ html: `

Boom

`, }); ``` ```python from codai import Codai client = Codai(api_key=os.environ["CODAI_API_KEY"]) r = client.sfx.search(q="whoosh", category="whoosh", max_duration=1.5, limit=5) asset = client.sfx.import_(r.data[0]["sfx_id"]) # `import` is a Python keyword, hence import_ html = f'''

Boom

''' video = client.renders.render({"html": html}) ``` The TypeScript result also has `fallbackUnavailable` and the Python one `fallback_unavailable`, both `true` when the response carried `x-codai-sfx-fallback: unavailable`.