API REFERENCE

Get Music Generation

On this page

GET/api/music/{generationId}

One generation, including the seed the model used and its logs progress, both read live from the provider rather than stored. This is the polling target while a generation is in flight: call it until status is completed or failed. Responses are never cached.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL

curl --request GET \
  --url 'https://api.recoupable.dev/api/music/YOUR_GENERATION_ID' \
  --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

Path parameters

generationIdstringrequired

The generation's id, from Generate Music.

Query parameters

account_idstring

Optional. Read on behalf of another account you can access.

Responses

200The generation, with the seed it used and its render progress.

application/json

statusstring · enum

Status of the request

Values: "success"

generationall of

Properties

allOf · MusicGeneration 1

One music generation.

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

allOf · object 2

seedinteger | null

The seed the model actually used, read live from the provider rather than stored. Null until the generation completes, and null if the provider cannot be reached. Pass it back as seed to reproduce a generation. It is the only generation parameter recoverable after the fact: num_inference_steps and guidance_scale are consumed when the request is submitted and are never reported back.

logsarray<MusicGenerationLogEntry>

The model's own render progress, oldest first, read live from the provider rather than stored. Empty if the provider cannot be reached. Returned only on the single-generation read.

Item properties

atstring

When the line was emitted.

format: date-time

messagestring

What the model reported.

400generationId is not a valid uuid.

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 this generation's account.

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

404No generation with that 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": "Get music generation",
  "description": "One generation, including the `seed` the model used and its `logs` progress, both read live from the provider rather than stored. This is the polling target while a generation is in flight: call it until `status` is `completed` or `failed`. Responses are never cached.",
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "generationId",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "description": "The generation's id, from [Generate Music](/api-reference/music/generate)."
    },
    {
      "name": "account_id",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Optional. Read on behalf of another account you can access."
    }
  ],
  "responses": {
    "200": {
      "description": "The generation, with the seed it used and its render progress.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MusicGenerationDetailResponse"
          }
        }
      }
    },
    "400": {
      "description": "`generationId` is not a valid uuid.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MusicGenerationErrorResponse"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MusicGenerationErrorResponse"
          }
        }
      }
    },
    "403": {
      "description": "Access denied to this generation's account.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MusicGenerationErrorResponse"
          }
        }
      }
    },
    "404": {
      "description": "No generation with that id.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MusicGenerationErrorResponse"
          }
        }
      }
    },
    "500": {
      "description": "Internal server error.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MusicGenerationErrorResponse"
          }
        }
      }
    }
  }
}