Adds an event to an entity OR to a folder. The event name is WHAT happens (Move, Attack, Die, Land, Click, Undo, Level complete), never 'Sound' or 'Som'. A folder event applies to all entities inside it (e.g. 'Select' once for all units); an entity can have its own with the same name, which wins. Game actions with no owner (Undo, Victory, Level complete) go as events of the Interface folder. Ambience (wind, rain, forest) goes in the Ambience folder ("Ambiente" in Portuguese games). Always say whether it is a loop. LOOP OR ONE-SHOT, decided from what the sound is in the game: a LOOP is anything that lasts while something keeps happening and the game plays on repeat: ambience and weather, music, engines and machines, fire burning, flowing water, AND movement cycles: footsteps, walking, running, crawling, galloping, sustained wing flapping, rolling. Footsteps are a walk cycle with several steps (6-10 s), never a single step. A ONE-SHOT is one discrete action: hit, swing, click, cry, death, explosion, door, item, sting. DURATION: one-shots at least 2 s even for a tiny click, since shorter clips come out thin (hits, clicks and swings 2 s; cries, deaths, collapses and stings 3-5 s); movement loops 6-10 s; ambience, engine and fire loops 10-16 s. A music TRACK (Music folder) is not a sound effect: it is generated with generate_music and lasts up to the user's plan limit (generate_music duration_sec says it), usually 1-3 min for a theme and 30-60 s for a short loop. The server refuses one-shots under 2 s and loops under 6 s. COST = seconds rounded up × the account price per second (creditsPerSecond in list_games) × variations. Omit duration_sec and a loop is born at 12 s, a one-shot at 2 s. A TRACK in the Music folder follows the music limits instead (a longer prompt, duration up to the user's plan; see duration_sec; omitted: 1 min or the plan limit) and takes the same form as generate_music (genres, bpm, key_scale, time_signature...), saved on it so the site shows it before generating; the form is ignored for other sounds. Several tracks: create_tracks. Generate it with generate_music. On the site an event is a SOUND card (its variations are the versions): call it a sound when talking to the user. Creating an event spends no credits and generates nothing: generate it with generate_sounds (or generate_music). Returns the event id and its site page (url).
View input schema
{
"type": "object",
"properties": {
"entity_id": {
"description": "The entity that owns the event (from get_game). Pass entity_id OR folder_id, never both.",
"type": "string"
},
"folder_id": {
"description": "The folder that owns the event (from list_folders): every entity inside inherits it. Pass entity_id OR folder_id, never both.",
"type": "string"
},
"name": {
"description": "What happens, in the game's language (Attack, Die, Click, Level complete). Up to 60 characters. If the owner already has an event with this name, that one is returned instead of a new one.",
"minLength": 1,
"maxLength": 60,
"type": "string"
},
"prompt": {
"description": "What the sound should sound like, preferably in English, saved on the event for generating later. Up to 450 characters for a sound; up to 512 for a track in the Music folder.",
"minLength": 1,
"maxLength": 512,
"type": "string"
},
"duration_sec": {
"description": "Sounds (up to 30 s): one-shot at least 2 s (hits 2 s, cries and deaths 3-5 s); movement loops like footsteps 6-10 s; ambience 10-16 s. Omitted: loop 12 s, one-shot 2 s. A track in the Music folder: Whole seconds, 10 to 240 (4 min). The user's plan may allow less: the server refuses a longer track. Omitted: 1 min (or the plan limit, if lower).",
"minimum": 2,
"maximum": 240,
"type": "number"
},
"quality": {
"description": "draft (fast and cheap, to test the idea), good, high (the approved default), max (large model; may be unavailable). The price per minute follows the level.",
"enum": [
"draft",
"good",
"high",
"max"
],
"type": "string"
},
"mode": {
"description": "describe = only the prompt; compose = you also set the tempo, key and meter. Omitted: compose when bpm, key_scale, time_signature, genres or sung lyrics are sent, otherwise the track keeps its current mode.",
"enum": [
"describe",
"compose"
],
"type": "string"
},
"genres": {
"description": "Musical style (the site's \"Estilo musical\"): ONE genre as a one-item list. Its words are written at the start of the prompt (empty = only your prompt).",
"maxItems": 1,
"items": {
"enum": [
"folk",
"synthwave",
"rock",
"metal",
"thrash",
"power",
"death",
"black",
"doom",
"pop",
"epic",
"orchestral",
"classical",
"choral",
"medieval",
"celtic",
"tribal",
"pirate",
"western",
"japanese",
"desert",
"chiptune",
"electronic",
"cyberpunk",
"ambient",
"horror",
"lofi",
"comic",
"military",
"jazz",
"hiphop",
"blues",
"funk",
"bossa",
"samba",
"latin"
],
"type": "string"
},
"type": "array"
},
"bpm": {
"description": "Compose (\"Andamento\"): tempo in beats per minute (60 to 180 sound best).",
"minimum": 30,
"maximum": 300,
"type": "integer"
},
"key_scale": {
"description": "Compose (\"Tom\"): the key, e.g. \"A minor\".",
"enum": [
"C major",
"C minor",
"C# major",
"C# minor",
"D major",
"D minor",
"Eb major",
"Eb minor",
"E major",
"E minor",
"F major",
"F minor",
"F# major",
"F# minor",
"G major",
"G minor",
"Ab major",
"Ab minor",
"A major",
"A minor",
"Bb major",
"Bb minor",
"B major",
"B minor"
],
"type": "string"
},
"time_signature": {
"description": "Compose (\"Compasso\"): beats per bar (2, 3 = waltz, 4 = most music, 6 = compound like 6/8).",
"enum": [
2,
3,
4,
6
],
"type": "integer"
},
"instrumental": {
"description": "false = sung, with the lyrics below.",
"default": true,
"type": "boolean"
},
"lyrics": {
"description": "The lyrics, one line per row, parts marked with [Verse], [Chorus], [Bridge]... Only with instrumental=false.",
"maxLength": 4096,
"type": "string"
},
"language": {
"description": "Language of the lyrics.",
"enum": [
"pt-BR",
"en"
],
"type": "string"
},
"vocal_level": {
"description": "Sung tracks: the voice behind the band (back), even (balanced, default, adds nothing) or up front (front); written at the end of the prompt.",
"enum": [
"back",
"balanced",
"front"
],
"type": "string"
},
"voice": {
"description": "Sung tracks: who sings (gender), how deep (timbre) and up to 2 singing styles, written at the end of the prompt. Omitted: the model picks.",
"properties": {
"gender": {
"enum": [
"male",
"female",
"duet",
"choir"
],
"type": "string"
},
"timbre": {
"enum": [
"low",
"mid",
"high"
],
"type": "string"
},
"styles": {
"maxItems": 2,
"items": {
"enum": [
"breathy",
"powerful",
"raspy",
"falsetto",
"spoken",
"screamed"
],
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"loop": {
"description": "Required. true for anything continuous the game repeats: ambience, music, engines, fire, water and movement cycles (footsteps, running, flapping). false for one discrete action (hit, click, cry, death).",
"type": "boolean"
}
},
"required": [
"name",
"prompt",
"loop"
]
}