Analyze a song with many prompts

{
  "operationId": "postSongsAnalyzeBatch",
  "summary": "Ask many questions about one song",
  "description": "Ask up to 40 short questions about one audio file in a single request. The audio is downloaded once, then every prompt is answered against it, one after another, in the order sent. Use it instead of one [`POST /api/songs/analyze`](/api-reference/songs/analyze) call per question: a batch pays the per-call base price once, not once per prompt.\n\nSend `audio_url` and `prompts`, an array of `{ id, prompt, max_new_tokens }`. `id` is your key for the answer (1 to 64 characters, unique within the batch), `prompt` is 1 to 4,000 characters, and the optional `max_new_tokens` (1 to 2048, default 400) bounds that one answer. `temperature` (default 0.2), `top_p` (default 1) and `do_sample` (default false) apply to every prompt in the batch.\n\nPricing: `$0.05` once per batch plus `$0.001166` per second of the batch's total inference time (`elapsed_seconds`, audio download included), charged once after the batch succeeds, as a single usage row. A batch that runs 90 seconds costs `$0.15494`. The balance must hold `$0.05` before the model runs, otherwise the response is `402`. A batch the model service rejects is not charged.\n\nA batch is all or nothing: if the model service rejects it, the response is `502` and no answers are returned. Prompts run one after another, so a batch of many long answers can take several minutes; the request stays open until it finishes, so use a generous client timeout.",
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "requestBody": {
    "description": "One audio file and its prompts",
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/SongAnalyzeBatchRequest"
        },
        "examples": {
          "twoQuestions": {
            "summary": "Two short questions about one file",
            "value": {
              "audio_url": "https://example.com/song.mp3",
              "prompts": [
                {
                  "id": "genre",
                  "prompt": "What genre is this?",
                  "max_new_tokens": 64
                },
                {
                  "id": "tempo",
                  "prompt": "What is the tempo in BPM?"
                }
              ],
              "temperature": 0.2,
              "top_p": 1,
              "do_sample": false
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Every prompt was answered. `answers` holds one entry per prompt, in the order sent.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SongAnalyzeBatchResponse"
          },
          "examples": {
            "twoQuestions": {
              "summary": "Answers to the two questions above",
              "value": {
                "status": "success",
                "answers": [
                  {
                    "id": "genre",
                    "response": "Indie pop.",
                    "elapsed_seconds": 1.4
                  },
                  {
                    "id": "tempo",
                    "response": "Approximately 96 BPM.",
                    "elapsed_seconds": 0.6
                  }
                ],
                "elapsed_seconds": 3.1,
                "prompts": 2
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "Bad request. The body is not valid JSON, or a field is invalid: `audio_url` missing, `prompts` empty or longer than 40, a prompt with an empty or over-long `id` or `prompt`, `max_new_tokens` outside 1 to 2048, or an `id` repeated within the batch. `missing_fields` is the path to the first invalid field.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SongAnalyzeErrorResponse"
          },
          "examples": {
            "repeatedId": {
              "summary": "Two prompts share an id",
              "value": {
                "status": "error",
                "error": "prompt ids must be unique",
                "missing_fields": [
                  "prompts"
                ]
              }
            },
            "tooManyPrompts": {
              "summary": "More than 40 prompts",
              "value": {
                "status": "error",
                "error": "prompts cannot contain more than 40 prompts",
                "missing_fields": [
                  "prompts"
                ]
              }
            }
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized — invalid or missing API key / Bearer token",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SongAnalyzeErrorResponse"
          }
        }
      }
    },
    "402": {
      "description": "Insufficient credits — the balance cannot cover the base price of a batch (`$0.05`). The model is not called, nothing is charged, and no Stripe object is created. The body includes a static `billingUrl`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SongAnalyzeInsufficientCreditsResponse"
          },
          "examples": {
            "short": {
              "summary": "A balance that cannot cover a batch",
              "value": {
                "error": "insufficient_credits",
                "remaining_credits": 12000,
                "required_credits": 50000,
                "billingUrl": "https://app.recoupable.dev"
              }
            }
          }
        }
      }
    },
    "422": {
      "description": "Unverifiable audio. Before the model is called, `audio_url` is checked with a `HEAD` request (a ranged `GET` for hosts that reject `HEAD`). It must answer 2xx within 10 seconds with an `audio/*` or `application/octet-stream` content type. When it does not, the model is not called and nothing is charged.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SongAnalyzeAudioUrlErrorResponse"
          }
        }
      }
    },
    "500": {
      "description": "Server error. The request failed for a reason other than a rejection from the model service, for example the model service could not be reached or answered with an unexpected body.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SongAnalyzeErrorResponse"
          }
        }
      }
    },
    "502": {
      "description": "The model service rejected the batch. `upstream_status` is the status it answered with and `detail` is its error text; a `422` with `audio_unreachable` or `audio_undecodable` means it could not fetch the file or could not read it as audio. No answers are returned and nothing is charged.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SongAnalyzeUpstreamErrorResponse"
          },
          "examples": {
            "rejectedBatch": {
              "summary": "The model service could not fetch the audio",
              "value": {
                "status": "error",
                "error": "Music analysis failed (status 422)",
                "upstream_status": 422,
                "detail": "{\"detail\":\"audio_unreachable: could not download the audio file\"}"
              }
            }
          }
        }
      }
    }
  }
}