MusicFlowAI Docs

Public API and CLI for agent-driven music workflows

Create songs, generate audio, turn songs into videos, publish to YouTube, propose plans, and poll jobs from one compact surface. The public API is intentionally small. The complex editor and render internals stay behind it.

Quickstart API Reference

Base URL

https://api.musicflowai.com/v1

Auth

Bearer mf_... API keys

CLI Package

@musicflowai/cli

Job Types

song_audio, render, publish

Quickstart

Call the API directly or use the CLI

The CLI is a thin wrapper around the same v1 endpoints. Use the API when you are integrating from another service. Use the CLI when a human logs in once and a local agent takes over on that machine.

Install CLI

npm install -g @musicflowai/cli
musicflow login
musicflow whoami

Call the API

curl -X POST https://api.musicflowai.com/v1/songs \
  -H "Authorization: Bearer mf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Write a reflective indie song about starting over",
    "generate_audio": true
  }'

Authentication

Use bearer API keys

All public requests are authenticated with app-managed MusicFlow API keys. For local workflows, the CLI can open a browser login flow and store a key automatically. For unattended systems, set MUSICFLOW_API_KEY directly.

HTTP Header

Authorization: Bearer mf_your_api_key

CLI Environment

export MUSICFLOW_API_KEY=mf_your_api_key
export MUSICFLOW_APP_URL=https://api.musicflowai.com

Reference

Seven endpoints cover the public agent surface

The public API stays intentionally compact. Song generation, single-video creation, publishing, planning, and job polling are the only top-level workflows exposed today.

Get Account

Returns the authenticated account, subscription summary, and top-level workspace stats.

GET/v1/account

Request

curl -H "Authorization: Bearer mf_your_api_key" \
  https://api.musicflowai.com/v1/account

Response

{
  "account": {
    "id": "usr_123",
    "email": "artist@example.com",
    "name": "Artist Name",
    "auth_method": "api_key"
  },
  "subscription": {
    "tier": "growth"
  },
  "stats": {
    "channels": 2,
    "producers": 3,
    "youtubeChannels": 1
  }
}

List Capabilities

Returns the capability registry for the current user, including whether each capability is allowed and which plan gate applies.

GET/v1/capabilities

Request

curl -H "Authorization: Bearer mf_your_api_key" \
  https://api.musicflowai.com/v1/capabilities

Response

{
  "capabilities": [
    {
      "id": "song_draft",
      "label": "Song Draft Generation",
      "description": "Generate lyrics, title, and metadata for a song.",
      "category": "music",
      "minimumTier": "free",
      "mode": "metered",
      "allowed": true,
      "currentTier": "growth",
      "currentUsage": 12,
      "limit": 100
    }
  ]
}

Create Song

Creates a song draft. You can generate from a freeform prompt or supply prefilled title, description, and lyrics. If generate_audio is true, MusicFlow either queues audio generation or returns inline audio when sync is true and the provider finishes within the request timeout.

POST/v1/songs

Request

{
  "prompt": "Write a bright indie pop song about finally feeling momentum again",
  "producer_id": "7d6b7b2a-7f1d-4f6d-bf4e-66ff5d9f0f4a",
  "channel_id": "13dc8ef3-28fa-4971-b141-f5b2aaf3a338",
  "generate_audio": true,
  "sync": true,
  "style_prompt": "Upbeat indie pop with clean percussion and warm hooks"
}

Response

{
  "song": {
    "id": "1633ea49-d7f0-409a-8493-7b27b2a73e7f",
    "title": "Momentum Again",
    "lyrics": "[Verse]\n...",
    "music_prompt": "Upbeat indie pop with clean percussion and warm hooks",
    "youtube_description": "A bright indie pop release about momentum after a hard stretch.",
    "channel_id": "13dc8ef3-28fa-4971-b141-f5b2aaf3a338",
    "producer_id": "7d6b7b2a-7f1d-4f6d-bf4e-66ff5d9f0f4a",
    "audio_generation_status": "completed"
  },
  "content": {
    "id": "9e460f72-f302-46d6-9882-9f8c9e72d1b4"
  },
  "audio": {
    "url": "https://musicflowai.headshotsbyai.cc/songs/1633ea49-d7f0-409a-8493-7b27b2a73e7f/output.mp3",
    "duration": 144
  },
  "job": null
}

Create Video From Song

Queues a single quick-video render from an existing song. This wraps the internal editor flow so agents can request one high-level action instead of driving editor internals directly.

POST/v1/videos/from-song

Request

{
  "song_id": "1633ea49-d7f0-409a-8493-7b27b2a73e7f",
  "caption_mode": "auto",
  "caption_style": "alexHormozi",
  "aspect_ratio": "9:16",
  "resolution": "1080p",
  "background_color": "#1a1a2e",
  "show_channel_logo": true
}

Response

{
  "video": {
    "content_id": "9e460f72-f302-46d6-9882-9f8c9e72d1b4",
    "song_id": "1633ea49-d7f0-409a-8493-7b27b2a73e7f"
  },
  "job": {
    "id": "render:4e6c6fd2-1ad4-4b89-8145-21c64f2c3e19",
    "status": "queued"
  }
}

Publish Video

Publishes an existing content asset to a connected YouTube channel. If scheduled_publish_at is supplied, the publish job is created in a scheduled state.

POST/v1/publishes

Request

{
  "content_id": "9e460f72-f302-46d6-9882-9f8c9e72d1b4",
  "youtube_channel_id": "0b5b8ad0-4c6f-4b9f-8f08-dfe4e5f0f2d2",
  "privacy_status": "unlisted"
}

Response

{
  "publish": {
    "content_id": "9e460f72-f302-46d6-9882-9f8c9e72d1b4",
    "youtube_video_id": "abc123xyz",
    "youtube_url": "https://www.youtube.com/watch?v=abc123xyz"
  },
  "job": {
    "id": "publish:9e460f72-f302-46d6-9882-9f8c9e72d1b4",
    "status": "completed"
  }
}

Generate Plan

Creates a structured proposal for an autonomous or semi-automated generation plan from a natural-language prompt.

POST/v1/plans

Request

{
  "prompt": "Create a 30-day release plan for cinematic ambient singles with one video per track"
}

Response

{
  "plan": {
    "name": "30-Day Cinematic Ambient Release Plan",
    "description": "A month-long plan for releasing cinematic ambient singles with supporting video content.",
    "musicStylePrompt": "Cinematic ambient with spacious pads, slow builds, and emotional piano textures.",
    "totalSongs": 30,
    "songsPerDay": 1,
    "producerName": "Cinematic Producer"
  }
}

Get Job

Returns the current status for queued song audio, video renders, and publish jobs. Job IDs are prefixed by type: song_audio:, render:, or publish:.

GET/v1/jobs/:id

Request

curl -H "Authorization: Bearer mf_your_api_key" \
  https://api.musicflowai.com/v1/jobs/:id

Response

{
  "job": {
    "id": "song_audio:4705063c-fe61-44a7-bbf6-12cefb77c066",
    "kind": "song_audio",
    "status": "completed",
    "error": null,
    "output": {
      "audio_url": "https://musicflowai.headshotsbyai.cc/songs/4705063c-fe61-44a7-bbf6-12cefb77c066/output.mp3"
    },
    "requestId": "019d1d41-8eed-7d93-a095-f22d26702aa6"
  }
}

Behavior

Sync mode is opportunistic, not brittle

POST /v1/songs supports sync: true only when generate_audio is also true. If the provider finishes within the request window, the API returns inline audio. If it runs long, MusicFlow degrades to async and returns 202 with a job ID instead of failing the song.

Inline completion

Fast runs return 201, a completed song, and an audio object with url and optional duration.

Fallback to async

Slow runs return 202, keep audio generation active, and include job.id like song_audio:uuid so the client can poll GET /v1/jobs/:id.

Errors

Errors use a small stable envelope

Every error response returns an error object with type, message, and an optional code and details payload. Types stay small and stable. Codes add specificity where useful.

HTTP	Type	Description
400	validation_error	Invalid or missing request parameters
401	authentication_error	Missing or invalid API key
402	insufficient_credits	Not enough credits for the operation
403	authentication_error	Forbidden or plan tier too low
404	not_found	Resource not found
429	rate_limit_error	Too many requests. Respect the Retry-After header.
500	server_error	Internal server error
502	server_error	Backend dependency temporarily unavailable

{
  "error": {
    "type": "validation_error",
    "message": "Invalid or missing request parameters",
    "code": "invalid_request",
    "details": {
      "fieldErrors": {
        "prompt": ["Required"]
      }
    }
  }
}

CLI

The CLI stays thin

The CLI mirrors the public workflows rather than exposing internal editor or render primitives. It is designed for local automation, scripting, and human-to-agent handoff.

musicflow login

Open the browser login flow and store a local app-managed API key.

musicflow logout

Remove the local CLI session config.

musicflow whoami

Return the active account and plan.

musicflow capabilities

List capabilities, plan gates, and usage limits for the current user.

musicflow song create

Create a song draft and optionally generate audio with --generate-audio and --sync.

musicflow video from-song

Queue a single editor-backed video render for an existing song.

musicflow publish create

Publish an existing video asset to YouTube.

musicflow plan create

Generate a structured plan proposal from a natural-language brief.

musicflow job get

Poll a song, video, or publish job until it reaches a terminal state.

musicflow song create \
  --prompt "Write a reflective indie song about starting over" \
  --generate-audio \
  --sync

musicflow video from-song \
  --song-id 1633ea49-d7f0-409a-8493-7b27b2a73e7f \
  --caption-mode auto \
  --caption-style alexHormozi \
  --aspect-ratio 9:16

curl -X POST https://api.musicflowai.com/v1/songs \ -H "Authorization: Bearer mf_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Write a reflective indie song about starting over", "generate_audio": true }'

{ "account": { "id": "usr_123", "email": "artist@example.com", "name": "Artist Name", "auth_method": "api_key" }, "subscription": { "tier": "growth" }, "stats": { "channels": 2, "producers": 3, "youtubeChannels": 1 } }

{ "capabilities": [ { "id": "song_draft", "label": "Song Draft Generation", "description": "Generate lyrics, title, and metadata for a song.", "category": "music", "minimumTier": "free", "mode": "metered", "allowed": true, "currentTier": "growth", "currentUsage": 12, "limit": 100 } ] }

{ "prompt": "Write a bright indie pop song about finally feeling momentum again", "producer_id": "7d6b7b2a-7f1d-4f6d-bf4e-66ff5d9f0f4a", "channel_id": "13dc8ef3-28fa-4971-b141-f5b2aaf3a338", "generate_audio": true, "sync": true, "style_prompt": "Upbeat indie pop with clean percussion and warm hooks" }

{ "song": { "id": "1633ea49-d7f0-409a-8493-7b27b2a73e7f", "title": "Momentum Again", "lyrics": "[Verse]\n...", "music_prompt": "Upbeat indie pop with clean percussion and warm hooks", "youtube_description": "A bright indie pop release about momentum after a hard stretch.", "channel_id": "13dc8ef3-28fa-4971-b141-f5b2aaf3a338", "producer_id": "7d6b7b2a-7f1d-4f6d-bf4e-66ff5d9f0f4a", "audio_generation_status": "completed" }, "content": { "id": "9e460f72-f302-46d6-9882-9f8c9e72d1b4" }, "audio": { "url": "https://musicflowai.headshotsbyai.cc/songs/1633ea49-d7f0-409a-8493-7b27b2a73e7f/output.mp3", "duration": 144 }, "job": null }

{ "song_id": "1633ea49-d7f0-409a-8493-7b27b2a73e7f", "caption_mode": "auto", "caption_style": "alexHormozi", "aspect_ratio": "9:16", "resolution": "1080p", "background_color": "#1a1a2e", "show_channel_logo": true }

{ "video": { "content_id": "9e460f72-f302-46d6-9882-9f8c9e72d1b4", "song_id": "1633ea49-d7f0-409a-8493-7b27b2a73e7f" }, "job": { "id": "render:4e6c6fd2-1ad4-4b89-8145-21c64f2c3e19", "status": "queued" } }

{ "publish": { "content_id": "9e460f72-f302-46d6-9882-9f8c9e72d1b4", "youtube_video_id": "abc123xyz", "youtube_url": "https://www.youtube.com/watch?v=abc123xyz" }, "job": { "id": "publish:9e460f72-f302-46d6-9882-9f8c9e72d1b4", "status": "completed" } }

{ "plan": { "name": "30-Day Cinematic Ambient Release Plan", "description": "A month-long plan for releasing cinematic ambient singles with supporting video content.", "musicStylePrompt": "Cinematic ambient with spacious pads, slow builds, and emotional piano textures.", "totalSongs": 30, "songsPerDay": 1, "producerName": "Cinematic Producer" } }

{ "job": { "id": "song_audio:4705063c-fe61-44a7-bbf6-12cefb77c066", "kind": "song_audio", "status": "completed", "error": null, "output": { "audio_url": "https://musicflowai.headshotsbyai.cc/songs/4705063c-fe61-44a7-bbf6-12cefb77c066/output.mp3" }, "requestId": "019d1d41-8eed-7d93-a095-f22d26702aa6" } }

HTTP

Type

Description

400

validation_error

Invalid or missing request parameters

401

authentication_error

Missing or invalid API key

402

insufficient_credits

Not enough credits for the operation

403

authentication_error

Forbidden or plan tier too low

404

not_found

Resource not found

429

rate_limit_error

Too many requests. Respect the Retry-After header.

500

server_error

Internal server error

502

server_error

Backend dependency temporarily unavailable

{ "error": { "type": "validation_error", "message": "Invalid or missing request parameters", "code": "invalid_request", "details": { "fieldErrors": { "prompt": ["Required"] } } } }