{
  "name": "app-audio",
  "title": "App API - Audio Services (Sound Effects, Music, Transcription)",
  "description": "Sound effects, music generation, and audio transcription services for deployed apps",
  "guid": "sk_plat_aaud",
  "category": "App services",
  "requiredTools": [
    "project_settings"
  ],
  "content": "# App API - Audio Services (Sound Effects, Music, Transcription)\n\nThree audio services available for every project with no setup needed (owner_pays by default).\n\nUse `project_settings` to customize each independently (optional).\n\n---\n\n## Sound Effects\n\nGenerate sound effects from text descriptions using ElevenLabs.\n\n### Endpoint\n`POST /api/<PROJECT_GUID>/services/sound`\n\n### Request\n```json\n{\n  \"text\": \"thunder rumbling in the distance\",\n  \"duration_seconds\": 5,\n  \"prompt_influence\": 0.5\n}\n```\n- `text` (required): Description of the sound, max 1,000 chars\n- `duration_seconds`: 0.5-30 (optional, provider decides if omitted)\n- `prompt_influence`: 0-1, how closely to follow the prompt (optional)\n\n### Response\n```json\n{\n  \"url\": \"https://media.gipity.ai/med_abc12345.mp3\",\n  \"duration_seconds\": 5,\n  \"credits_used\": 2\n}\n```\n\n---\n\n## Music Generation\n\nGenerate music from text prompts using ElevenLabs.\n\n### Endpoint\n`POST /api/<PROJECT_GUID>/services/music`\n\n### Request\n```json\n{\n  \"prompt\": \"upbeat lo-fi hip hop beat with piano and soft drums\",\n  \"duration_seconds\": 30,\n  \"instrumental\": true\n}\n```\n- `prompt` (required): Music description, max 2,000 chars\n- `duration_seconds`: 3-600 (optional, default ~30s)\n- `instrumental`: true to force no vocals (optional)\n\n### Response\n```json\n{\n  \"url\": \"https://media.gipity.ai/med_abc12345.mp3\",\n  \"duration_seconds\": 30,\n  \"credits_used\": 3\n}\n```\n\n---\n\n## Audio Transcription\n\nTranscribe audio files to text. Supports ElevenLabs (Scribe v2) and OpenAI (GPT-4o Transcribe).\n\n### Endpoint\n`POST /api/<PROJECT_GUID>/services/transcribe` (multipart/form-data)\n\n### Request\nSend as `multipart/form-data`:\n- `audio` (required): Audio file (MP3, WAV, M4A, etc.), max 100MB\n- `provider`: \"elevenlabs\" (default) or \"openai\"\n- `language`: Language code (e.g., \"en\", \"es\") - optional, auto-detected\n- `diarize`: \"true\" to identify speakers (optional)\n\n### Response\n```json\n{\n  \"text\": \"Hello, this is a transcription test.\",\n  \"words\": [{ \"text\": \"Hello\", \"start\": 0.0, \"end\": 0.5, \"type\": \"word\" }],\n  \"language\": \"en\",\n  \"duration_seconds\": 12.5,\n  \"provider\": \"elevenlabs\",\n  \"credits_used\": 5\n}\n```\n\n---\n\n## Client Code Examples\n\n```js\n// Get token first\nconst tokenRes = await fetch('https://a.gipity.ai/api/token', {\n  method: 'POST',\n  headers: { 'Content-Type': 'application/json' },\n  body: JSON.stringify({ app: '<PROJECT_GUID>' })\n});\nconst { data: { token } } = await tokenRes.json();\n\n// Sound effect\nconst soundRes = await fetch('https://a.gipity.ai/api/<PROJECT_GUID>/services/sound', {\n  method: 'POST',\n  headers: { 'Content-Type': 'application/json', 'X-App-Token': token },\n  body: JSON.stringify({ text: 'door creaking open slowly' })\n});\nconst sound = await soundRes.json();\nnew Audio(sound.url).play();\n\n// Music\nconst musicRes = await fetch('https://a.gipity.ai/api/<PROJECT_GUID>/services/music', {\n  method: 'POST',\n  headers: { 'Content-Type': 'application/json', 'X-App-Token': token },\n  body: JSON.stringify({ prompt: 'calm ambient piano', duration_seconds: 60 })\n});\nconst music = await musicRes.json();\nnew Audio(music.url).play();\n\n// Transcription (from file input)\nconst formData = new FormData();\nformData.append('audio', fileInput.files[0]);\nformData.append('diarize', 'true');\nconst transRes = await fetch('https://a.gipity.ai/api/<PROJECT_GUID>/services/transcribe', {\n  method: 'POST',\n  headers: { 'X-App-Token': token },\n  body: formData\n});\nconst transcript = await transRes.json();\nconsole.log(transcript.text);\n```\n\n## Limits\n- **Rate limit**: 600 requests per 5-minute window (per IP, all audio endpoints)\n- **Sound text**: max 1,000 chars, duration 0.5-30s, timeout 60s\n- **Music prompt**: max 2,000 chars, duration 3-600s, timeout 120s\n- **Transcription**: max 100MB file, timeout 120s\n- Standard `RateLimit-*` headers included in responses"
}