{"openapi":"3.1.0","info":{"title":"SFX Engine API","description":"API for creating and managing sound effects and songs","version":"1.0.0"},"servers":[{"url":"https://api.sfxengine.com/v1","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"Sound Effects","description":"Generate and look up sound effects"},{"name":"Songs","description":"Generate and look up songs and background music"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","description":"Your API key, sent as `Authorization: Bearer YOUR_API_KEY`."}},"schemas":{"SoundEffect":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the sound effect"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"length":{"type":"number","description":"Duration of the sound effect in seconds"},"userId":{"type":"string","description":"ID of the user who created the sound effect"},"prompt":{"type":"string","description":"Text prompt used to generate the sound effect"},"isPublic":{"type":"boolean","description":"Whether the sound effect is publicly accessible"},"url":{"type":"string","description":"URL to access the sound effect file"},"fileSize":{"type":"number","description":"Size of the sound effect file in bytes"},"status":{"type":"string","enum":["generated","processing","failed"],"description":"Current status of the sound effect"},"imageUrl":{"type":["string","null"],"description":"URL to the generated image for the sound effect"}},"required":["id","createdAt","length","userId","prompt","isPublic","url","fileSize","status","imageUrl"]},"PaginatedSoundEffects":{"type":"object","properties":{"pageCount":{"type":"integer","description":"Total number of pages available"},"sounds":{"type":"array","items":{"$ref":"#/components/schemas/SoundEffect"},"description":"List of sound effects for the current page"}},"required":["pageCount","sounds"]},"ValidationError":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"name":{"type":"string","example":"ZodError"},"message":{"type":"string","description":"JSON-encoded list of validation issues (field path and reason)"}},"required":["name","message"]}},"required":["success","error"],"description":"Returned when the body, query or path parameters fail validation."},"Song":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the song"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"length":{"type":"number","description":"Duration of the song in seconds"},"userId":{"type":"string","description":"ID of the user who created the song"},"prompt":{"type":"string","description":"Text prompt used to generate the song"},"isPublic":{"type":"boolean","description":"Whether the song is publicly accessible"},"url":{"type":"string","description":"URL to access the song file"},"fileSize":{"type":"number","description":"Size of the song file in bytes"},"status":{"type":"string","enum":["generated","processing","failed"],"description":"Current status of the song"},"imageUrl":{"type":["string","null"],"description":"URL to the generated image for the song"}},"required":["id","createdAt","length","userId","prompt","isPublic","url","fileSize","status","imageUrl"]},"PaginatedSongs":{"type":"object","properties":{"pageCount":{"type":"integer","description":"Total number of pages available"},"songs":{"type":"array","items":{"$ref":"#/components/schemas/Song"},"description":"List of songs for the current page"}},"required":["pageCount","songs"]}},"parameters":{}},"paths":{"/sound-effect":{"get":{"tags":["Sound Effects"],"operationId":"listSoundEffects","summary":"List all sound effects","description":"Returns a paginated list of sound effects created by anyone in the API key's organization","parameters":[{"schema":{"type":"string","default":"0","description":"Page number (zero-based)","example":"0"},"required":false,"description":"Page number (zero-based)","name":"page","in":"query"},{"schema":{"type":"string","default":"25","description":"Number of items per page (max 25)","example":"25"},"required":false,"description":"Number of items per page (max 25)","name":"limit","in":"query"}],"responses":{"200":{"description":"A paginated list of sound effects","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedSoundEffects"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"text/plain":{"schema":{"type":"string","example":"Invalid API key"}}}},"403":{"description":"Forbidden - The API key owner is banned or has not verified their email","content":{"text/plain":{"schema":{"type":"string","example":"Verify your email to continue"}}}},"500":{"description":"Internal Server Error","content":{"text/plain":{"schema":{"type":"string","example":"Internal Server Error"}}}}}},"post":{"tags":["Sound Effects"],"operationId":"createSoundEffect","summary":"Create a new sound effect","description":"Starts generating a sound effect from the prompt. The response has `status: \"processing\"`; poll `GET /sound-effect/{soundEffectId}` or pass `webhookUrl` to learn when it is ready.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","minLength":1,"maxLength":255,"description":"Text prompt describing the sound to generate","example":"Heavy wooden door creaking open"},"length":{"anyOf":[{"type":"integer","minimum":1,"maximum":47},{"type":"string","enum":["auto"]}],"default":"auto","description":"Length in whole seconds (1–47), or \"auto\" to pick one that fits the prompt.","example":"auto"},"secondsToStart":{"type":"integer","minimum":0,"maximum":47,"default":0,"description":"Ignored. Kept so existing requests stay valid.","deprecated":true},"isPublic":{"type":"boolean","default":false,"description":"Whether the sound effect should be publicly accessible"},"webhookUrl":{"type":"string","format":"uri","description":"URL we POST the finished sound to as JSON (`id`, `createdAt`, `length`, `prompt`, `url`, `fileSize`, `isPublic`) once it is generated. Not called if generation fails."},"projectId":{"type":"string","pattern":"^proj_[a-zA-Z0-9]+$","description":"ID of a project in your organization (`proj_…`) to add the sound to. Omit to leave it unsorted."}},"required":["prompt"]}}}},"responses":{"200":{"description":"Sound effect created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SoundEffect"}}}},"400":{"description":"Bad Request. Invalid parameters return a JSON `ValidationError`; requests that are valid but can't be fulfilled (e.g. insufficient credits, a prompt blocked by moderation) return a plain-text message.","content":{"text/plain":{"schema":{"type":"string","example":"Insufficient credits"}},"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"text/plain":{"schema":{"type":"string","example":"Invalid API key"}}}},"403":{"description":"Forbidden - The API key owner is banned or has not verified their email","content":{"text/plain":{"schema":{"type":"string","example":"Verify your email to continue"}}}},"404":{"description":"Not Found - `projectId` is not a project in your organization","content":{"text/plain":{"schema":{"type":"string","example":"Project not found"}}}},"409":{"description":"Conflict - the project is archived and can't receive new sounds","content":{"text/plain":{"schema":{"type":"string","example":"Project is archived"}}}},"429":{"description":"Too Many Requests - Creation requests are rate limited per account","content":{"text/plain":{"schema":{"type":"string","example":"Too many requests. Please wait a moment and try again."}}}},"500":{"description":"Internal Server Error","content":{"text/plain":{"schema":{"type":"string","example":"Internal Server Error"}}}}}}},"/sound-effect/{soundEffectId}":{"get":{"tags":["Sound Effects"],"operationId":"getSoundEffect","summary":"Get a specific sound effect","description":"Returns details for a specific sound effect","parameters":[{"schema":{"type":"string","pattern":"^se_[a-zA-Z0-9]+$","description":"ID of the sound effect to retrieve","example":"se_abc123"},"required":true,"description":"ID of the sound effect to retrieve","name":"soundEffectId","in":"path"}],"responses":{"200":{"description":"Sound effect details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SoundEffect"}}}},"400":{"description":"Bad Request. Invalid parameters return a JSON `ValidationError`; requests that are valid but can't be fulfilled (e.g. insufficient credits, a prompt blocked by moderation) return a plain-text message.","content":{"text/plain":{"schema":{"type":"string","example":"Insufficient credits"}},"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"text/plain":{"schema":{"type":"string","example":"Invalid API key"}}}},"403":{"description":"Forbidden - The API key owner is banned or has not verified their email","content":{"text/plain":{"schema":{"type":"string","example":"Verify your email to continue"}}}},"404":{"description":"Not Found - Resource does not exist","content":{"text/plain":{"schema":{"type":"string","example":"Sound effect not found"}}}},"500":{"description":"Internal Server Error","content":{"text/plain":{"schema":{"type":"string","example":"Internal Server Error"}}}}}}},"/song":{"get":{"tags":["Songs"],"operationId":"listSongs","summary":"List all songs","description":"Returns a paginated list of songs created by the API key owner","parameters":[{"schema":{"type":"string","default":"0","description":"Page number (zero-based)","example":"0"},"required":false,"description":"Page number (zero-based)","name":"page","in":"query"},{"schema":{"type":"string","default":"25","description":"Number of items per page (max 25)","example":"25"},"required":false,"description":"Number of items per page (max 25)","name":"limit","in":"query"}],"responses":{"200":{"description":"A paginated list of songs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedSongs"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"text/plain":{"schema":{"type":"string","example":"Invalid API key"}}}},"403":{"description":"Forbidden - The API key owner is banned or has not verified their email","content":{"text/plain":{"schema":{"type":"string","example":"Verify your email to continue"}}}},"500":{"description":"Internal Server Error","content":{"text/plain":{"schema":{"type":"string","example":"Internal Server Error"}}}}}},"post":{"tags":["Songs"],"operationId":"createSong","summary":"Create a new song","description":"Starts generating a song from the prompt. The response has `status: \"processing\"`; poll `GET /song/{songId}` to learn when it is ready.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["song","background-music"],"description":"`song` for a full song, `background-music` for a background music track"},"prompt":{"type":"string","minLength":1,"maxLength":255,"description":"Text prompt describing the song to generate","example":"Upbeat synthwave for a racing game menu"}},"required":["type","prompt"]}}}},"responses":{"200":{"description":"Song created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Song"}}}},"400":{"description":"Bad Request. Invalid parameters return a JSON `ValidationError`; requests that are valid but can't be fulfilled (e.g. insufficient credits, a prompt blocked by moderation) return a plain-text message.","content":{"text/plain":{"schema":{"type":"string","example":"Insufficient credits"}},"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"text/plain":{"schema":{"type":"string","example":"Invalid API key"}}}},"403":{"description":"Forbidden - The API key owner is banned or has not verified their email","content":{"text/plain":{"schema":{"type":"string","example":"Verify your email to continue"}}}},"429":{"description":"Too Many Requests - Creation requests are rate limited per account","content":{"text/plain":{"schema":{"type":"string","example":"Too many requests. Please wait a moment and try again."}}}},"500":{"description":"Internal Server Error","content":{"text/plain":{"schema":{"type":"string","example":"Internal Server Error"}}}}}}},"/song/{songId}":{"get":{"tags":["Songs"],"operationId":"getSong","summary":"Get a specific song","description":"Returns details for a specific song","parameters":[{"schema":{"type":"string","pattern":"^so_[a-zA-Z0-9]+$","description":"ID of the song to retrieve","example":"so_abc123"},"required":true,"description":"ID of the song to retrieve","name":"songId","in":"path"}],"responses":{"200":{"description":"Song details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Song"}}}},"400":{"description":"Bad Request. Invalid parameters return a JSON `ValidationError`; requests that are valid but can't be fulfilled (e.g. insufficient credits, a prompt blocked by moderation) return a plain-text message.","content":{"text/plain":{"schema":{"type":"string","example":"Insufficient credits"}},"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"text/plain":{"schema":{"type":"string","example":"Invalid API key"}}}},"403":{"description":"Forbidden - The API key owner is banned or has not verified their email","content":{"text/plain":{"schema":{"type":"string","example":"Verify your email to continue"}}}},"404":{"description":"Not Found - Resource does not exist","content":{"text/plain":{"schema":{"type":"string","example":"Song not found"}}}},"500":{"description":"Internal Server Error","content":{"text/plain":{"schema":{"type":"string","example":"Internal Server Error"}}}}}}}},"webhooks":{}}