Sound effects
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. 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 (kind: "sfx") |
What is in the library
The library is a curated set of CC0 sounds stored by codai in europe-west1 — today the Kenney 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 (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
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
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
| 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. |
curl "https://ai.codai.ro/v1/studio/sfx?q=metal%20hit&category=impact&max_duration=2&limit=5" \
-H "Authorization: Bearer $CODAI_API_KEY"{
"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
POST /v1/studio/sfx/{sfx_id}/import copies the sound into your assets and returns 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:<asset_id>:
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)<audio class="clip" src="asset:7d0f2c1e-4b8a-4c1e-9a51-0f3c2e8d9b10"
data-start="1.2" data-duration="0.62" data-track-index="3"></audio>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
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: `<div data-composition-id="hit" data-width="1920" data-height="1080">
<h1 class="clip" data-start="0" data-duration="3" data-track-index="0">Boom</h1>
<audio class="clip" src="asset:${asset.asset_id}" data-start="0.5" data-duration="1.5" data-track-index="1"></audio>
</div>`,
});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'''<div data-composition-id="hit" data-width="1920" data-height="1080">
<h1 class="clip" data-start="0" data-duration="3" data-track-index="0">Boom</h1>
<audio class="clip" src="asset:{asset["asset_id"]}" data-start="0.5" data-duration="1.5" data-track-index="1"></audio>
</div>'''
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.
Share, review and remix
Public read-only links to a creative, review links with anchored comments and approval, and remix of a shared creative into your own account.
Request headers
Every header the gateway reads and every header it sends back — auth, client identity, caching, effort, thinking, sessions, tasks, cost.