🔌 API

• boundary:
  • all browser calls target local SvelteKit routes under https://elv3.loca.zone.
  • server routes call ElevenLabs and optional OpenRouter APIs with runtime secrets.
  • clients must authenticate through /auth before using workspace or API routes.
• authentication:
  • route: /auth
  • method: GET shows password form.
  • method: POST validates the configured password and sets eleven3_auth as an HttpOnly cookie.
  • cookie shape: timestamp plus HMAC signature.
  • max age: 30 days.
• rate_limit:
  • scope: paths beginning with /api/elevenlabs.
  • key: auth cookie.
  • policy: 30 requests per minute.
  • failure: HTTP 429 with JSON error and Retry-After: 60.
• voices:
  • route: GET /api/voices
  • upstream: ElevenLabs /v2/voices.
  • query:
    • search: optional voice search string.
    • page: optional page number, default 1.
    • page_size: optional page size, default 30.
  • response: upstream JSON voice list, pagination fields, and metadata.
• tts:
  • route: POST /api/elevenlabs/tts
  • stream: append ?stream=true to use the ElevenLabs stream endpoint.
  • upstream: /v1/text-to-speech/{voice_id} or /stream.
  • required_body:
    • voice_id: ElevenLabs voice identifier.
    • text: prompt text; Eleven v3 tags are supported when using eleven_v3.
  • optional_body:
    • model_id: defaults to eleven_v3.
    • output_format: defaults to mp3_44100_128.
    • speed: included only when not the default.
    • voice_settings: stability and similarity boost.
  • response: audio stream with an audio content type.
• dialogue:
  • route: POST /api/elevenlabs/dialogue
  • stream: append ?stream=true for streaming output.
  • upstream: /v1/text-to-dialogue or /stream.
  • required_body:
    • dialogue: non-empty array of { voice_id, text } rows.
  • optional_body:
    • model_id: defaults to eleven_v3.
    • output_format: defaults to mp3_44100_128.
  • transform: the app sends dialogue to the browser contract and forwards it upstream as inputs.
• sound_effects:
  • route: POST /api/elevenlabs/sfx
  • upstream: /v1/sound-generation.
  • required_body:
    • text: sound prompt.
  • optional_body:
    • duration_seconds: defaults to 2.0.
    • prompt_influence: defaults to 0.3.
  • response: MP3 attachment named with an sfx_ timestamp.
• voice_design:
  • route: POST /api/elevenlabs/voice-design
  • design_action: default when no action query is supplied.
  • save_action: use ?action=save.
  • design_upstream: /v1/text-to-voice/design with model_id: eleven_ttv_v3.
  • design_body:
    • voice_description: required.
    • text: optional preview text.
    • loudness: clamped to -1 through 1.
    • guidance_scale: clamped to 0 through 100.
    • output_format, should_enhance, quality, seed.
    • reference_audio_base_64 and prompt_strength for reference-guided design.
  • save_upstream: /v1/text-to-voice/create-voice-from-preview.
  • save_body:
    • generated_voice_id: required.
    • voice_name, voice_description, played_not_selected_voice_ids.
  • optional_enrichment:
    • OpenRouter can produce description and label metadata when its runtime key is configured.
    • lack of OpenRouter configuration is non-fatal; the original description is used.
• failure_contract:
  • missing required request fields return 400.
  • missing runtime API keys return 500 without disclosing secret values.
  • upstream ElevenLabs failures pass status and readable error text through the proxy where practical.