Generate a song

June 3, 2026

Table of contents

  1. Request Headers
  2. Request Body
  3. Responses
  4. Model
  5. Examples
  6. Try It

Generate a complete song from a text prompt using Lyria 3 Pro. Whether the result is vocal or instrumental is decided by the model from your prompt — describe vocals (or pass your own lyrics) to get a sung track with model-written lyrics, or set instrumental: true to force an instrumental. Each generation returns up to two clips (an A/B pair) and consumes credits from your account balance.

https://api.useapi.net/v1/flowmusic/music

Request Headers 

Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data

Request Body 

{
  "prompt": "lo-fi hip hop, mellow piano, 80 bpm",
  "instrumental": false,
  "ghostwriter": "pro"
}
  • email is optional. The Flow Music account to use. See GET /accounts for configured accounts. If not provided, the API automatically selects an account with available capacity. Specify when you want to use a specific configured account.
  • prompt is required, the song description — style, mood, genre, instruments, BPM, and any vocal direction. 1–10,000 characters.
  • instrumental is optional. true forces an instrumental (prepends an [Instrumental] tag). false (default) lets the model decide whether to sing based on your prompt.
  • lyrics is optional, your own lyrics, ideally [Verse]/[Chorus]-tagged (≤10,000 chars). Providing them forces a vocal render of those words. Omit them and the model writes lyrics only if the prompt implies vocals.
  • ghostwriter is optional, the lyrics-writer version used when the model writes the lyrics. It has no effect if you supply your own lyrics. Supported values: standard, pro.
  • refImage1 to refImage10 are optional, encoded image asset IDs from POST /files or POST /files/generate. Passed to the model only as uploaded-file hints (it may loosely nudge style) — not a literal reference.
  • refAudio1 to refAudio10 are optional, encoded audio asset IDs from POST /files. Experimental, limited effect — the current Lyria 3 Pro model does not truly reference an uploaded song. The upload is passed only as a hint and may not influence the result.
  • mode is optional, sync (default — blocks until the song is ready, ~40–150 s) or async (returns 201 immediately with a jobid; poll GET /jobs/jobid for the result). In sync your connection must stay open the whole time — if it drops the result is lost, so prefer async on mobile, flaky networks, or short-timeout platforms.
  • replyUrl is optional, webhook URL. When the job completes or fails the API POSTs the job record to it — the same shape as GET /jobs/jobid.
  • replyRef is optional, custom reference string echoed back in the webhook.

References must come from one account. A refImage/refAudio ID is tied to the account it was uploaded to, so if you pass any, they must all be from that one account — and the song is generated there. If you also pass email, it has to match, or the request fails with 400.

Responses

  • 200 OK

    Sync mode (default, or "mode": "sync") — the song is generated and the full record is returned inline. All audio lives in the clips[] array.

    {
  "jobid": "job:aaaabbbb-cccc-4ddd-8eee-ffff99990000-user:[email protected]:flowmusic",
  "email": "[email protected]",
  "status": "completed",
  "created_at": "2026-06-01T18:40:42.412Z",
  "completed_at": "2026-06-01T18:42:55.123Z",
  "duration_ms": 132711,
  "clips": [
    {
      "clip": "user:[email protected]:a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "title": "Morning Sun",
      "duration_s": 173.04,
      "lyrics": "[Verse 1]\nCity lights blur in the rain\n[Chorus]\nAnd I will wait for the morning sun",
      "seed": null,
      "lyrics_timing": [ [0.0, 2.4], [2.4, 5.1] ],
      "created_at": "2026-06-01T18:41:04.283Z",
      "audio_url": "https://storage.googleapis.com/...a1b2c3d4.m4a",
      "wav_url": "https://storage.googleapis.com/...a1b2c3d4.wav",
      "image_url": "https://storage.googleapis.com/...b2c3d4e5.jpg"
    }
  ],
  "request": { "prompt": "lo-fi hip hop, mellow piano, 80 bpm", "instrumental": false }
}

  • 201 Created

    Async mode ("mode": "async") — the job is queued and returned immediately as pending. Poll GET /jobs/jobid until status is completed or failed.

    {
  "jobid": "job:aaaabbbb-cccc-4ddd-8eee-ffff99990000-user:[email protected]:flowmusic",
  "email": "[email protected]",
  "status": "pending",
  "created_at": "2026-06-01T18:40:42.412Z",
  "request": {
    "prompt": "upbeat funk groove, 110 bpm",
    "instrumental": true,
    "mode": "async"
  }
}

  • 400 Bad Request

    Validation error (missing/invalid parameter, or no account configured).

    {
  "error": "Parameter prompt is required",
  "code": 400
}

  • 401 Unauthorized

    Invalid API token.

    {
  "error": "Unauthorized",
  "code": 401
}

  • 402 Payment Required

    The targeted Flow Music account has insufficient credits to complete the generation. Top up its credit balance (or target a funded account with email), then retry.

    {
  "error": "FlowMusic conversation failed (402): {\"detail\":\"User has insufficient credits\"}",
  "code": 402
}

  • 422

    The model produced no audio (e.g. a content-moderation refusal). A terminal job record with status: "failed".

    {
  "jobid": "job:aaaabbbb-cccc-4ddd-8eee-ffff99990000-user:[email protected]:flowmusic",
  "email": "[email protected]",
  "status": "failed",
  "created_at": "2026-06-01T18:40:42.412Z",
  "completed_at": "2026-06-01T18:41:10.512Z",
  "error": {
    "code": "moderation_reject",
    "message": "the model declined to generate audio for this prompt"
  },
  "request": { "prompt": "...", "instrumental": false }
}

  • 429 Too Many Requests

    Returned in two cases.

    email omitted and every configured account is already at its maxJobs concurrency limit (load-balancing has nowhere to place the job) — retry once a running job finishes:

    {
  "error": "All 3 FlowMusic accounts are at their maxJobs concurrency limit — retry shortly",
  "code": 429
}

    Or passed through from FlowMusic when a chosen account exceeds its own per-account limit (a single or email-targeted account running too many generations at once):

    {
  "error": "FlowMusic conversation failed (429): {\"detail\":\"Too Many Requests\"}",
  "code": 429
}

  • 596 Account Error

    The account targeted by email is in an error state and can’t be used — re-add it via POST /accounts. The error field returns whatever reason was recorded for the account.

    {
  "error": "Account [email protected] in error state: refresh token rejected",
  "code": 596
}

Model 

  • {
  jobid: string                  // job:<uuid>-user:<id>-<email>-bot:flowmusic
  email: string
  status: 'completed' | 'pending' | 'failed'
  created_at: string             // ISO 8601 timestamp
  completed_at?: string          // present when terminal
  duration_ms?: number           // wall-clock generation time
  clips: Array<{
    clip: string                 // encoded clip asset id — use with /music/download and /music/edit
    title: string | null
    duration_s: number | null
    lyrics: string | null        // [Verse]/[Chorus]-tagged; "[Instrumental]" for instrumentals
    seed: number | null
    lyrics_timing: Array<[number, number]> | null  // timing markers, [start, end] seconds (vocal clips)
    created_at: string           // ISO 8601 timestamp
    audio_url: string            // signed m4a download URL
    wav_url: string              // signed wav download URL
    image_url: string | null     // auto-generated artwork URL
  }>
  request: {                     // the request body you submitted, echoed back verbatim
    prompt: string
    email?: string
    instrumental?: boolean
    lyrics?: string
    ghostwriter?: 'standard' | 'pro'
    mode?: 'sync' | 'async'
    replyUrl?: string
    replyRef?: string
    refImage1?: string           // …up to refImage10 — encoded image asset IDs
    refAudio1?: string           // …up to refAudio10 — encoded audio asset IDs
  }
}

  • {
  jobid: string                  // job:<uuid>-user:<id>-<email>-bot:flowmusic
  email: string
  status: 'pending'
  created_at: string             // ISO 8601 timestamp
  request: {                     // the request body you submitted, echoed back verbatim
    prompt: string
    email?: string
    instrumental?: boolean
    lyrics?: string
    ghostwriter?: 'standard' | 'pro'
    mode?: 'sync' | 'async'
    replyUrl?: string
    replyRef?: string
    refImage1?: string           // …up to refImage10 — encoded image asset IDs
    refAudio1?: string           // …up to refAudio10 — encoded audio asset IDs
  }
}

Examples 

  • curl -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -X POST "https://api.useapi.net/v1/flowmusic/music" \
     -d '{ "prompt": "lo-fi hip hop, mellow piano, 80 bpm" }'

  • const response = await fetch('https://api.useapi.net/v1/flowmusic/music', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    prompt: 'lo-fi hip hop, mellow piano, 80 bpm'
  })
});
const result = await response.json();
console.log(result.clips?.[0]?.audio_url);

  • import requests

response = requests.post(
    'https://api.useapi.net/v1/flowmusic/music',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'},
    json={'prompt': 'lo-fi hip hop, mellow piano, 80 bpm'}
)
print(response.status_code, response.json())

Try It