# Efecte sonore (/ro/docs/gateway/sfx) Biblioteca de efecte sonore codai Studio — cauți sunete CC0 selectate, le imporți gratuit ca asset-uri și le folosești în randări. codai Studio vine cu o **bibliotecă de efecte sonore**: lovituri, whoosh-uri, click-uri, notificări, bipuri sci-fi, foley, jingle-uri și altele, gata de pus într-o [randare](./renders.mdx). Id-ul public al modelului este `codai-sfx`. Căutarea și importul sunt **gratuite**; căutarea se socotește în limita obișnuită de cereri a cheii tale. | Metodă | Cale | Rezultat | | --- | --- | --- | | `GET` | `/v1/studio/sfx?q=&category=&tags=&max_duration=&limit=` | `{ object: "list", data: [sunet…], source }`, cel mai relevant primul | | `POST` | `/v1/studio/sfx/{sfx_id}/import` | Sunetul copiat în [asset-urile](./assets.mdx) tale (`kind: "sfx"`) | ## Ce conține biblioteca [#ce-conține-biblioteca] Biblioteca este un set selectat de sunete **CC0** stocate de codai în europe-west1 — azi pachetele [Kenney](https://kenney.nl) *Impact Sounds*, *Interface Sounds*, *UI Audio*, *Digital Audio*, *Sci-fi Sounds*, *RPG Audio* (foley), *Casino Audio* și *Music Jingles*. Când biblioteca întoarce mai puțin de jumătate din `limit` și gateway-ul are o cheie Freesound, restul paginii se completează cu sunete **Creative Commons 0** de pe [Freesound](https://freesound.org) (`source: "library+freesound"`, id-uri care încep cu `fs-`). Se întorc și se importă doar sunete Freesound CC0. Cheile cu rezidența datelor în UE nu folosesc niciodată completarea din Freesound. Dacă Freesound e lent sau indisponibil primești totuși rezultatele din bibliotecă, cu antetul de răspuns `x-codai-sfx-fallback: unavailable`. ### Categorii [#categorii] | `category` | Sunete tipice | | --- | --- | | `impact` | Lovituri, pumni, impacturi de metal și lemn | | `whoosh` | Fâșâituri, mișcări rapide | | `ui` | Click-uri, comutatoare, apăsări de butoane | | `notification` | Alerte, ping-uri, confirmări, erori | | `transition` | Riser-e, sweep-uri, schimbări de scenă | | `ambience` | Bucle și ton de cameră | | `foley` | Pași, uși, haine, obiecte manevrate | | `scifi` | Lasere, motoare, bipuri de calculator | | `cartoon` | Boing-uri, pocnituri, efecte comice | | `nature` | Apă, vânt, animale | | `crowd` | Aplauze, ovații, voci | | `other` | Jingle-uri, sunete de cazino și orice altceva | ## Licență [#licență] Fiecare sunet are licența **CC0-1.0** (dedicare în domeniul public): îl poți folosi în video-uri comerciale, îl poți modifica și redistribui și **nu e nevoie de atribuire**. Fiecare rezultat are `license: "CC0-1.0"`; sunetele Freesound sunt reverificate la import și refuzate cu `400 license_not_allowed` dacă licența nu e exact CC0. ## Căutare [#căutare] | Parametru | Semnificație | | --- | --- | | `q` | Text liber căutat în nume, etichete, categorie și pachet (sintaxă de căutare web: `metal hit`, `"coin pickup"`, `laser -gun`). | | `category` | Una dintre categoriile de mai sus. | | `tags` | Etichete separate prin virgulă; un sunet se potrivește dacă are cel puțin una. | | `max_duration` | Doar sunetele de cel mult atâtea secunde. | | `limit` | Între 1 și 50, implicit 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` îți permite să asculți înainte de import: un URL semnat valabil o oră pentru sunetele din bibliotecă, previzualizarea MP3 HQ de pe Freesound pentru sunetele `fs-`. ## Importul și folosirea unui sunet într-o randare [#importul-și-folosirea-unui-sunet-într-o-randare] `POST /v1/studio/sfx/{sfx_id}/import` copiază sunetul în asset-urile tale și întoarce [obiectul asset](./assets.mdx#obiectul-asset) cu `kind: "sfx"` și `model: "codai-sfx"`. Se păstrează 90 de zile, ca orice asset, și apare și în `GET /v1/assets?kind=sfx`. Folosește-l în HTML-ul unei randări ca `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 ``` ## Erori [#erori] | HTTP | `code` | Când | | --- | --- | --- | | 400 | `bad_request` | `category`, `max_duration` sau `limit` invalid. | | 400 | `license_not_allowed` | Un sunet Freesound a cărui licență nu e CC0. | | 404 | `not_found` | `sfx_id` necunoscut. | | 503 | `assets_unavailable` | Stocarea asset-urilor nu e configurată pe acest gateway. | ## SDK-uri [#sdk-uri] ```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` e cuvânt rezervat în Python, de aici import_ html = f'''

Boom

''' video = client.renders.render({"html": html}) ``` Rezultatul TypeScript are și `fallbackUnavailable`, iar cel Python `fallback_unavailable`, ambele `true` când răspunsul a avut `x-codai-sfx-fallback: unavailable`.