{
  "openapi": "3.1.0",
  "info": {
    "title": "Jammable API",
    "description": "Transform audio with AI voices programmatically. Use the Jammable API to search voice models, create voice conversions from audio files or text-to-speech, and retrieve results.\n\n## Authentication\n\nAll requests require an API key passed via the `Authorization` header:\n\n```\nAuthorization: Bearer jmb_live_your_api_key_here\n```\n\n## 🔑 Get Started\n\nYou need an API key to make requests. Create one now:\n\n> **[Open the Developer Dashboard →](https://www.jammable.com/developers/dashboard)**\n\n## Rate Limits\n\nRate limits depend on your plan tier. Headers are included in every response:\n\n| Header | Description |\n|--------|-------------|\n| `X-RateLimit-Limit` | Requests allowed per minute |\n| `X-RateLimit-Remaining` | Requests remaining in current window |\n| `X-RateLimit-Reset` | Unix timestamp when the window resets |\n\n## Pricing\n\nUsage is billed per minute of audio processed, by the second, and deducted from your balance after completion. Rates fall with your volume in the calendar month (UTC):\n\n| Minutes this month | Price per minute |\n|---|---|\n| First 10,000 | $0.05 |\n| 10,000 to 50,000 | $0.04 |\n| Over 50,000 | $0.03 |\n\nEach job has a $0.01 minimum. Failed jobs are not charged. Read operations (listing models, checking cover status) are free. Top up your balance via the checkout endpoint or the [Developer Dashboard](https://www.jammable.com/developers/dashboard).\n\n**Enterprise:** for a custom rate, higher rate limits and concurrency, or paying by invoice, email [team@jammable.com](mailto:team@jammable.com?subject=Jammable%20API%20Enterprise).\n\n## File Retention\n\nOutput audio files are automatically deleted **7 days** after creation. Download the files you need before the `expires_at` timestamp.\n\n## Content Rights\n\nYou are responsible for ensuring you have the necessary rights to any audio content submitted for processing. Use of the API is subject to our [Terms of Service](https://www.jammable.com/terms).",
    "version": "1.0.0",
    "contact": {
      "name": "Jammable Developer Support",
      "url": "https://www.jammable.com",
      "email": "support@jammable.com"
    }
  },
  "servers": [
    {
      "url": "https://www.jammable.com",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Voice Models",
      "description": "Browse and search the Jammable voice model catalog"
    },
    {
      "name": "Covers",
      "description": "Create AI voice covers and check their status"
    },
    {
      "name": "Jams",
      "description": "Covers sung by several voices, with you deciding who sings when"
    },
    {
      "name": "Uploads",
      "description": "Upload your own source audio"
    },
    {
      "name": "Text to Speech",
      "description": "Create AI voice covers from text input using text-to-speech"
    },
    {
      "name": "Balance",
      "description": "Check your balance and add funds"
    }
  ],
  "paths": {
    "/api/v1/models": {
      "get": {
        "operationId": "listModels",
        "summary": "Search voice models",
        "description": "Browse and search public voice models. Supports text search, category filtering, and sorting.",
        "tags": ["Voice Models"],
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "description": "Search by model name",
            "schema": { "type": "string" },
            "example": "deep-voice"
          },
          {
            "name": "category",
            "in": "query",
            "description": "Filter by category",
            "schema": {
              "type": "string",
              "enum": ["English", "Spanish", "Portuguese", "Italian", "German", "Korean", "Japanese", "French", "Music", "Cartoon", "Anime", "Gaming", "Public Figure", "Other"]
            }
          },
          {
            "name": "sort",
            "in": "query",
            "description": "Sort order",
            "schema": {
              "type": "string",
              "enum": ["popular", "trending", "newest"],
              "default": "popular"
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Page number (starts at 1)",
            "schema": { "type": "integer", "minimum": 1, "default": 1 }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Results per page (max 100)",
            "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of voice models",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/VoiceModel" }
                    },
                    "pagination": { "$ref": "#/components/schemas/Pagination" }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": "64abc123def4567890abcdef",
                      "name": "Deep Voice",
                      "url_param": "deep-voice",
                      "image_url": "https://images.jammable.com/models/deep-voice.jpg",
                      "categories": ["English"],
                      "description": "A deep, resonant voice model",
                      "total_uses": 150432,
                      "creator": {
                        "username": "jammable",
                        "avatar": "https://images.jammable.com/avatars/jammable.jpg"
                      }
                    }
                  ],
                  "pagination": {
                    "page": 1,
                    "limit": 20,
                    "total": 2847,
                    "total_pages": 143
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/models/{id}": {
      "get": {
        "operationId": "getModel",
        "summary": "Get voice model details",
        "description": "Retrieve details for a specific voice model by ID or URL parameter.",
        "tags": ["Voice Models"],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Model ID or URL parameter (e.g. `deep-voice`)",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Voice model details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/VoiceModel" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/covers": {
      "post": {
        "operationId": "createCover",
        "summary": "Create a cover",
        "description": "Create an AI voice cover. This is an asynchronous operation — the cover will be processed in the background. Poll `GET /api/v1/covers/{id}` to check status, or provide a `callback_url` to receive a webhook when processing completes.\n\n**Cost:** from $0.05 per minute of audio, less at volume (see Pricing), deducted after completion. Failed jobs are not charged.\n\n**Retention:** Output audio files are deleted after 7 days.",
        "tags": ["Covers"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateCoverRequest" },
              "example": {
                "voice_model_id": "deep-voice",
                "audio_url": "https://example.com/audio.mp3",
                "title": "My AI Cover",
                "pitch_semitones": 0,
                "settings": {
                  "voice_volume": 0,
                  "extract_background": false,
                  "autotune": { "strength": 0.7 },
                  "mix": { "reverb": 4, "compression": 3 },
                  "choir": { "harmonies": "little" }
                },
                "output_format": "wav",
                "callback_url": "https://myapp.com/webhook/cover-complete"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Cover creation started",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": { "type": "string", "description": "Cover ID" },
                        "short_id": { "type": "string", "description": "Short ID (e.g. jam-a3b4c5d6)" },
                        "status": { "type": "string", "enum": ["pending"] },
                        "created_at": { "type": "string", "format": "date-time" },
                        "expires_at": { "type": "string", "format": "date-time", "description": "When output files will be deleted (7 days after creation)" }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "65def456abc7890123456789",
                    "short_id": "jam-a3b4c5d6",
                    "status": "pending",
                    "created_at": "2025-03-15T14:30:00.000Z",
                    "expires_at": "2025-03-22T14:30:00.000Z"
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": {
            "description": "Insufficient balance",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" },
                "example": {
                  "error": {
                    "code": "INSUFFICIENT_BALANCE",
                    "message": "Insufficient balance. You need at least $0.25 to create a cover."
                  }
                }
              }
            }
          },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      },
      "get": {
        "operationId": "listCovers",
        "summary": "List your covers",
        "description": "List all covers created with your API key, ordered by most recent first.",
        "tags": ["Covers"],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "default": 1 }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Filter by cover status",
            "schema": {
              "type": "string",
              "enum": ["pending", "processing", "completed", "failed"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of covers",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Cover" }
                    },
                    "pagination": { "$ref": "#/components/schemas/Pagination" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/covers/{id}": {
      "get": {
        "operationId": "getCover",
        "summary": "Get cover status",
        "description": "Check the status and results of a cover. When status is `completed`, `output_urls` will contain the audio files.",
        "tags": ["Covers"],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Cover ID or short ID (e.g. `jam-a3b4c5d6`)",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Cover details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/CoverDetail" }
                  }
                },
                "example": {
                  "data": {
                    "id": "65def456abc7890123456789",
                    "short_id": "jam-a3b4c5d6",
                    "title": "My AI Cover",
                    "status": "completed",
                    "progress": 100,
                    "voice_model_id": "64abc123def4567890abcdef",
                    "output_urls": {
                      "audio": "https://audio.jammable.com/covers/combined.mp3",
                      "vocals": "https://audio.jammable.com/covers/vocals.mp3",
                      "instrumentals": "https://audio.jammable.com/covers/instrumentals.mp3"
                    },
                    "duration": 215.4,
                    "cover_settings": {
                      "pitch_semitones": 0,
                      "extract_background": false
                    },
                    "created_at": "2025-03-15T14:30:00.000Z",
                    "expires_at": "2025-03-22T14:30:00.000Z"
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/effects": {
      "get": {
        "operationId": "listEffects",
        "summary": "List effect presets",
        "tags": ["Covers"],
        "description": "The effect presets a cover or jam can use as `settings.effect_id`, most used first. `applies_to` is `vocals` (changes only the voice) or `song` (changes the whole track, for example sped up or slowed). Free.",
        "responses": {
          "200": {
            "description": "Effect presets",
            "content": {
              "application/json": {
                "example": {
                  "data": [
                    { "id": "6650a1b2c3d4e5f607182930", "name": "Slow and Reverb", "description": "Slowed down with a big room", "emoji": "🌙", "applies_to": "song" }
                  ]
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/jams": {
      "post": {
        "operationId": "createJam",
        "summary": "Create a jam",
        "tags": ["Jams"],
        "description": "A cover sung by several voices, where you decide who sings when. Give the voices in order and `voice_times` as index, start and end. Poll `GET /api/v1/jams/{id}`, or pass `callback_url`.\n\n**Cost:** billed per minute of output like a cover, however many voices sing.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateJamRequest" },
              "example": {
                "voice_model_ids": ["deep-voice", "bright-voice"],
                "audio_url": "https://example.com/audio.mp3",
                "voice_times": [
                  { "index": 0, "start": 0, "end": 15.5 },
                  { "index": 1, "start": 15.5, "end": 31 }
                ],
                "clip": { "start_s": 30, "duration_s": 31 },
                "voice_pitch": [0, 4],
                "settings": {
                  "mix": { "reverb": 3 }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Job started",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": { "type": "string" },
                        "short_id": { "type": "string" },
                        "status": { "type": "string", "enum": ["pending"] },
                        "created_at": { "type": "string", "format": "date-time" },
                        "expires_at": { "type": "string", "format": "date-time" }
                      }
                    }
                  }
                },
                "example": {
                  "data": { "id": "65def456abc7890123456789", "short_id": "jam-a3b4c5d6", "status": "pending", "created_at": "2025-03-15T14:30:00.000Z", "expires_at": "2025-03-22T14:30:00.000Z" }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "402": {
            "description": "Insufficient balance",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" },
                "example": {
                  "error": { "code": "INSUFFICIENT_BALANCE", "message": "Insufficient balance. You need at least $0.25 to create a cover." }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/jams/{id}": {
      "get": {
        "operationId": "getJam",
        "summary": "Get jam status",
        "tags": ["Jams"],
        "description": "Status and results of a jam. When status is `completed`, `output_urls` has the full mix, the vocals and the instrumental.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Jam ID or short ID (e.g. `jam-a3b4c5d6`)",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Jam details",
            "content": {
              "application/json": {
                "example": {
                  "data": {
                    "id": "65def456abc7890123456789",
                    "short_id": "jam-a3b4c5d6",
                    "title": "My jam",
                    "status": "completed",
                    "progress": 100,
                    "voice_model_ids": ["64abc123def4567890abcdef", "64abc123def4567890abcdee"],
                    "voice_times": [
                      { "voice": "deep-voice", "start": 0, "end": 15.5 },
                      { "voice": "bright-voice", "start": 15.5, "end": 31 }
                    ],
                    "output_urls": { "audio": "https://audio.jammable.com/jammer/.../combined.mp3", "vocals": "https://audio.jammable.com/jammer/.../vocals.mp3", "instrumentals": "https://audio.jammable.com/jammer/.../instrumentals.mp3" },
                    "duration": 31,
                    "created_at": "2025-03-15T14:30:00.000Z",
                    "expires_at": "2025-03-22T14:30:00.000Z"
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/uploads": {
      "post": {
        "operationId": "createUpload",
        "summary": "Upload a source track",
        "tags": ["Uploads"],
        "description": "Get a presigned URL to upload an audio file straight to Jammable storage, then use the returned `audio_url` with `POST /api/v1/covers` or `POST /api/v1/jams`. Send the file with `PUT` to `upload_url`, with the `Content-Type` header given, within `expires_in` seconds. Works from browsers (CORS is allowed).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["content_type"],
                "properties": {
                  "content_type": { "type": "string", "enum": ["audio/mpeg", "audio/mp3", "audio/wav", "audio/x-wav", "audio/wave", "audio/mp4", "audio/x-m4a", "audio/aac", "audio/ogg", "audio/flac", "audio/webm"] },
                  "filename": { "type": "string", "maxLength": 200 },
                  "size_bytes": { "type": "integer", "maximum": 209715200, "description": "Up to 200 MB" }
                }
              },
              "example": { "content_type": "audio/mpeg", "filename": "song.mp3" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Upload URL",
            "content": {
              "application/json": {
                "example": {
                  "data": {
                    "upload_url": "https://...r2.cloudflarestorage.com/audio/api-uploads/...",
                    "method": "PUT",
                    "headers": { "Content-Type": "audio/mpeg" },
                    "audio_url": "https://audio.jammable.com/api-uploads/.../file.mp3",
                    "expires_in": 900
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/tts": {
      "post": {
        "operationId": "createTtsCover",
        "summary": "Create a TTS cover",
        "description": "Create an AI voice cover from text using text-to-speech. The text is first synthesized into speech audio, then processed through the selected voice model.\n\nThis is an asynchronous operation — the cover will be processed in the background. Poll `GET /api/v1/covers/{id}` to check status, or provide a `callback_url` to receive a webhook when processing completes.\n\n**Cost:** from $0.05 per minute of audio, less at volume (see Pricing), deducted after completion. Failed jobs are not charged.\n\n**Retention:** Output audio files are deleted after 7 days.",
        "tags": ["Text to Speech"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateTtsRequest" },
              "example": {
                "voice_model_id": "deep-voice",
                "text": "Hello, this is a test of the text to speech system.",
                "gender": "male",
                "accent": "US",
                "expression": "Default",
                "speed": "Default",
                "title": "My TTS Cover",
                "callback_url": "https://myapp.com/webhook/cover-complete"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "TTS cover creation started",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": { "type": "string", "description": "Cover ID" },
                        "short_id": { "type": "string", "description": "Short ID (e.g. jam-a3b4c5d6)" },
                        "status": { "type": "string", "enum": ["pending"] },
                        "created_at": { "type": "string", "format": "date-time" },
                        "expires_at": { "type": "string", "format": "date-time", "description": "When output files will be deleted (7 days after creation)" }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "65def456abc7890123456789",
                    "short_id": "jam-a3b4c5d6",
                    "status": "pending",
                    "created_at": "2025-03-15T14:30:00.000Z",
                    "expires_at": "2025-03-22T14:30:00.000Z"
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": {
            "description": "Insufficient balance",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" },
                "example": {
                  "error": {
                    "code": "INSUFFICIENT_BALANCE",
                    "message": "Insufficient balance. You need at least $0.25 to create a TTS cover."
                  }
                }
              }
            }
          },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/credits": {
      "get": {
        "operationId": "getCredits",
        "summary": "Get balance",
        "description": "Check your current API balance in USD.",
        "tags": ["Balance"],
        "responses": {
          "200": {
            "description": "Current balance",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "balance": { "type": "number", "description": "Available balance in USD" }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "balance": 48.50
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/credits/checkout": {
      "post": {
        "operationId": "createCreditCheckout",
        "summary": "Top up balance",
        "description": "Create a Stripe Checkout session to add funds to your API balance. Returns a checkout URL to complete payment.",
        "tags": ["Balance"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/TopUpRequest" },
              "example": {
                "amount": 50
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Checkout session created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "checkout_url": { "type": "string", "format": "uri", "description": "Stripe Checkout URL to complete payment" }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "checkout_url": "https://checkout.stripe.com/c/pay/cs_test_..."
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key in the format `jmb_live_...`"
      }
    },
    "schemas": {
      "VoiceModel": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "description": "Unique model ID" },
          "name": { "type": "string", "description": "Model display name" },
          "url_param": { "type": "string", "description": "URL-friendly identifier (can be used as voice_model_id when creating covers)" },
          "image_url": { "type": "string", "nullable": true, "description": "Model image URL" },
          "categories": { "type": "array", "items": { "type": "string" }, "description": "Model categories" },
          "description": { "type": "string", "nullable": true },
          "total_uses": { "type": "integer", "description": "Total number of covers made" },
          "creator": {
            "type": "object",
            "nullable": true,
            "properties": {
              "username": { "type": "string" },
              "avatar": { "type": "string" }
            }
          }
        }
      },
      "Cover": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "short_id": { "type": "string" },
          "title": { "type": "string", "nullable": true },
          "status": { "type": "string", "enum": ["pending", "processing", "completed", "failed"] },
          "progress": { "type": "integer", "minimum": 0, "maximum": 100 },
          "voice_model_id": { "type": "string", "nullable": true },
          "output_urls": {
            "type": "object",
            "nullable": true,
            "description": "Available only when status is `completed`. Files are deleted after `expires_at`.",
            "properties": {
              "audio": { "type": "string", "nullable": true, "description": "Final mixed audio" },
              "vocals": { "type": "string", "nullable": true, "description": "Converted vocals only" },
              "instrumentals": { "type": "string", "nullable": true, "description": "Instrumental track" }
            }
          },
          "duration": { "type": "number", "nullable": true, "description": "Duration in seconds" },
          "created_at": { "type": "string", "format": "date-time" },
          "expires_at": { "type": "string", "format": "date-time", "description": "When output files will be deleted (7 days after creation)" }
        }
      },
      "CoverDetail": {
        "allOf": [
          { "$ref": "#/components/schemas/Cover" },
          {
            "type": "object",
            "properties": {
              "cover_settings": {
                "type": "object",
                "properties": {
                  "pitch_semitones": { "type": "integer" },
                  "extract_background": { "type": "boolean" }
                }
              }
            }
          }
        ]
      },
      "CreateCoverRequest": {
        "type": "object",
        "required": ["voice_model_id", "audio_url"],
        "properties": {
          "voice_model_id": { "type": "string", "description": "ID or URL parameter of the voice model to use (e.g. `64abc123def...` or `deep-voice`)" },
          "audio_url": { "type": "string", "format": "uri", "description": "Publicly accessible URL to an audio file (MP3, WAV, etc.). YouTube and streaming links are not supported." },
          "title": { "type": "string", "maxLength": 200, "description": "Optional title for the cover" },
          "pitch_semitones": { "type": "integer", "minimum": -24, "maximum": 24, "default": 0, "description": "Pitch shift in semitones (-24 to +24)" },
          "settings": {
            "type": "object",
            "properties": {
              "voice_volume": { "type": "number", "minimum": -10, "maximum": 10, "default": 0, "description": "Voice volume adjustment in dB" },
              "extract_background": { "type": "boolean", "default": false, "description": "Extract and preserve background vocals" },
              "vocals_only": { "type": "boolean", "default": false, "description": "Set when `audio_url` is already an a cappella (vocals only). Skips vocal separation" },
              "autotune": {
                "type": "object",
                "description": "Snap the new vocal to the song's key. Send `true` for full strength, or an object to set the strength.",
                "properties": {
                  "strength": { "type": "number", "minimum": 0.2, "maximum": 1, "default": 1, "description": "0.4 is light, 0.7 medium, 1 strong" }
                }
              },
              "effect_id": { "type": "string", "description": "An effect preset from `GET /api/v1/effects`, by `id` or exact `name`. Some presets change only the vocals, others the whole song (for example sped up or slowed)." },
              "mix": {
                "type": "object",
                "description": "Mix controls on the vocals, applied after the effect preset. Whole numbers; leave a knob out to keep it at 0.",
                "properties": {
                  "reverb": { "type": "integer", "minimum": 0, "maximum": 10, "default": 0 },
                  "echo": { "type": "integer", "minimum": 0, "maximum": 10, "default": 0 },
                  "compression": { "type": "integer", "minimum": 0, "maximum": 10, "default": 0 },
                  "bass": { "type": "integer", "minimum": -6, "maximum": 6, "default": 0, "description": "dB at 150 Hz" },
                  "treble": { "type": "integer", "minimum": -6, "maximum": 6, "default": 0, "description": "dB at 8 kHz" }
                }
              },
              "choir": {
                "type": "object",
                "description": "Extra copies of the voice behind the lead. `doubles` adds two slightly detuned takes panned left and right; `harmonies` adds a third above and a third below along the song's scale. Each is `little` or `lot` (how loud and wide). Covers only.",
                "properties": {
                  "doubles": { "type": "string", "enum": ["little", "lot"] },
                  "harmonies": { "type": "string", "enum": ["little", "lot"] }
                }
              }
            }
          },
          "clip": {
            "type": "object",
            "required": ["start_s", "duration_s"],
            "description": "Render only this window of the song. The output is `duration_s` long and you are billed for that length.",
            "properties": {
              "start_s": { "type": "number", "minimum": 0, "description": "Start, in seconds of the source" },
              "duration_s": { "type": "number", "exclusiveMinimum": 0, "maximum": 360, "description": "Length in seconds, up to 360" }
            }
          },
          "output_format": { "type": "string", "enum": ["mp3", "wav"], "default": "mp3", "description": "`wav` returns every output file as stereo WAV instead of 320 kbps MP3" },
          "callback_url": { "type": "string", "format": "uri", "description": "URL to receive a webhook when the cover completes or fails. Retried up to 3 times with exponential backoff on failure." }
        }
      },
      "CreateJamRequest": {
        "type": "object",
        "required": ["voice_model_ids", "voice_times"],
        "properties": {
          "voice_model_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 9,
            "items": { "type": "string" },
            "description": "Voices in slot order (ID or URL parameter). `voice_times[].index` points into this list."
          },
          "audio_url": { "type": "string", "format": "uri", "description": "Public audio file URL. Give this or `source_cover_id`." },
          "source_cover_id": { "type": "string", "description": "Reuse the source track of one of your covers or jams (ID or short ID) instead of `audio_url`." },
          "voice_times": {
            "type": "array",
            "minItems": 1,
            "maxItems": 2000,
            "description": "Who sings when. Seconds of the source, or of the clip when `clip` is set.",
            "items": {
              "type": "object",
              "required": ["index", "start", "end"],
              "properties": {
                "index": { "type": "integer", "minimum": 0, "description": "Index into `voice_model_ids`" },
                "start": { "type": "number", "minimum": 0 },
                "end": { "type": "number", "minimum": 0 }
              }
            }
          },
          "clip": {
            "type": "object",
            "required": ["start_s", "duration_s"],
            "description": "Render only this window of the song. The output is `duration_s` long and you are billed for that length.",
            "properties": {
              "start_s": { "type": "number", "minimum": 0, "description": "Start, in seconds of the source" },
              "duration_s": { "type": "number", "exclusiveMinimum": 0, "maximum": 360, "description": "Length in seconds, up to 360" }
            }
          },
          "voice_pitch": {
            "type": "array",
            "maxItems": 9,
            "items": { "type": "number", "minimum": -12, "maximum": 12 },
            "description": "Pitch per voice in semitones, in the order of `voice_model_ids`. Missing entries are 0."
          },
          "title": { "type": "string", "maxLength": 200 },
          "settings": {
            "type": "object",
            "properties": {
              "voice_volume": { "type": "number", "minimum": -10, "maximum": 10, "default": 0, "description": "Voice volume adjustment in dB" },
              "extract_background": { "type": "boolean", "default": false, "description": "Extract and preserve background vocals" },
              "vocals_only": { "type": "boolean", "default": false, "description": "Set when `audio_url` is already an a cappella (vocals only). Skips vocal separation" },
              "autotune": {
                "type": "object",
                "description": "Snap the new vocal to the song's key. Send `true` for full strength, or an object to set the strength.",
                "properties": {
                  "strength": { "type": "number", "minimum": 0.2, "maximum": 1, "default": 1, "description": "0.4 is light, 0.7 medium, 1 strong" }
                }
              },
              "effect_id": { "type": "string", "description": "An effect preset from `GET /api/v1/effects`, by `id` or exact `name`. Some presets change only the vocals, others the whole song (for example sped up or slowed)." },
              "mix": {
                "type": "object",
                "description": "Mix controls on the vocals, applied after the effect preset. Whole numbers; leave a knob out to keep it at 0.",
                "properties": {
                  "reverb": { "type": "integer", "minimum": 0, "maximum": 10, "default": 0 },
                  "echo": { "type": "integer", "minimum": 0, "maximum": 10, "default": 0 },
                  "compression": { "type": "integer", "minimum": 0, "maximum": 10, "default": 0 },
                  "bass": { "type": "integer", "minimum": -6, "maximum": 6, "default": 0, "description": "dB at 150 Hz" },
                  "treble": { "type": "integer", "minimum": -6, "maximum": 6, "default": 0, "description": "dB at 8 kHz" }
                }
              }
            }
          },
          "output_format": { "type": "string", "enum": ["mp3", "wav"], "default": "mp3", "description": "`wav` returns every output file as stereo WAV instead of 320 kbps MP3" },
          "callback_url": { "type": "string", "format": "uri", "description": "URL to receive a webhook when the jam completes or fails." }
        }
      },
      "CreateTtsRequest": {
        "type": "object",
        "required": ["voice_model_id", "text"],
        "properties": {
          "voice_model_id": { "type": "string", "description": "ID or URL parameter of the voice model to use (e.g. `64abc123def...` or `deep-voice`)" },
          "text": { "type": "string", "minLength": 1, "maxLength": 2500, "description": "The text to convert to speech (max 2500 characters)" },
          "gender": { "type": "string", "enum": ["male", "female"], "default": "male", "description": "Voice gender for the TTS synthesis" },
          "accent": { "type": "string", "enum": ["US", "GB", "FR", "DE", "ES", "IT", "KR", "AU", "JP"], "default": "US", "description": "Voice accent/language" },
          "expression": { "type": "string", "enum": ["Default", "Whispered", "Happy", "Sad", "Angry", "Shouting", "Terrified"], "default": "Default", "description": "Vocal expression style" },
          "speed": { "type": "string", "enum": ["Slowest", "Slow", "Default", "Fast", "Fastest"], "default": "Default", "description": "Speech speed" },
          "title": { "type": "string", "maxLength": 200, "description": "Optional title for the cover" },
          "pitch_semitones": { "type": "integer", "minimum": -24, "maximum": 24, "default": 0, "description": "Pitch shift in semitones (-24 to +24)" },
          "settings": {
            "type": "object",
            "properties": {
              "voice_volume": { "type": "number", "minimum": -10, "maximum": 10, "default": 0, "description": "Voice volume adjustment in dB" }
            }
          },
          "callback_url": { "type": "string", "format": "uri", "description": "URL to receive a webhook when the cover completes or fails. Retried up to 3 times with exponential backoff on failure." }
        }
      },
      "TopUpRequest": {
        "type": "object",
        "required": ["amount"],
        "properties": {
          "amount": { "type": "number", "minimum": 10, "description": "Amount in USD to add to your balance (minimum $10)" }
        }
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "page": { "type": "integer" },
          "limit": { "type": "integer" },
          "total": { "type": "integer" },
          "total_pages": { "type": "integer" }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": { "type": "string", "description": "Machine-readable error code" },
              "message": { "type": "string", "description": "Human-readable error message" },
              "details": { "type": "object", "description": "Additional error context" }
            },
            "required": ["code", "message"]
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid request parameters",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" },
            "example": {
              "error": {
                "code": "BAD_REQUEST",
                "message": "Invalid request body",
                "details": { "issues": [{ "path": ["audio_url"], "message": "audio_url must be a publicly accessible audio file URL" }] }
              }
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing or invalid API key",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" },
            "example": {
              "error": {
                "code": "UNAUTHORIZED",
                "message": "Invalid or revoked API key"
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" },
            "example": {
              "error": {
                "code": "NOT_FOUND",
                "message": "Not found"
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "Rate limit exceeded",
        "headers": {
          "Retry-After": {
            "description": "Seconds until the rate limit resets",
            "schema": { "type": "integer" }
          },
          "X-RateLimit-Limit": {
            "description": "Requests allowed per minute",
            "schema": { "type": "integer" }
          },
          "X-RateLimit-Remaining": {
            "description": "Requests remaining",
            "schema": { "type": "integer" }
          }
        },
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" },
            "example": {
              "error": {
                "code": "RATE_LIMITED",
                "message": "Rate limit exceeded. 120 requests per minute allowed.",
                "details": { "retry_after": 45 }
              }
            }
          }
        }
      }
    }
  }
}
