RecoupGet a free auditFree audit

API REFERENCE

Create a composition plan

On this page
POST/api/music/plan

Create a composition plan from a text prompt. A composition plan is a structured representation of a song — sections, styles, lyrics, and durations — that you can review and tweak before passing to the compose endpoint. This endpoint is free and does not consume credits.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL
curl --request POST \
  --url 'https://api.recoupable.dev/api/music/plan' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "prompt": "string"
}'

Try it

Fill in the fields, send the request from your browser, and read the live response. The curl below updates as you type.

Kept in this browser tab only and cleared when it closes.

cURL for this request
curl --request POST \
  --url 'https://recoup-api.vercel.app/api/music/plan' \
  --header 'Content-Type: application/json' \
  --data '{
  "prompt": "string"
}'

Request body required

Plan creation parameters

application/json

promptstringrequired

Text prompt describing the desired song.

Responses

200Composition plan created successfully

application/json

planobject

The composition plan with sections, styles, lyrics, and durations.

Properties for plan
sectionsarray<object>
Item properties for sections
namestring

Section name (e.g. intro, verse, chorus)

durationnumber

Section duration in seconds

stylestring

Style description for this section

lyricsstring

Lyrics for this section

400Validation failed — invalid or missing request body fields

application/json

errorstringrequired

Error message describing what went wrong.

401Unauthorized — invalid or missing API key

application/json

errorstringrequired

Error message describing what went wrong.

500Internal server error

application/json

errorstringrequired

Error message describing what went wrong.

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download content.json
View operation source
json
{
  "description": "Create a composition plan from a text prompt. A composition plan is a structured representation of a song — sections, styles, lyrics, and durations — that you can review and tweak before passing to the compose endpoint. This endpoint is free and does not consume credits.",
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "requestBody": {
    "description": "Plan creation parameters",
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/MusicCreatePlanRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Composition plan created successfully",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MusicCreatePlanResponse"
          }
        }
      }
    },
    "400": {
      "description": "Validation failed — invalid or missing request body fields",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MusicErrorResponse"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized — invalid or missing API key",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MusicErrorResponse"
          }
        }
      }
    },
    "500": {
      "description": "Internal server error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MusicErrorResponse"
          }
        }
      }
    }
  }
}