fulcrum: "1.0"
name: audio_tts
description: >
  Convert text to natural-sounding speech using OpenAI TTS API.
  Returns base64-encoded MP3 audio data. Supports 6 voices and 2 models.
  Ideal for voice responses, accessibility, and audio content generation.

schema:
  input:
    type: object
    properties:
      text:
        type: string
        description: >
          Text to convert to speech. Maximum 4096 characters.
          Supports SSML-style emphasis through punctuation.
        examples:
          - "Hello! How can I help you today?"
      voice:
        type: string
        description: >
          Voice to use for synthesis. Each voice has a distinct character:
          alloy (neutral), echo (male), fable (British), onyx (deep),
          nova (female), shimmer (warm).
        enum: [alloy, echo, fable, onyx, nova, shimmer]
        default: nova
      model:
        type: string
        description: >
          TTS model. tts-1 is faster and cheaper; tts-1-hd produces
          higher quality output with less compression artifacts.
        enum: [tts-1, tts-1-hd]
        default: tts-1
      speed:
        type: number
        description: Speech speed multiplier (0.25=very slow, 1.0=normal, 4.0=very fast)
        default: 1.0
        minimum: 0.25
        maximum: 4.0
      response_format:
        type: string
        description: Audio output format
        enum: [mp3, opus, aac, flac, wav, pcm]
        default: mp3
    required:
      - text
  output:
    type: object
    properties:
      data:
        type: string
        description: Base64-encoded audio data
      mime_type:
        type: string
        description: Audio MIME type (e.g., "audio/mpeg" for MP3)
      size:
        type: integer
        description: Audio data size in bytes

providers:
  primary:
    service: rest
    cost_per_call: 0.015
    timeout: 30
    config:
      base_url: https://api.openai.com
      path: /v1/audio/speech
      method: POST
      response_format: binary
      headers:
        Authorization: "Bearer {env.OPENAI_API_KEY}"
        Content-Type: "application/json"
      body:
        model: "{model}"
        input: "{text}"
        voice: "{voice}"
        speed: "{speed}"
        response_format: "{response_format}"

auth:
  required: true
  type: bearer
  key: "env:OPENAI_API_KEY"
  description: >
    Requires an OpenAI API key with audio access.
    Set OPENAI_API_KEY environment variable.
    Pricing: $0.015/1K chars (tts-1), $0.030/1K chars (tts-1-hd).

cache:
  strategy: exact
  ttl: 86400

metadata:
  category: media
  tags:
    - audio
    - text-to-speech
    - tts
    - voice
    - synthesis
    - openai
  cost_category: cheap
  execution_time: fast
  read_only: true
  produces:
    - audioData
  consumes:
    - text
  chains_with:
    - audio_transcribe
  docs: https://platform.openai.com/docs/api-reference/audio/createSpeech
