openapi: 3.0.1
info:
  title: Wondercraft Public API
  description: >-
    The Wondercraft Public API creates audio content - podcasts, audio ads,
    meditations, and audiobooks - from an AI-generated or user-supplied script.
    Generation is asynchronous: a create request returns a job_id, which is then
    polled for completion and an MP3 download URL. Voices and background music are
    referenced by IDs copied from the Wondercraft platform. API access requires a
    paid plan.
  termsOfService: https://www.wondercraft.ai/terms
  contact:
    name: Wondercraft Support
    url: https://support.wondercraft.ai/
  version: 0.0.1
servers:
  - url: https://api.wondercraft.ai/v1
security:
  - APIKeyHeader: []
paths:
  /podcast:
    post:
      operationId: generate_ai_scripted_episode_podcast_post
      tags:
        - Audio Generation
      summary: Create any audio content with an AI-generated script
      description: >-
        Generates audio content from a natural-language prompt. Wondercraft writes
        the script and synthesizes the audio. Optionally accepts voice IDs and a
        background music spec. Returns a job_id to poll for status.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateAiScriptedEpisodeRequest'
      responses:
        '200':
          description: Job accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateEpisodeResponse'
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Too many concurrent jobs (limit is 5).
  /podcast/scripted:
    post:
      operationId: generate_user_scripted_episode_podcast_scripted_post
      tags:
        - Audio Generation
      summary: Create any audio content with a user-provided script
      description: >-
        Generates audio from a user-provided script of ordered segments, each
        pairing text with a Wondercraft voice ID. Optionally accepts a background
        music spec. Returns a job_id to poll for status.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateUserScriptedEpisodeRequest'
      responses:
        '200':
          description: Job accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateEpisodeResponse'
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Too many concurrent jobs (limit is 5).
  /podcast/convo-mode/ai-scripted:
    post:
      operationId: generate_ai_scripted_convo_mode_episode_podcast_convo_mode_ai_scripted_post
      tags:
        - Convo Mode
      summary: Generate AI-scripted podcast with 2 hosts using Convo Mode
      description: >-
        Generates a two-host conversational podcast from a natural-language prompt.
        Requires exactly two voice IDs and accepts optional delivery instructions
        and a background music spec. Returns a job_id to poll for status.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateAiScriptedConvoModeEpisodeRequest'
      responses:
        '200':
          description: Job accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateEpisodeResponse'
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Too many concurrent jobs (limit is 5).
  /podcast/convo-mode/user-scripted:
    post:
      operationId: generate_user_scripted_convo_mode_episode_podcast_convo_mode_user_scripted_post
      tags:
        - Convo Mode
      summary: Generate podcast with 2 hosts using Convo Mode and a user-provided script
      description: >-
        Generates a two-host conversational podcast from a user-provided script of
        ordered segments. Accepts optional delivery instructions and a background
        music spec. Returns a job_id to poll for status.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateUserScriptedConvoModeEpisodeRequest'
      responses:
        '200':
          description: Job accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateEpisodeResponse'
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Too many concurrent jobs (limit is 5).
  /podcast/{job_id}:
    get:
      operationId: get_episode_status_podcast__job_id__get
      tags:
        - Jobs
      summary: Get audio content result and status
      description: >-
        Retrieves the status of an audio generation job. When finished, returns the
        generated script and an MP3 download URL. Errors are reported via the error
        and error_details fields.
      parameters:
        - name: job_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The job_id returned by a generate request.
      responses:
        '200':
          description: Job status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetEpisodeStatusResponse'
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /podcasts:
    get:
      operationId: get_podcasts_for_user_podcasts_get
      tags:
        - Jobs
      summary: Get podcasts for the authenticated user
      description: Returns the podcasts associated with the authenticated API key.
      responses:
        '200':
          description: List of podcasts for the user.
          content:
            application/json:
              schema:
                type: object
  /verify:
    get:
      operationId: verify_key_verify_get
      tags:
        - Account
      summary: Verify API key
      description: Verifies the supplied API key and returns the associated account email.
      responses:
        '200':
          description: Key is valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyResponse'
components:
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-KEY
  schemas:
    ScriptSegment:
      type: object
      additionalProperties: false
      required:
        - text
        - voice_id
      properties:
        text:
          type: string
          description: The text to be spoken for this part of the dialogue.
        voice_id:
          type: string
          description: A unique identifier for the voice, copied from the Wondercraft platform.
    MusicTrackSpec:
      type: object
      additionalProperties: false
      required:
        - music_id
      properties:
        music_id:
          type: string
          description: The ID of the music track to use in the background.
        fade_in_ms:
          type: integer
          default: 0
        fade_out_ms:
          type: integer
          default: 0
        playback_start:
          type: integer
          default: 0
        playback_end:
          type: integer
          nullable: true
        volume:
          type: number
          default: 0.05
        loop:
          type: boolean
          default: false
    GenerateAiScriptedEpisodeRequest:
      type: object
      required:
        - prompt
      properties:
        prompt:
          type: string
          description: Natural-language description of the audio content to generate.
        voice_ids:
          type: array
          items:
            type: string
          description: Optional Wondercraft voice IDs to use.
        music_spec:
          $ref: '#/components/schemas/MusicTrackSpec'
    GenerateUserScriptedEpisodeRequest:
      type: object
      required:
        - script
      properties:
        script:
          type: array
          items:
            $ref: '#/components/schemas/ScriptSegment'
          description: Ordered list of script segments.
        music_spec:
          $ref: '#/components/schemas/MusicTrackSpec'
    GenerateAiScriptedConvoModeEpisodeRequest:
      type: object
      required:
        - prompt
      properties:
        prompt:
          type: string
          description: Natural-language description of the conversation to generate.
        voice_ids:
          type: array
          items:
            type: string
          minItems: 2
          maxItems: 2
          description: Exactly two Wondercraft voice IDs, one per host.
        delivery_instructions:
          type: string
          description: Optional guidance on tone and delivery.
        music_spec:
          $ref: '#/components/schemas/MusicTrackSpec'
    GenerateUserScriptedConvoModeEpisodeRequest:
      type: object
      required:
        - script
      properties:
        script:
          type: array
          items:
            $ref: '#/components/schemas/ScriptSegment'
          description: Ordered list of script segments for the two hosts.
        delivery_instructions:
          type: string
          description: Optional guidance on tone and delivery.
        music_spec:
          $ref: '#/components/schemas/MusicTrackSpec'
    GenerateEpisodeResponse:
      type: object
      required:
        - job_id
      properties:
        job_id:
          type: string
          format: uuid
          description: Identifier used to poll job status.
    GetEpisodeStatusResponse:
      type: object
      required:
        - finished
      properties:
        finished:
          type: boolean
          description: Whether the job has completed.
        script:
          type: string
          description: The generated script, when available.
        url:
          type: string
          description: Download URL for the finished MP3, when available.
        error:
          type: boolean
          description: Whether the job failed.
        error_details:
          type: string
          description: Details about the failure, when present.
    VerifyResponse:
      type: object
      required:
        - status
        - email
      properties:
        status:
          type: string
          enum:
            - ok
        email:
          type: string
    ValidationError:
      type: object
      required:
        - loc
        - msg
        - type
      properties:
        loc:
          type: array
          items:
            type: string
        msg:
          type: string
        type:
          type: string
    HTTPValidationError:
      type: object
      properties:
        detail:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'