API REFERENCE

List Music Generations

On this page

GET/api/music

The calling account's music generations, newest first. Scope follows the standard account override: with no account_id you get your own personal and organization generations; pass account_id to read another account you can access.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL

curl --request GET \
  --url 'https://api.recoupable.dev/api/music' \
  --header 'x-api-key: YOUR_API_KEY'

Replace the YOUR_ placeholders with your values. Required query parameters are included; optional parameters are listed below.

Parameters

Query parameters

account_idstring

Optional. Read another account you can access. Defaults to the calling account.

statusstring · enum

Optional. Return only generations in this state.

Values: "pending", "processing", "completed", "failed"

limitinteger

Optional. Maximum generations to return, newest first.

Default: 20

offsetinteger

Optional. Number of generations to skip, for paging.

Default: 0

Responses

200Generations in the requested context, newest first.

application/json

statusstring · enum

Status of the request

Values: "success"

generationsarray<MusicGeneration>

Generations, newest first. Empty when the context has none.

Item properties

idstring

The generation's id. Poll Get Music Generation with this.

format: uuid

statusstring · enum

Lifecycle phase. pending until the workflow picks it up, processing while fal is rendering, then completed or failed.

Values: "pending", "processing", "completed", "failed"

promptstring

The music description the song was generated from.

lyricsstring

The lyrics the song was generated from.

modelstring

The generating model.

duration_secondsnumber | null

Actual length of the generated audio. Null until completed; may be shorter than requested.

audio_urlstring | null

Playable audio URL. Null until the generation completes.

error_messagestring | null

Why the generation failed. Null unless status is failed.

created_atstring

When the generation was created.

format: date-time

updated_atstring

When the generation last changed.

format: date-time

400Invalid query parameter.

application/json

statusstring · enumrequired

Always error

Values: "error"

missing_fieldsarray<one of>

JSON path segments to the first field that failed validation, e.g. ["lyrics"]

Item properties

oneOf · string 1

string

oneOf · integer 2

integer

errorstringrequired

Human-readable error message

401Unauthorized.

application/json

statusstring · enumrequired

Always error

Values: "error"

missing_fieldsarray<one of>

JSON path segments to the first field that failed validation, e.g. ["lyrics"]

Item properties

oneOf · string 1

string

oneOf · integer 2

integer

errorstringrequired

Human-readable error message

403Access denied to the specified account_id.

application/json

statusstring · enumrequired

Always error

Values: "error"

missing_fieldsarray<one of>

JSON path segments to the first field that failed validation, e.g. ["lyrics"]

Item properties

oneOf · string 1

string

oneOf · integer 2

integer

errorstringrequired

Human-readable error message

500Internal server error.

application/json

statusstring · enumrequired

Always error

Values: "error"

missing_fieldsarray<one of>

JSON path segments to the first field that failed validation, e.g. ["lyrics"]

Item properties

oneOf · string 1

string

oneOf · integer 2

integer

errorstringrequired

Human-readable error message

Full specification

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

Download content.json

View operation source

json

{
  "summary": "List music generations",
  "description": "The calling account's music generations, newest first. Scope follows the standard account override: with no `account_id` you get your own personal and organization generations; pass `account_id` to read another account you can access.",
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "account_id",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Optional. Read another account you can access. Defaults to the calling account."
    },
    {
      "name": "status",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "pending",
          "processing",
          "completed",
          "failed"
        ]
      },
      "description": "Optional. Return only generations in this state."
    },
    {
      "name": "limit",
      "in": "query",
      "required": false,
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 50,
        "default": 20
      },
      "description": "Optional. Maximum generations to return, newest first."
    },
    {
      "name": "offset",
      "in": "query",
      "required": false,
      "schema": {
        "type": "integer",
        "minimum": 0,
        "default": 0
      },
      "description": "Optional. Number of generations to skip, for paging."
    }
  ],
  "responses": {
    "200": {
      "description": "Generations in the requested context, newest first.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MusicGenerationListResponse"
          }
        }
      }
    },
    "400": {
      "description": "Invalid query parameter.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MusicGenerationErrorResponse"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MusicGenerationErrorResponse"
          }
        }
      }
    },
    "403": {
      "description": "Access denied to the specified `account_id`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MusicGenerationErrorResponse"
          }
        }
      }
    },
    "500": {
      "description": "Internal server error.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MusicGenerationErrorResponse"
          }
        }
      }
    }
  }
}