### Python Setup

Source: https://docs.audiostack.ai/recipes/beta-building-longform-audio-with-the-story-endpoint-getting-ai-recommended-one-shot-sound-effects

Basic Python setup for using the AudioStack library.

```python
from audiostream import AudioStream

audio = AudioStream(api_key="YOUR_API_KEY")
```

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

### Create a script

Source: https://docs.audiostack.ai/reference

Creates a new audio project with a specified script and module. This is useful for getting started and debugging API key authentication.

```APIDOC
## POST /content/script

### Description
Creates a new audio project with a specified script and module.

### Method
POST

### Endpoint
https://v2.api.audio/content/script

### Parameters
#### Request Body
- **projectName** (string) - Required - The name of the project.
- **moduleName** (string) - Required - The name of the module within the project.
- **scriptName** (string) - Required - The name of the script.
- **scriptText** (string) - Required - The text content of the script.

### Request Example
{
  "projectName": "myFirstAudioProject",
  "moduleName": "admodule",
  "scriptName": "script1",
  "scriptText": "Got my first script created!"
}

### Response
#### Success Response (200)
- **message** (string) - Description of the success.
- **id** (string) - The ID of the created script.
```

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

### Request to build an Audioform

Source: https://docs.audiostack.ai/reference/process_request__post

This endpoint validates the audioform and then starts building it in the background. If the audioform is valid enough to warrant starting a background job, it will return a `202` status code with the `audioformID`. Call then the GET endpoint with the `audioformID` to get the result of the build.

```APIDOC
## POST /audioforms/

### Description
This endpoint validates the audioform and then starts building it in the background. If the audioform is valid enough to warrant starting a background job, it will return a `202` status code with the `audioformID`. Call then the GET endpoint with the `audioformID` to get the result of the build.

### Method
POST

### Endpoint
/audioforms/

### Parameters
#### Request Body
- **audioform** (object) - Required - The audioform object to be validated and built.

### Request Example
{
  "audioform": {
    "audioform": "string"
  }
}

### Response
#### Success Response (202)
- **audioformID** (string) - The ID of the audioform that has been accepted for building.

#### Response Example
{
  "audioformID": "string"
}

#### Error Response (400)
- **metadata** (object) - Metadata about the response.
- **warnings** (array) - A list of warnings associated with the request.
- **message** (string) - A message describing the error.
- **errors** (array) - A list of specific errors encountered.

#### Error Response (422)
- **metadata** (object) - Metadata about the response.
- **warnings** (array) - A list of warnings associated with the request.
- **message** (string) - A message describing the validation error.
- **errors** (array) - A list of specific validation errors encountered.
```

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

### Get Batch Batches Example

Source: https://docs.audiostack.ai/reference/get_batch_batches__batch_id__get

This example demonstrates how to retrieve details for a specific batch ID. Ensure you have the correct batch ID from a previous batch creation request.

```shell
curl -X GET \
  http://localhost:8000/v1/batch/batches/a1b2c3d4-e5f6-7890-1234-567890abcdef \
  -H 'accept: application/json'
```

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

### Create an Ad Instantly with AI

Source: https://docs.audiostack.ai/recipes

This recipe demonstrates how to create an ad by calling the creator brief endpoint with a product name and description. It includes setup for API key, imports, and the JSON payload for the brief.

```Python
import requests
```

```Python
import json
```

```Python
from time import sleep
```

```Python

```

```Python
API_KEY = "Your API key"
```

```Python

```

```Python
brief = {
```

```Python
    "script": {
```

```Python
        "productName": "AudioStack AI Ad Builder",
```

```Python
        "productDescription": "Instantly create professional, broadcast-ready ads with AudioStack's AI ad building API. Just provide a product name and description, and we'll handle the rest.",
```

```Python
    }
```

```Python
}
```

```Python

```

```Python
print(f"Calling the brief endpoint with the following brief:")
```

```Python
print(json.dumps(brief, indent=4))
```

```Python

```

```Python
post_brief_response = requests.post(
```

```Python
    url="https://v2.api.audio/creator/brief",
```

```Python
    json={ 
```

```Python
        "audioformVersion": "2",
```

```Python
        "brief": brief,
```

```Python
        "numAds": 1,
```

```Python
    },
```

```Python
    headers={"x-api-key": API_KEY},
```

```Python
)
```

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

### Get Usage Analytics

Source: https://docs.audiostack.ai/openapi/audiostack-api.json

Retrieves usage information between the specified start and end dates inclusive.

```APIDOC
## GET /analytics/usage

### Description
Returns usage information between the specified start and end dates inclusive. 
Usage metrics are:

  - Total number of audioforms created
  - Total seconds of production audio created

  Both dates must be valid and not in the future. The end date must be equal to or after the start date.

### Method
GET

### Endpoint
/analytics/usage

### Parameters
#### Query Parameters
- **dateFrom** (string) - Required - Start date for the usage report (YYYY-MM-DD). Must not be in the future.
- **dateTo** (string) - Required - End date for the usage report (YYYY-MM-DD). Must be equal to or after dateFrom.

### Response
#### Success Response (200)
- **audioformsCreated** (integer) - Description
- **productionSeconds** (integer) - Description

#### Response Example
{
  "audioformsCreated": 0,
  "productionSeconds": 0
}
```

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

### Python SDK Authentication

Source: https://docs.audiostack.ai/reference/authentication

Example of how to set your API key using the Python SDK. It's recommended to load your API key from environment variables.

```APIDOC
## Python SDK Authentication

### Description
Example of how to set your API key using the Python SDK. It's recommended to load your API key from environment variables.

### Code
```python
import audiostack
import os

audiostack.api_key = os.environ["AUDIO_STACK_DEV_KEY"]
```
```

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

### Get Usage in a Date Range

Source: https://docs.audiostack.ai/reference/getanalyticsusage

Returns usage information between the specified start and end dates inclusive. Both dates must be valid and not in the future. The end date must be equal to or after the start date.

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Audiostack API",
    "description": "Documentation for the Audiostack API - the infrastructure for audio",
    "version": "v2",
    "termsOfService": "https://audiostack.ai/en/legal/terms-of-service",
    "contact": {
      "email": "support@audiostack.ai"
    }
  },
  "servers": [
    {
      "url": "https://v2.api.audio",
      "description": "Production server"
    },
    {
      "url": "https://staging-v2.api.audio",
      "description": "Staging server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/analytics/usage": {
      "get": {
        "tags": [
          "Analytics"
        ],
        "summary": "Get usage in a date range",
        "description": "Returns usage information between the specified start and end dates inclusive. \nUsage metrics are:\n\n  - Total number of audioforms created\n  - Total seconds of production audio created\n\n  Both dates must be valid and not in the future. The end date must be equal to or after the start date.\n",
        "operationId": "getAnalyticsUsage",
        "parameters": [
          {
            "name": "dateFrom",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Start date for the usage report (YYYY-MM-DD). Must not be in the future.",
              "example": "2026-01-25"
            }
          },
          {
            "name": "dateTo",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "End date for the usage report (YYYY-MM-DD). Must be equal to or after dateFrom. Must not be in the future.",
              "example": "2026-01-26"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Events usage report generated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnalyticsUsageResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation error - invalid date, date in future, or date_to must be after date_from",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnalyticsValidationError"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    },
    "schemas": {
      "AnalyticsUsageResponse": {
        "type": "object",
        "properties": {
          "metadata": {
            "type": "object",
            "properties": {
              "request_id": {
                "type": "string",
                "description": "Unique identifier for the request"
              },
              "version": {
                "type": "string",
                "description": "API version"
              },
              "credit_used": {
                "type": "number",
                "description": "Credits used for this request"
              },
              "credits_remaining": {
                "type": "number",
                "description": "Credits remaining"
              }
            }
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "default": []
          },
          "message": {
            "type": "string",
            "description": "Success message",
            "example": "Events usage report generated successfully."
          },
          "data": {
            "type": "object",
            "properties": {
              "totalUsage": {
                "type": "object",
                "properties": {
                  "productionSecondsCreated": {
                    "type": "number",
                    "description": "Total seconds of production audio created in the date range"
                  },
                  "audioformsCreated": {
                    "type": "number",
                    "description": "Total number of audioforms created in the date range"
                  }
                }
              }
            }
          }
        }
      },
      "AnalyticsValidationError": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "description": "Error message"
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "field": {
                  "type": "string",
                  "description": "Field that caused the error"
                },
                "message": {
                  "type": "string",
                  "description": "Error message for the field"
                }
              }
            }
          }
        }
      }
    }
  }
}
```

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

### Create Brief from File

Source: https://docs.audiostack.ai/openapi/audiostack-api.json

Creates an audio ad from a previously uploaded brief file. This endpoint is useful for reusing existing brief structures.

```APIDOC
## POST /v1/briefs/file

### Description
Creates an audio ad from a previously uploaded brief file. This endpoint is useful for reusing existing brief structures.

### Method
POST

### Endpoint
/v1/briefs/file

### Parameters
#### Request Body
- **fileId** (string) - Required - A file ID of a valid uploaded brief.
- **numAds** (integer) - Optional - Number of audio ads to generate. Minimum 1, maximum 5. Defaults to 3.

### Request Example
```json
{
  "fileId": "123e4567-e89b-12d3-a456-426614174000",
  "numAds": 1
}
```

### Response
#### Success Response (200)
- **data** (array) - An array of response data objects for each generated ad.
  - **statusCode** (integer) - Status of the rendering of the audioform (200 - completed, 202 - in progress).
  - **audioformId** (string) - UUID of the generated audioform.
  - **audioform** (object) - The generated audioform details.
  - **details** (object) - Details for the script and voices used in the ad.
    - **script** (object) - Script details.
      - **tone** (array) - Tone descriptors for the script.
      - **messages** (array) - Explanatory messages about the script.
    - **voices** (array) - Explanations for each voice used in the ad.
      - **voice_reference** (string) - Reference to the voice asset.
      - **tone** (array) - Descriptions of the tone with which the voice speaks.
      - **messages** (array) - Explanatory messages about the voice.

#### Response Example
```json
{
  "data": [
    {
      "statusCode": 202,
      "audioformId": "123e4567-e89b-12d3-a456-426614174000",
      "audioform": {},
      "details": {
        "script": {
          "tone": ["informative"],
          "messages": []
        },
        "voices": [
          {
            "voice_reference": "voice_for_ad",
            "tone": ["informative", "friendly", "engaging"],
            "messages": []
          }
        ]
      }
    }
  ]
}
```
```

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

### POST /audioforms/

Source: https://docs.audiostack.ai/openapi/audiostack-api.json

Initiates the building of an Audioform. This endpoint validates the provided audioform configuration and, if valid, starts a background job for its creation, returning a 202 Accepted status with an audioformID. You can then use this ID to retrieve the build status and result.

```APIDOC
## POST /audioforms/

### Description
Requests to build an Audioform. This endpoint validates the audioform and starts building it in the background. If the audioform is valid enough to start a background job, it returns a `202` status code with the `audioformID`. You can then call the GET endpoint with the `audioformID` to get the result of the build.

### Method
POST

### Endpoint
/audioforms/

### Request Body
- **PostRequestSchema** - Required - Schema for the audioform request.

### Responses
#### Success Response (202)
- **PostSuccessResponse** - Accepted status with audioformID.

#### Error Response (400)
- **EndpointErrorResponse** - Generally error message will be of this format.

#### Error Response (422)
- **ValidationErrorResponse** - Validation error.
```

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

### Get usage in a date range

Source: https://docs.audiostack.ai/reference/getanalyticsusage

Returns usage information between the specified start and end dates inclusive. Usage metrics include the total number of audioforms created and total seconds of production audio created. Both dates must be valid and not in the future, with the end date being equal to or after the start date.

```APIDOC
## GET /analytics/usage

### Description
Returns usage information between the specified start and end dates inclusive. 
Usage metrics are:

  - Total number of audioforms created
  - Total seconds of production audio created

  Both dates must be valid and not in the future. The end date must be equal to or after the start date.

### Method
GET

### Endpoint
/analytics/usage

### Parameters
#### Query Parameters
- **dateFrom** (string) - Required - Start date for the usage report (YYYY-MM-DD). Must not be in the future.
- **dateTo** (string) - Required - End date for the usage report (YYYY-MM-DD). Must be equal to or after dateFrom. Must not be in the future.

### Response
#### Success Response (200)
- **metadata** (object) - Request metadata including request_id, version, credit_used, and credits_remaining.
- **warnings** (array) - An array of warning strings.
- **message** (string) - Success message.
- **data** (object) - Contains the usage data.
  - **totalUsage** (object) - Aggregated usage metrics.
    - **productionSecondsCreated** (number) - Total seconds of production audio created in the date range.
    - **audioformsCreated** (number) - Total number of audioforms created in the date range.

#### Response Example
{
  "example": "{\n  \"metadata\": {\n    \"request_id\": \"req_12345\",\n    \"version\": \"v2\",\n    \"credit_used\": 1,\n    \"credits_remaining\": 99\n  },\n  \"warnings\": [],\n  \"message\": \"Events usage report generated successfully.\",\n  \"data\": {\n    \"totalUsage\": {\n      \"productionSecondsCreated\": 120.5,\n      \"audioformsCreated\": 10\n    }\n  }\n}"
}

#### Error Response (422)
- **error** (object) - Contains details about the validation error.
  - **code** (string) - Error code.
  - **message** (string) - Error message describing the validation failure.

#### Error Response Example
{
  "example": "{\n  \"error\": {\n    \"code\": \"VALIDATION_ERROR\",\n    \"message\": \"date_to must be after date_from\"\n  }\n}"
}
```

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

### Process Request POST

Source: https://docs.audiostack.ai/reference/process_request__post

Initiates an audio production process with specified parameters.

```APIDOC
## POST /websites/audiostack_ai/process

### Description
This endpoint processes a request to generate an audio production. It takes a detailed production configuration including arrangement, mixing presets, and specific section details with layers, sound templates, and effects.

### Method
POST

### Endpoint
/websites/audiostack_ai/process

### Parameters
#### Request Body
- **production** (object) - Required - Defines the overall production settings.
  - **arrangement** (object) - Required - Specifies the structure and content of the audio production.
  - **mixingPreset** (string) - Required - The mixing preset to be used for the production. Possible values: `balanced`, `voiceenhanced`, `musicenhanced`.
- **sections** (array) - Optional - An array of section objects defining different parts of the audio production.
  - **layers** (array) - Required - Contains clips that play together to form the audio for the section.
    - **type** (string) - Required - Type of the layer, e.g., `audioform`.
    - **assetRef** (string) - Required - Reference to the audio asset.
    - **duration** (number) - Optional - Duration of the clip in seconds.
    - **startOffset** (number) - Optional - Start offset of the clip in seconds.
    - **endOffset** (number) - Optional - End offset of the clip in seconds.
    - **reverse** (boolean) - Optional - Whether to play the clip in reverse.
    - **volume** (number) - Optional - Volume of the clip (0 to 1).
    - **fadeInDuration** (number) - Optional - Fade-in duration in seconds.
    - **fadeOutDuration** (number) - Optional - Fade-out duration in seconds.
    - **trimStart** (number) - Optional - Trim start of the clip in seconds.
    - **trimEnd** (number) - Optional - Trim end of the clip in seconds.
    - **alignement** (string) - Optional - Alignment of the clip within the layer. Possible values: `start`, `end`, `center`.
  - **soundTemplateRef** (string) - Optional - Reference to a sound template asset for background audio.
  - **forcedDuration** (number) - Optional - Exact duration for the section in seconds.
  - **paddingStart** (number) - Optional - Padding before the layers in seconds.
  - **paddingEnd** (number) - Optional - Padding after the layers in seconds.
  - **smartFit** (boolean) - Optional - Enables smart-fit feature for sound templates.
  - **soundEffects** (array) - Optional - Array of sound effect objects to apply to the section.
    - **type** (string) - Required - Type of the effect, must be `soundEffect`.
    - **soundEffectAlias** (string) - Required - Alias of the sound effect.

### Request Example
```json
{
  "production": {
    "arrangement": {
      "sections": [
        {
          "layers": [
            {
              "type": "audioform",
              "assetRef": "asset_123",
              "duration": 10.5,
              "startOffset": 0,
              "endOffset": 10.5,
              "reverse": false,
              "volume": 1,
              "fadeInDuration": 0.5,
              "fadeOutDuration": 0.5,
              "trimStart": 0,
              "trimEnd": 10.5,
              "alignement": "start"
            }
          ],
          "soundTemplateRef": "template_abc",
          "forcedDuration": 15,
          "paddingStart": 1,
          "paddingEnd": 1,
          "smartFit": true,
          "soundEffects": [
            {
              "type": "soundEffect",
              "soundEffectAlias": "reverb_large"
            }
          ]
        }
      ]
    },
    "mixingPreset": "voiceenhanced"
  }
}
```

### Response
#### Success Response (200)
- **productionId** (string) - The ID of the generated production.
- **status** (string) - The status of the production job (e.g., `processing`, `completed`, `failed`).

#### Response Example
```json
{
  "productionId": "prod_xyz789",
  "status": "processing"
}
```
```

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

### Create Batch Batches POST

Source: https://docs.audiostack.ai/reference/create_batch_batches_post

This endpoint allows for the creation of a batch of audio assets. It requires header, assets, production, and delivery information.

```APIDOC
## POST /batches

### Description
Creates a new batch of audio assets. This operation is part of the batch processing workflow.

### Method
POST

### Endpoint
/batches

### Request Body
- **header** (object) - Required - Contains metadata for the batch.
- **assets** (object) - Required - Defines the audio assets to be included in the batch. Can reference Voice, SoundTemplate, SoundTemplateSnippet, or SoundEffect.
- **production** (object) - Required - Specifies production settings for the audio.
- **delivery** (object) - Required - Defines delivery options for the generated audio.

### Request Example
```json
{
  "header": {
    "title": "My New Batch",
    "description": "A batch of audio clips for a new project."
  },
  "assets": {
    "voices": [
      {
        "$ref": "#/components/schemas/Audioform2/properties/Voice"
      }
    ],
    "soundTemplates": [
      {
        "$ref": "#/components/schemas/Audioform2/properties/SoundTemplate"
      }
    ],
    "soundTemplateSnippets": [
      {
        "$ref": "#/components/schemas/Audioform2/properties/SoundTemplateSnippet"
      }
    ],
    "soundEffects": [
      {
        "$ref": "#/components/schemas/Audioform2/properties/SoundEffect"
      }
    ]
  },
  "production": {
    "$ref": "#/components/schemas/Audioform2/properties/ProductionInput"
  },
  "delivery": {
    "$ref": "#/components/schemas/Audioform2/properties/Delivery"
  }
}
```

### Response
#### Success Response (200)
- **batchId** (string) - The unique identifier for the created batch.
- **status** (string) - The current status of the batch processing.

#### Response Example
```json
{
  "batchId": "b12345abcde",
  "status": "processing"
}
```
```

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

### Get All Batches

Source: https://docs.audiostack.ai/reference/get_batch_batches__batch_id__get

Retrieves a list of all batches. This endpoint is useful for getting an overview of all available batches.

```APIDOC
## GET /batch/batches

### Description
Retrieves a list of all batches.

### Method
GET

### Endpoint
/batch/batches

### Response
#### Success Response (200)
- **batches** (array) - A list of batch objects.
  - **batch_id** (string) - The unique identifier for the batch.
  - **created_at** (string) - The timestamp when the batch was created.
  - **status** (string) - The current status of the batch (e.g., 'processing', 'completed', 'failed').
  - **error** (string) - Details about any error that occurred during batch processing, if applicable.

#### Response Example
{
  "batches": [
    {
      "batch_id": "b12345",
      "created_at": "2023-10-27T10:00:00Z",
      "status": "completed",
      "error": null
    },
    {
      "batch_id": "b67890",
      "created_at": "2023-10-27T10:05:00Z",
      "status": "processing",
      "error": null
    }
  ]
}
```

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

### Create a Script via API

Source: https://docs.audiostack.ai/reference/authentication

Use this `curl` command to create a new audio script within a project and module. Replace 'APIKEY' with your actual API key.

```shell
curl -X 'POST' \
  'https://v2.api.audio/content/script' \
  -H 'accept: application/json' \
  -H 'x-api-key: APIKEY' \
  -H 'Content-Type: application/json' \
  -d '{ \
  "projectName": "myFirstAudioProject", \
  "moduleName": "admodule", \
  "scriptName": "script1", \
  "scriptText": "Got my first script created!" \
}'
```

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

### Get Batch by ID

Source: https://docs.audiostack.ai/reference/get_batch_batches__batch_id__get

Fetches a specific batch using its unique identifier. This is a GET request to the /batch/{batch_id} endpoint.

```APIDOC
## GET /batch/{batch_id}

### Description
Retrieves the details of a specific batch using its unique identifier.

### Method
GET

### Endpoint
/batch/{batch_id}

### Parameters
#### Path Parameters
- **batch_id** (string) - Required - The unique identifier of the batch to retrieve.

### Response
#### Success Response (200)
- **batch_id** (string) - The unique identifier of the batch.
- **status** (string) - The current status of the batch (e.g., PENDING, PROCESSING, COMPLETED, FAILED).
- **createdAt** (string) - The timestamp when the batch was created.
- **updatedAt** (string) - The timestamp when the batch was last updated.

#### Response Example
```json
{
  "batch_id": "b123e456-7890-1234-5678-9abcdef01234",
  "status": "COMPLETED",
  "createdAt": "2023-10-27T10:00:00Z",
  "updatedAt": "2023-10-27T10:05:00Z"
}
```
```

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

### Get Batch by ID

Source: https://docs.audiostack.ai/reference/get_batch_batches__batch_id__get

Fetches a specific batch using its unique identifier. This is a GET request to the /batch/{batch_id} endpoint.

```APIDOC
## GET /batch/{batch_id}

### Description
Retrieves the details of a specific batch using its unique identifier.

### Method
GET

### Endpoint
/batch/{batch_id}

### Parameters
#### Path Parameters
- **batch_id** (string) - Required - The unique identifier of the batch to retrieve.

### Response
#### Success Response (200)
- **batch_id** (string) - The unique identifier of the batch.
- **status** (string) - The current status of the batch (e.g., PENDING, PROCESSING, COMPLETED, FAILED).
- **createdAt** (string) - The timestamp when the batch was created.
- **updatedAt** (string) - The timestamp when the batch was last updated.
- **results** (array) - A list of results associated with the batch.

#### Response Example
```json
{
  "batch_id": "b12345",
  "status": "COMPLETED",
  "createdAt": "2023-10-27T10:00:00Z",
  "updatedAt": "2023-10-27T10:05:00Z",
  "results": [
    {
      "assetRef": "asset1",
      "position": 0,
      "duration": 10
    }
  ]
}
```
```

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

### Use an already uploaded brief

Source: https://docs.audiostack.ai/reference/postcreativebrief

Creates an audio ad using a previously uploaded brief file. Users can specify the number of ads to generate.

```APIDOC
## POST /briefs/file

### Description
Creates an audio ad from a stored brief file.

### Method
POST

### Endpoint
/briefs/file

### Parameters
#### Request Body
- **fileId** (string) - Required - A file ID of a valid uploaded brief.
- **numAds** (integer) - Optional - Number of audio ads to generate. Minimum: 1, Maximum: 5, Default: 3.

### Request Example
```json
{
  "fileId": "123e4567-e89b-12d3-a456-426614174000",
  "numAds": 3
}
```

### Response
#### Success Response (200)
- **statusCode** (integer) - Status of the rendering of the audioform (200 - completed, 202 - in progress).
- **audioformId** (string) - UUID of the audioform.
- **audioform** (object) - Details of the audioform.
- **details** (object) - Details about the generated ad.
  - **script** (object) - Tone descriptors and messages for the script.
    - **tone** (array of strings | null) - Tone descriptors for the script.
    - **messages** (array of strings) - Explanatory messages about the script.
  - **voices** (array of objects) - Explanations for each voice used in the ad.
    - **voice_reference** (string) - Reference to the voice asset.
    - **tone** (array of strings | null) - Descriptions of the tone with which the voice speaks.
    - **messages** (array of strings) - Explanatory messages about the voice.

#### Response Example
```json
{
  "statusCode": 202,
  "audioformId": "123e4567-e89b-12d3-a456-426614174000",
  "audioform": {},
  "details": {
    "script": {
      "tone": [
        "informative"
      ],
      "messages": []
    },
    "voices": [
      {
        "voice_reference": "voice_for_ad",
        "tone": [
          "informative",
          "friendly",
          "engaging"
        ],
        "messages": []
      }
    ]
  }
}
```
```

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

### Get Batch by ID

Source: https://docs.audiostack.ai/reference/get_batch_batches__batch_id__get

Fetches a specific batch using its unique identifier. This is a GET request to the /batch/{batchId} endpoint.

```APIDOC
## GET /batch/{batchId}

### Description
Retrieves the details of a specific batch using its unique identifier.

### Method
GET

### Endpoint
/batch/{batchId}

### Parameters
#### Path Parameters
- **batchId** (string) - Required - The unique identifier of the batch to retrieve.
```

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

### Create Batch Batches POST

Source: https://docs.audiostack.ai/reference/create_batch_batches_post

This endpoint allows for the creation of a batch job that processes multiple audio assets according to specified configurations. It supports various presets for loudness and mixing, and allows for defining time constraints for each media asset.

```APIDOC
## POST /batches

### Description
Creates a new batch job for processing audio assets.

### Method
POST

### Endpoint
/batches

### Request Body
- **name** (string) - Required - The name of the batch.
- **media** (array) - Required - A list of media assets to be processed.
  - **fileId** (string) - Required - The ID of the media file.
  - **loudnessPreset** (string) - Optional - The loudness preset to apply (e.g., "youtube", "lowVol", "podcastDynamic").
  - **mixingPreset** (string) - Optional - The mixing preset to apply (e.g., "balanced", "voiceenhanced").
  - **placement** (string) - Optional - The placement of the audio (e.g., "background", "foreground").
  - **targetDuration** (number) - Optional - The target duration in seconds.
  - **smartFit** (boolean) - Optional - Whether to enable the smart fit feature.
  - **processRequired** (string) - Optional - The type of duration processing required (e.g., "trim_only", "speed_up", "slow_down").

### Response
#### Success Response (201 Created)
- **batchId** (string) - The ID of the created batch.
- **status** (string) - The status of the batch job (e.g., "pending", "processing", "completed").

#### Response Example
```json
{
  "batchId": "b12345",
  "status": "pending"
}
```
```

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

### Example Story Response

Source: https://docs.audiostack.ai/reference/postsoundtemplatesquery

An example of a complete response object for a story creation job, including metadata and generated output details.

```json
{
  "meta": {
    "version": "123",
    "requestId": "165e5b01-43b3-45df-b992-75af149f3c3d",
    "creditsUsed": 10,
    "creditsRemaining": 990
  },
  "message": "Story build completed successfully",
  "warnings": [],
  "data": {
    "storyId": "0d694352-266c-4a62-b09f-4e910657af11",
    "storyResult": {
      "title": "My Podcast",
      "chapters": [],
      "voices": [],
      "sounds": {},
      "production": {},
      "delivery": {}
    },
    "audioforms": [],
    "output": {
      "audioformUris": [
        "https://v2.api.audio/public-file/aaaaaaaa-0000-0000-0000-000000000001",
        "https://v2.api.audio/public-file/aaaaaaaa-0000-0000-0000-000000000002"
      ],
      "public": true,
      "singleAudioFileUri": "https://v2.api.audio/public-file/aaaaaaaa-0000-0000-0000-000000000003",
      "extension": "mp3"
    }
  }
}
```

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

### Create Folder

Source: https://docs.audiostack.ai/openapi/audiostack-api.json

Creates a new folder.

```APIDOC
## POST /folders

### Description
Creates a new folder.

### Method
POST

### Endpoint
/folders

### Parameters
#### Request Body
- **name** (string) - Required - The name of the folder.

### Request Example
{
  "name": "New Folder Name"
}

### Response
#### Success Response (200)
- **folderId** (string) - Description
- **name** (string) - Description
- **createdAt** (string) - Description
- **updatedAt** (string) - Description

#### Response Example
{
  "folderId": "string",
  "name": "string",
  "createdAt": "string",
  "updatedAt": "string"
}
```

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

### Create Project

Source: https://docs.audiostack.ai/openapi/audiostack-api.json

Creates a new project within the AudioStack system. Projects serve as top-level containers for files and folders.

```APIDOC
## POST /projects

### Description
Creates a new project.

### Method
POST

### Endpoint
/projects

### Parameters
#### Request Body
- **projectName** (string) - Required - The name of the project to be created.

### Request Example
{
  "projectName": "My New Project"
}

### Response
#### Success Response (200)
- **projectId** (string) - The unique identifier for the newly created project.
- **projectName** (string) - The name of the created project.

#### Response Example
{
  "projectId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "projectName": "My New Project"
}
```

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

### Get File by ID

Source: https://docs.audiostack.ai/reference/get_file_files__fileid__get

Fetches the details of a specific file using its unique identifier. This operation is part of the Files resource and supports GET requests.

```APIDOC
## GET /files/{fileId}

### Description
Retrieves the details of a specific file using its unique identifier.

### Method
GET

### Endpoint
/files/{fileId}

### Parameters
#### Path Parameters
- **fileId** (string) - Required - The unique identifier of the file.

### Responses
#### Success Response (200)
- **fileId** (string) - The unique identifier of the file.
- **fileName** (string) - The name of the file.
- **folderId** (string) - The identifier of the folder containing the file.
- **url** (string or null) - The URL of the file.
- **createdBy** (string) - The identifier of the user who created the file.
- **updatedAt** (string or null) - The timestamp when the file was last updated.
- **updatedBy** (string) - The identifier of the user who last updated the file.

#### Error Response (422)
- **detail** (array) - An array of validation errors.
```

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

### OpenAPI Definition for Get File Categories

Source: https://docs.audiostack.ai/reference/get_file_categories_files_file_categories_get

This snippet shows the OpenAPI 3.1.0 definition for the GET /files/file-categories endpoint. It includes details on the operation, responses, and component schemas.

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Audiostack API",
    "description": "Documentation for the Audiostack API - the infrastructure for audio",
    "version": "v2",
    "termsOfService": "https://audiostack.ai/en/legal/terms-of-service",
    "contact": {
      "email": "support@audiostack.ai"
    }
  },
  "servers": [
    {
      "url": "https://v2.api.audio",
      "description": "Production server"
    },
    {
      "url": "https://staging-v2.api.audio",
      "description": "Staging server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/files/file-categories": {
      "get": {
        "tags": [
          "Files"
        ],
        "summary": "Get File Categories",
        "operationId": "get_file_categories_files_file_categories_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FileCategoriesResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    },
    "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"
      },
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
          }
        },
        "type": "object",
        "title": "HTTPValidationError"
      },
      "FileCategoriesResponse": {
        "properties": {
          "fileTypes": {
            "items": {
              "$ref": "#/components/schemas/FileType"
            },
            "type": "array",
            "title": "Filetypes"
          }
        },
        "type": "object",
        "required": [
          "fileTypes"
        ],
        "title": "FileCategoriesResponse"
      },
      "FileCategory": {
        "properties": {
          "categoryId": {
            "type": "string",
            "format": "uuid",
            "title": "Categoryid"
          },
          "name": {
            "type": "string",
            "title": "Name"
          }
        },
        "type": "object",
        "required": [
          "categoryId",
          "name"
        ],
        "title": "FileCategory"
      },
      "FileType": {
        "properties": {
          "fileTypeId": {
            "type": "string",
            "format": "uuid",
            "title": "Filetypeid"
          },
          "name": {
            "type": "string",
            "title": "Name"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "title": "Createdat"
          },
          "fileCategories": {
            "items": {
              "$ref": "#/components/schemas/FileCategory"
            },
            "type": "array",
            "title": "Filecategories"
          }
        },
        "type": "object",
        "required": [
          "fileTypeId",
          "name",
          "createdAt",
          "fileCategories"
        ],
        "title": "FileType"
      }
    }
  }
}
```

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

### Create Batch Batches

Source: https://docs.audiostack.ai/reference/create_batch_batches_post

This endpoint allows for the creation of a batch, which can contain multiple audio assets. The structure of the batch and its contents are defined by the OpenAPI schema provided.

```APIDOC
## POST /batches

### Description
Creates a new batch with specified audio assets.

### Method
POST

### Endpoint
/batches

### Request Body
- **name** (string) - Required - The name of the batch.
- **items** (array) - Required - A list of audio assets to include in the batch. Each item can be a MediaResult, ProductionResult, or STSResult.

#### MediaResult
- **type** (string) - Required - Must be "media".
- **fileId** (string) - Required - The ID of the media file.
- **duration** (number) - Required - The duration of the audio in seconds.
- **uri** (string) - Required - The download URI of the audio file.
- **playbackGainHint** (number | null) - Optional - Playback gain hint in dB.

#### ProductionResult
- **arrangement** (object) - Required - The arrangement result.
- **masteringPreset** (string) - Required - The mastering preset to be used. Enum: ["balanced", "voiceenhanced", "musicenhanced"].

#### STSResult
- **type** (string) - Required - Must be "sts".
- **mediaRef** (string) - Required - Reference to the media file containing the source speech.
- **voiceRef** (string) - Required - Reference to the voice asset.
- **targetDuration** (number | null) - Optional - Target duration in seconds for time-stretching.
- **duration** (number) - Required - The actual duration of the audio in seconds.
- **uri** (string) - Required - The download URI of the audio file.
- **playbackGainHint** (number | null) - Optional - Playback gain hint in dB.

### Response
#### Success Response (200)
- **batchId** (string) - The ID of the created batch.
- **status** (string) - The status of the batch creation.
```