Generates two-host conversational podcasts from either an AI prompt or a user-provided script, taking exactly two voice IDs plus optional delivery instructions and a background music spec.
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'