Wondercraft API

https://docs.wondercraft.ai/api-reference
Admin
The Wondercraft API allows users to create AI-generated audio content such as podcasts, audio ads,...
Tokens:8,980
Snippets:28
Trust Score:9.3
Update:11 months ago
Show doc for...
Tokens:
Raw
### POST /podcast

Source: https://docs.wondercraft.ai/api-reference/endpoint/user_scripted

Starts a background job to produce an audio file with the provided script segments. Requires a valid X-API-TOKEN header.

```APIDOC
## POST /podcast

### Description
Starts a background job to produce an audio file with the provided script segments. The response contains a `job_id` that can be used to query with the `/podcast/{job_id}` to query for status. Requires a valid `X-API-TOKEN` header.

### Method
POST

### Endpoint
/podcast

### Parameters
#### Query Parameters
- **script** (string) - Required - The script segments to be converted into audio.
- **voice_id** (string) - Required - The ID of the voice to be used for narration.
- **music_id** (string) - Optional - The ID of the background music to be included.

#### Headers
- **X-API-TOKEN** (string) - Required - Your API authentication token.

### Request Example
```json
{
  "script": [
    {"type": "text", "content": "Hello, welcome to Wondercraft AI."}, 
    {"type": "text", "content": "We create amazing audio content for you."} 
  ],
  "voice_id": "your_voice_id",
  "music_id": "your_music_id"
}
```

### Response
#### Success Response (200)
- **job_id** (string) - The ID of the background job started for audio production.

#### Response Example
```json
{
  "job_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
}
```

#### Error Handling
- **429** - Too many jobs in flight.
- **400** - Invalid `voice_id` or `music_id` provided.
```

--------------------------------

### POST /podcast

Source: https://docs.wondercraft.ai/api-reference/endpoint/generate_podcast

Creates an AI-generated script and produces an audio file. This endpoint starts a background job and returns a job ID that can be used to track the creation status. Requires authentication via X-API-TOKEN header.

```APIDOC
## POST /podcast

### Description
Starts a background job that creates an AI-generated script and produces an audio file. The response contains a job_id that can be used with the /podcast/{job_id} endpoint to query for status.

### Method
POST

### Endpoint
/podcast

### Authentication
- **X-API-TOKEN** (string) - Required - Valid API token for authentication

### Parameters
#### Request Body
- **voice_ids** (array of strings) - Required - List of unique voice identifiers for audio generation
- **music_ids** (array of strings) - Optional - List of music track identifiers to include in audio

### Request Example
{
  "voice_ids": ["voice_1", "voice_2"],
  "music_ids": ["music_track_1"]
}

### Response
#### Success Response (200)
- **job_id** (string) - Unique identifier for the background job that can be used to query status

#### Response Example
{
  "job_id": "job_abc123def456"
}

### Error Handling
#### 429 Too Many Requests
- Returned when the user has too many jobs in flight

#### 422 Unprocessable Entity
- Returned if provided voice_ids are not unique

#### 400 Bad Request
- Returned if any voice_ids or music_ids provided are invalid

### Related Endpoints
- **GET /podcast/{job_id}** - Query the status of a created job using the job_id from this endpoint's response
```

--------------------------------

### POST /podcast/convo

Source: https://docs.wondercraft.ai/api-reference/endpoint/convo_mode_user_scripted

Starts a background job to produce an audio file using a provided script in conversation mode with two hosts. Use the returned job_id to track the generation status.

```APIDOC
## POST /podcast/convo

### Description
Starts a background job to produce an audio file with the provided script segments in convo mode. The response contains a `job_id` that can be used to query with the `/podcast/{job_id}` to query for status. Requires a valid `X-API-TOKEN` header.

Note that generating via Convo Mode yields more natural results but takes longer. Expect at least 1 minute of processing per minute duration of audio before investigating a potential failure.

### Method
POST

### Endpoint
/podcast/convo

### Parameters
#### Header Parameters
- **X-API-TOKEN** (string) - Required - A valid API token for authentication.

#### Request Body
- **script** (object) - Required - The script segments for the podcast.
  - **segments** (array) - Required - An array of script segments.
    - **speaker** (string) - Required - The speaker identifier (e.g., 'host_1', 'host_2').
    - **text** (string) - Required - The text content for the segment.
- **voice_ids** (array) - Required - An array of two voice IDs for the hosts.
  - **voice_id** (string) - Required - The ID of the voice to use.

### Request Example
```json
{
  "script": {
    "segments": [
      {
        "speaker": "host_1",
        "text": "Hello and welcome to our podcast!"
      },
      {
        "speaker": "host_2",
        "text": "It's great to be here today."
      }
    ]
  },
  "voice_ids": [
    "voice_id_1",
    "voice_id_2"
  ]
}
```

### Response
#### Success Response (200)
- **job_id** (string) - The ID of the background job.

#### Response Example
```json
{
  "job_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
}
```

#### Error Responses
- **429** - Too Many Requests: The user has too many jobs in flight.
- **400** - Bad Request: Invalid `voice_ids` provided or the length of `voice_ids` is not 2.
```

--------------------------------

### GET /podcast/{job_id}

Source: https://docs.wondercraft.ai/api-reference/endpoint/get_job_status

Retrieves the status of a podcast generation job. If the job is successful, it returns a URL to download the generated podcast. This URL is valid for 24 hours.

```APIDOC
## GET /podcast/{job_id}

### Description
Gets the status of a podcast generation job, including a link to download it if the job was successful. Requires a valid `X-API-TOKEN` header. The link returned expires after 24 hours. You can call this endpoint again to get a fresh link without regenerating the podcast.

### Method
GET

### Endpoint
`/podcast/{job_id}`

### Parameters
#### Path Parameters
- **job_id** (string) - Required - The unique identifier for the podcast generation job (UUID format).

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **finished** (boolean) - Indicates whether the episode generation is complete.
- **script** (string | null) - The script that was used for generating the episode. Can be null.
- **url** (string | null) - A URL for downloading the generated episode. Can be null if an error occurred or the job is not finished.
- **error** (boolean | null) - Indicates whether an error occurred during episode generation. Can be null.

#### Response Example
```json
{
  "finished": true,
  "script": "<string>",
  "url": "<string>",
  "error": false
}
```

#### Error Response (404)
- **detail** (array) - An array of validation errors if the `job_id` is invalid or other validation issues occur.

#### Error Response Example
```json
{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}
```
```

--------------------------------

### Get Podcast Generation Status (OpenAPI)

Source: https://docs.wondercraft.ai/api-reference/endpoint/get_job_status

This OpenAPI definition describes the GET /podcast/{job_id} endpoint for retrieving the status of a podcast generation job. It specifies request parameters, authentication (X-API-TOKEN), and response schemas for success (200) and validation errors (422).

```yaml
GET /podcast/{job_id}
paths:
  path: /podcast/{job_id}
  method: get
  servers:
    - url: https://api.wondercraft.ai/v1
      description: Base Wondercraft API
  request:
    security:
      - title: APIKeyHeader
        parameters:
          query: {}
          header:
            X-API-KEY:
              type: apiKey
          cookie: {}
    parameters:
      path:
        job_id:
          schema:
            - type: string
              required: true
              title: Job Id
              format: uuid
      query: {}
      header: {}
      cookie: {}
    body: {}
  response:
    '200':
      application/json:
        schemaArray:
          - type: object
            properties:
              finished:
                allOf:
                  - type: boolean
                    title: Finished
                    description: Whether the episode generation is finished
              script:
                allOf:
                  - anyOf:
                      - type: string
                      - type: 'null'
                    title: Script
                    description: The script used for generating the episode
              url:
                allOf:
                  - anyOf:
                      - type: string
                      - type: 'null'
                    title: Url
                    description: A URL for downloading the episode
              error:
                allOf:
                  - anyOf:
                      - type: boolean
                      - type: 'null'
                    title: Error
                    description: Whether an error occurred while generating the episode
            title: GetEpisodeStatusResponse
            refIdentifier: '#/components/schemas/GetEpisodeStatusResponse'
            requiredProperties:
              - finished
            additionalProperties: false
        examples:
          example:
            value:
              finished: true
              script: <string>
              url: <string>
              error: true
        description: Successful Response
    '422':
      application/json:
        schemaArray:
          - type: object
            properties:
              detail:
                allOf:
                  - items:
                      $ref: '#/components/schemas/ValidationError'
                    type: array
                    title: Detail
            title: HTTPValidationError
            refIdentifier: '#/components/schemas/HTTPValidationError'
        examples:
          example:
            value:
              detail:
                - loc:
                    - <string>
                  msg: <string>
                  type: <string>
        description: Validation Error
  deprecated: false
  type: path
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError

```

--------------------------------

### MusicTrackSpec - Music Track Configuration

Source: https://docs.wondercraft.ai/api-reference/endpoint/generate_podcast

Schema for adding and configuring music tracks in generated audio. Allows specification of music ID, playback timing, and volume levels. Music is automatically positioned at the beginning of generated content and trimmed to match content length.

```APIDOC
## Music Track Configuration

### Description
Configures a music track to be added to generated audio content. The music track will be positioned at the very beginning of the generated podcast and automatically trimmed to match the content length.

### Schema: MusicTrackSpec

### Parameters

#### Required Fields
- **music_id** (string) - Required - The unique identifier of the music track to add

#### Optional Fields
- **track** (integer) - Optional - Track number selection. Defaults to 0
- **playback_start** (integer) - Optional - Millisecond position in the music track at which playback begins. Equivalent to trimming the beginning of the track. Defaults to 0 (no trimming)
- **playback_end** (integer | null) - Optional - Number of milliseconds into the music to playback. Equivalent to trimming from this point onward. Defaults to the entire music track duration
- **volume** (number) - Optional - Volume level to apply to the music track. Must be between 0.0 and 1.0. Defaults to 0.05

### Request Example
```json
{
  "music_id": "track_12345",
  "track": 0,
  "playback_start": 0,
  "playback_end": 30000,
  "volume": 0.05
}
```

### Response

#### Success Response
- **music_id** (string) - The unique identifier of the configured music track
- **track** (integer) - Track number that was selected
- **playback_start** (integer) - Millisecond position where playback begins
- **playback_end** (integer | null) - Millisecond position where playback ends
- **volume** (number) - Applied volume level (0.0 - 1.0)

### Constraints
- volume must be a decimal number between 0.0 and 1.0 inclusive
- playback_start must be a non-negative integer
- playback_end must be null or a positive integer
- music_id is required and must reference a valid music track
- Additional properties are not allowed
```

--------------------------------

### POST /podcast/scripted API Request (OpenAPI Specification)

Source: https://docs.wondercraft.ai/api-reference/endpoint/user_scripted

This OpenAPI specification defines the POST request for the `/podcast/scripted` endpoint. It details the request body, including the script segments and optional music specifications, and the structure of the successful response containing a job ID. It also specifies the authentication method using an API key.

```yaml
paths:
  path: /podcast/scripted
  method: post
  servers:
    - url: https://api.wondercraft.ai/v1
      description: Base Wondercraft API
  request:
    security:
      - title: APIKeyHeader
        parameters:
          query: {}
          header:
            X-API-KEY:
              type: apiKey
          cookie: {}
    parameters: {}
    body:
      application/json:
        schemaArray:
          - type: object
            properties:
              script:
                allOf:
                  - items:
                      $ref: '#/components/schemas/ScriptSegment'
                    type: array
                    title: Script
                    description: The segments forming the script for the episode
              music_spec:
                allOf:
                  - anyOf:
                      - $ref: '#/components/schemas/MusicTrackSpec'
                      - type: 'null'
                    description: >-
                      An optional spec for adding background music to the
                      generated script. Note that if the chosenmusic track is
                      longer than the duration of the generated script, it will
                      be cut off.
            required: true
            title: GenerateUserScriptedEpisodeRequest
            description: >-
              A request to start a job to generate audio content with a provided
              script.
            refIdentifier: '#/components/schemas/GenerateUserScriptedEpisodeRequest'
            requiredProperties:
              - script
            additionalProperties: false
        examples:
          example:
            value:
              script:
                - text: <string>
                  voice_id: <string>
              music_spec:
                music_id: <string>
                fade_in_ms: 0
                fade_out_ms: 0
                playback_start: 0
                playback_end: 123
                volume: 0.05
  response:
    '200':
      application/json:
        schemaArray:
          - type: object
            properties:
              job_id:
                allOf:
                  - type: string
                    format: uuid
                    title: Job Id
                    description: >-
                      The job ID for the episode generation. The status of this
                      job can be queried using the`/podcast/{job_id}` endpoint.
            title: GenerateEpisodeResponse
            refIdentifier: '#/components/schemas/GenerateEpisodeResponse'
            requiredProperties:
              - job_id
            additionalProperties: false
        examples:
          example:
            value:
              job_id: 3c90c3cc-0d44-4b50-8888-8dd25736052a
        description: Successful Response
    '422':
      application/json:
        schemaArray:
          - type: object
            properties:
              detail:
                allOf:
                  - items:
                      $ref: '#/components/schemas/ValidationError'
                    type: array
                    title: Detail
            title: HTTPValidationError
            refIdentifier: '#/components/schemas/HTTPValidationError'
        examples:
          example:
            value:
              detail:
                - loc:
                    - <string>
                  msg: <string>
                  type: <string>
        description: Validation Error
  deprecated: false
  type: path
components:
  schemas:
    MusicTrackSpec:
      properties:
        music_id:
          type: string
          title: Music Id
          description: >-
            The ID of the music track to used in the background. This can be
            copied from theWondercraft platform
        fade_in_ms:
          type: integer
          title: Fade In Ms
          description: >-
            The number of milliseconds to fade in from the start of the music
            track
          default: 0
        fade_out_ms:
          type: integer
          title: Fade Out Ms
          description: >-
            The number of milliseconds to fade out from the end of the music
            track
          default: 0
        playback_start:
          type: integer
          title: Playback Start
          description: >-
            A millisecond into the music track at which we start playing.
            Equivalent to trimming thebeginning of the music track. Defaults to
            0 (i.e. no trimming)
          default: 0
        playback_end:
          anyOf:
            - type: integer
            - type: 'null'
          title: Playback End
          description: >-
            How many milliseconds into the music should we playback. Equivalent
            to trimming up to this numberof milliseconds from the music track.
            Defaults to the entire music track.
        volume:

```

--------------------------------

### POST /podcast

Source: https://docs.wondercraft.ai/api-reference/endpoint/generate_podcast

Generates an AI-scripted podcast episode. You can provide a prompt, specify voice IDs for the speakers, and optionally include background music.

```APIDOC
## POST /podcast

### Description
This endpoint initiates a job to generate an audio file for a podcast episode with an AI-generated script. You can customize the output by providing a detailed prompt, specifying voice IDs for up to two speakers, and adding background music with adjustable fade-in/out times and volume.

### Method
POST

### Endpoint
https://api.wondercraft.ai/v1/podcast

### Parameters
#### Query Parameters
None

#### Header Parameters
- **X-API-KEY** (apiKey) - Required - Your Wondercraft API key

#### Request Body
- **prompt** (string) - Required - The prompt for the episode, can include links.
- **voice_ids** (array[string]) - Optional - A list of voice_ids to use for the generated audio. If the script has multiple speakers, voices are used in the order they appear. All IDs must be unique. If not provided, up to 2 default voices will be used.
- **music_spec** (object | null) - Optional - An optional specification for adding background music. If the music track is longer than the script, it will be cut off.
  - **music_id** (string) - Required - The ID of the music track.
  - **fade_in_ms** (integer) - Optional - The number of milliseconds to fade in from the start of the music track. Defaults to 0.
  - **fade_out_ms** (integer) - Optional - The number of milliseconds to fade out from the end of the music track. Defaults to 0.
  - **playback_start** (integer) - Optional - The start time in milliseconds for music playback.
  - **playback_end** (integer) - Optional - The end time in milliseconds for music playback.
  - **volume** (number) - Optional - The volume level for the background music. Defaults to 0.05.

### Request Example
```json
{
  "prompt": "Create a podcast episode about the future of AI research.",
  "voice_ids": [
    "voice-123",
    "voice-456"
  ],
  "music_spec": {
    "music_id": "music-789",
    "fade_in_ms": 1000,
    "fade_out_ms": 1500,
    "playback_start": 0,
    "playback_end": 300000,
    "volume": 0.1
  }
}
```

### Response
#### Success Response (200)
- **job_id** (string) - The job ID for the episode generation. You can check the status of this job using the `/podcast/{job_id}` endpoint.

#### Response Example
```json
{
  "job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
```

#### Error Response (422)
- **detail** (array[object]) - Contains details about validation errors.
  - **loc** (array[string]) - Location of the error in the request.
  - **msg** (string) - The error message.
  - **type** (string) - The type of error.

#### Error Response Example
```json
{
  "detail": [
    {
      "loc": ["body", "prompt"],
      "msg": "Field required",
      "type": "value_error.missing"
    }
  ]
}
```
```

--------------------------------

### POST /podcast/scripted

Source: https://docs.wondercraft.ai/api-reference/endpoint/user_scripted

Generates an audio podcast episode based on a provided script and optional background music.

```APIDOC
## POST /podcast/scripted

### Description
This endpoint initiates a job to generate audio content for a podcast episode using a user-provided script. It also allows for the inclusion of background music with customizable fade effects and playback ranges.

### Method
POST

### Endpoint
https://api.wondercraft.ai/v1/podcast/scripted

### Parameters
#### Query Parameters
None

#### Header Parameters
- **X-API-KEY** (apiKey) - Required - Your Wondercraft API key for authentication.

#### Request Body
- **script** (array[object]) - Required - The segments forming the script for the episode.
  - **text** (string) - The spoken text for a segment.
  - **voice_id** (string) - The ID of the voice to use for the segment.
- **music_spec** (object | null) - Optional - Specifies background music for the episode.
  - **music_id** (string) - Required - The ID of the music track.
  - **fade_in_ms** (integer) - Optional - Milliseconds to fade in music at the start (default: 0).
  - **fade_out_ms** (integer) - Optional - Milliseconds to fade out music at the end (default: 0).
  - **playback_start** (integer) - Optional - Milliseconds into the track to start playback (default: 0).
  - **playback_end** (integer | null) - Optional - Milliseconds into the track to end playback.
  - **volume** (number) - Optional - Volume level for the background music (e.g., 0.05).

### Request Example
```json
{
  "script": [
    {
      "text": "<string>",
      "voice_id": "<string>"
    }
  ],
  "music_spec": {
    "music_id": "<string>",
    "fade_in_ms": 0,
    "fade_out_ms": 0,
    "playback_start": 0,
    "playback_end": 123,
    "volume": 0.05
  }
}
```

### Response
#### Success Response (200)
- **job_id** (string, uuid) - The job ID for the episode generation. This ID can be used to query the status of the job via the `/podcast/{job_id}` endpoint.

#### Response Example
```json
{
  "job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
```

#### Error Response (422)
- **detail** (array[object]) - Contains validation error details.
  - **loc** (array[string]) - Location of the validation error.
  - **msg** (string) - Error message.
  - **type** (string) - Error type.

#### Error Response Example
```json
{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}
```
```

--------------------------------

### Data Models

Source: https://docs.wondercraft.ai/api-reference/endpoint/user_scripted

Defines the structure for MusicTrackSpec, ScriptSegment, and ValidationError used within the Wondercraft AI API.

```APIDOC
## Data Models

### MusicTrackSpec

**Description**: A music track to add to the generated audio. The music will always be added at the very beginning of the generated podcast and will be automatically trimmed to match the content length.

**Properties**:
- **music_id** (string) - Required - The unique identifier for the music track.
- **volume** (number) - Optional - The volume to apply to the music track. Defaults to 0.05. Must be between 0.0 and 1.0.

### ScriptSegment

**Description**: A single unit of speech in the script defined by the user.

**Properties**:
- **text** (string) - Required - The text to be spoken for this part of the dialogue.
- **voice_id** (string) - Required - A unique identifier for the voice copied from the Wondercraft Platform to use for the speaker of this segment.

### ValidationError

**Description**: Represents a validation error returned by the API.

**Properties**:
- **loc** (array) - Required - The location of the error in the request.
- **msg** (string) - Required - The error message.
- **type** (string) - Required - The type of the error.
```

--------------------------------

### POST /podcast/convo-mode/ai-scripted

Source: https://docs.wondercraft.ai/api-reference/endpoint/convo_mode_ai_scripted

Generates an AI-scripted podcast episode in convo mode. This endpoint takes a prompt to instruct the AI, an optional list of voice IDs for the hosts, and optional delivery instructions for the audio. It returns a job ID to track the generation process.

```APIDOC
## POST /podcast/convo-mode/ai-scripted

### Description
This endpoint initiates the generation of an AI-scripted podcast episode in conversation mode. It utilizes a provided prompt to guide the AI in creating the script, allows for the specification of voice IDs for the hosts (requiring exactly two unique IDs, or defaults will be used), and accepts optional delivery instructions for audio generation.

### Method
POST

### Endpoint
https://api.wondercraft.ai/v1/podcast/convo-mode/ai-scripted

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Header Parameters
- **X-API-KEY** (apiKey) - Required - Your Wondercraft API key.

#### Request Body
- **prompt** (string) - Required - The prompt to instruct the AI to generate the script. You can specify the duration, and include links. Sometimes, the AI hallucinates, so it helps to mention that this podcast has two hosts.
- **voice_ids** (array of string) - Optional - A list of voice_ids to use for the generated audio. Must provide exactly 2 voices for this endpoint. If the script has multiple speakers, we will use the voices from this list in the order they appear in. All ids in this list must be unique. If no IDs are provided, 2 defaults will be used.
- **delivery_instructions** (string or null) - Optional - An optional delivery instructions for the generated audio. This will be used to guide the generation of the audio.
- **music_spec** (object or null) - Optional - An optional spec for adding background music to the generated script. Note that if the chosen music track is longer than the duration of the generated script, it will be cut off.
  - **music_id** (string) - Required - The ID of the music track.
  - **fade_in_ms** (integer) - Optional - The fade-in duration in milliseconds.
  - **fade_out_ms** (integer) - Optional - The fade-out duration in milliseconds.
  - **playback_start** (integer) - Optional - The start time in milliseconds for playback.
  - **playback_end** (integer) - Optional - The end time in milliseconds for playback.
  - **volume** (number) - Optional - The volume level for the music.

### Request Example
```json
{
  "prompt": "Generate a podcast script about the future of AI, lasting 10 minutes, with two hosts. Include a mention of the recent advancements in large language models.",
  "voice_ids": [
    "voice_id_1",
    "voice_id_2"
  ],
  "delivery_instructions": "Ensure a conversational tone between the hosts.",
  "music_spec": {
    "music_id": "music_track_abc",
    "fade_in_ms": 1000,
    "fade_out_ms": 2000,
    "playback_start": 5000,
    "playback_end": 30000,
    "volume": 0.05
  }
}
```

### Response
#### Success Response (200)
- **job_id** (string, uuid) - The job ID for the episode generation. The status of this job can be queried using the `/podcast/{job_id}` endpoint.

#### Response Example
```json
{
  "job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
```

#### Error Response (422)
- **detail** (array of ValidationError) - A list of validation errors.
  - **loc** (array of string or integer) - The location of the error in the request.
  - **msg** (string) - The error message.
  - **type** (string) - The type of error.

#### Error Response Example
```json
{
  "detail": [
    {
      "loc": [
        "body",
        "voice_ids"
      ],
      "msg": "Must provide exactly 2 voice IDs.",
      "type": "value_error"
    }
  ]
}
```
```

--------------------------------

### POST /podcast/convo

Source: https://docs.wondercraft.ai/api-reference/endpoint/convo_mode_ai_scripted

Initiates a background job to generate an AI-scripted podcast using Convo Mode. The response includes a job ID for status tracking.

```APIDOC
## POST /podcast/convo

### Description
Starts a background job that creates an AI generated script and produces an audio file in convo mode. The response contains a `job_id` that can be used with the `/podcast/{job_id}` endpoint to query for status. Requires a valid `X-API-TOKEN` header.

**Note that generating via Convo Mode yields more natural results but takes longer. Expect at least 1 minute of processing per minute duration of audio before investigating a potential failure.**

### Method
POST

### Endpoint
/podcast/convo

### Parameters
#### Headers
- **X-API-TOKEN** (string) - Required - A valid API token for authentication.

#### Query Parameters
- **voice_ids** (array of strings) - Required - A list of two valid voice IDs for the podcast hosts.
- **script_content** (string) - Required - The content of the script to be used for audio generation.
- **duration_minutes** (integer) - Required - The desired duration of the podcast in minutes.

#### Request Body
*(No specific request body schema provided, assuming parameters are passed via query or form data based on typical REST patterns for job initiation)*

### Request Example
*(Example assumes query parameters for simplicity)*
```
POST /podcast/convo?voice_ids=voice_id_1,voice_id_2&script_content=Your%20podcast%20script%20here.&duration_minutes=5

--header "X-API-TOKEN: YOUR_API_TOKEN"
```

### Response
#### Success Response (200)
- **job_id** (string) - The unique identifier for the generated job.

#### Response Example
```json
{
  "job_id": "abc123xyz789"
}
```

#### Error Responses
- **429 Too Many Requests**: If the user has too many jobs in flight.
- **400 Bad Request**: If any voice_ids provided are invalid or if the length of voice_ids is not 2.
```

--------------------------------

### POST /podcast/convo-mode/user-scripted

Source: https://docs.wondercraft.ai/api-reference/endpoint/convo_mode_user_scripted

Initiates a job to generate an audio file for a podcast in conversation mode, using a user-provided script. It allows for optional delivery instructions and background music specifications.

```APIDOC
## POST /podcast/convo-mode/user-scripted

### Description
This endpoint starts a job to generate an audio file for a podcast in convo mode with a script provided by the user. You can optionally specify delivery instructions and background music.

### Method
POST

### Endpoint
https://api.wondercraft.ai/v1/podcast/convo-mode/user-scripted

### Parameters
#### Header Parameters
- **X-API-KEY** (apiKey) - Required - Your Wondercraft API key.

#### Request Body
- **script** (array) - Required - An array of script segments, each containing 'text' and 'voice_id'.
- **delivery_instructions** (string | null) - Optional - Instructions for audio generation.
- **music_spec** (object | null) - Optional - Specification for background music.
  - **music_id** (string) - Required - The ID of the music track.
  - **fade_in_ms** (integer) - Optional - Fade-in duration in milliseconds (default: 0).
  - **fade_out_ms** (integer) - Optional - Fade-out duration in milliseconds (default: 0).
  - **playback_start** (integer) - Optional - Start time for music playback.
  - **playback_end** (integer) - Optional - End time for music playback.
  - **volume** (number) - Optional - Volume level for the music.

### Request Example
```json
{
  "script": [
    {
      "text": "<string>",
      "voice_id": "<string>"
    }
  ],
  "delivery_instructions": "<string>",
  "music_spec": {
    "music_id": "<string>",
    "fade_in_ms": 0,
    "fade_out_ms": 0,
    "playback_start": 0,
    "playback_end": 123,
    "volume": 0.05
  }
}
```

### Response
#### Success Response (200)
- **job_id** (string) - The job ID for the episode generation. This can be used to query the job status.

#### Response Example
```json
{
  "job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
```

#### Error Response (422)
- **detail** (array) - Contains validation error details.
  - **loc** (array) - Location of the error.
  - **msg** (string) - Error message.
  - **type** (string) - Error type.

#### Error Response Example
```json
{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}
```
```

--------------------------------

### ValidationError - Error Response Schema

Source: https://docs.wondercraft.ai/api-reference/endpoint/generate_podcast

Standard error response schema returned when validation fails. Contains location information, error message, and error type classification for debugging API requests.

```APIDOC
## ValidationError

### Description
Error response schema returned when request validation fails. Provides detailed information about what validation failed and where in the request the error occurred.

### Schema: ValidationError

### Response Fields

#### Required Fields
- **loc** (array) - Required - Location of the error in the request. Array of strings and/or integers indicating the path to the field that failed validation
- **msg** (string) - Required - Human-readable error message describing the validation failure
- **type** (string) - Required - Error type classification indicating the category of validation error

### Response Example
```json
{
  "loc": [
    "body",
    "music_id"
  ],
  "msg": "field required",
  "type": "value_error.missing"
}
```

### Error Location Format
- First element typically indicates the source: "body", "query", "path", etc.
- Subsequent elements indicate the nested field path
- Integers in the array represent array indices

### Common Error Types
- value_error.missing - Required field is missing
- type_error.integer - Expected integer value
- type_error.number - Expected number value
- value_error.number.not_le - Number exceeds maximum allowed value
- value_error.number.not_ge - Number below minimum allowed value
```
Tokens:
Raw