{
 "openapi": "3.1.0",
 "info": {
  "title": "musicai",
  "version": "1.0.0",
  "description": "Free song + music video generator. ACE-Step 1.5 (MIT) sings, an open LLM writes lyrics, Whisper times words, video drawn in code. Keyless. Jobs are async: POST /api/songs then poll GET /api/songs/{id}. Agent guide: https://musicai.broke2builtai.com/skills.md All songs are free to use (no copyright claimed); see /api/library."
 },
 "servers": [
  {
   "url": "https://musicai.broke2builtai.com"
  }
 ],
 "paths": {
  "/api/songs": {
   "post": {
    "operationId": "createSong",
    "summary": "Queue a song + music video",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/SongRequest"
       }
      }
     }
    },
    "responses": {
     "202": {
      "description": "Queued",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Song"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     },
     "502": {
      "$ref": "#/components/responses/Error"
     },
     "503": {
      "$ref": "#/components/responses/Error"
     }
    }
   },
   "get": {
    "operationId": "listSongs",
    "summary": "Recent public songs",
    "parameters": [
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 50,
       "default": 12
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "songs": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Song"
           }
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/songs/{id}": {
   "get": {
    "operationId": "getSong",
    "summary": "Poll a song's status and files",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Song"
        }
       }
      }
     },
     "404": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/api/lyrics": {
   "post": {
    "operationId": "writeLyrics",
    "summary": "Write lyrics from an idea",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "prompt"
        ],
        "properties": {
         "prompt": {
          "type": "string",
          "maxLength": 600
         },
         "style": {
          "type": "string",
          "maxLength": 400
         },
         "duration": {
          "type": "integer",
          "minimum": 30,
          "maximum": 240
         },
         "language": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "title": {
           "type": "string"
          },
          "style": {
           "type": "string"
          },
          "bpm": {
           "type": [
            "integer",
            "null"
           ]
          },
          "key": {
           "type": [
            "string",
            "null"
           ]
          },
          "lyrics": {
           "type": "string"
          },
          "model": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "429": {
      "$ref": "#/components/responses/Error"
     },
     "502": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/api/status": {
   "get": {
    "operationId": "status",
    "summary": "GPU node + queue status",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/api/library": {
   "get": {
    "operationId": "library",
    "summary": "Public library: every song anyone made, free to use (credit appreciated)",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "offset",
      "in": "query",
      "schema": {
       "type": "integer",
       "default": 0
      }
     },
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "maximum": 50,
       "default": 24
      }
     },
     {
      "name": "lyrics",
      "in": "query",
      "schema": {
       "type": "boolean"
      },
      "description": "include full lyrics"
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "total": {
           "type": "integer"
          },
          "next": {
           "type": [
            "string",
            "null"
           ]
          },
          "license": {
           "type": "string"
          },
          "songs": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Song"
           }
          }
         }
        }
       }
      }
     }
    }
   }
  }
 },
 "components": {
  "responses": {
   "Error": {
    "description": "Error",
    "content": {
     "application/json": {
      "schema": {
       "type": "object",
       "properties": {
        "error": {
         "type": "string"
        }
       }
      }
     }
    }
   }
  },
  "schemas": {
   "SongRequest": {
    "type": "object",
    "properties": {
     "prompt": {
      "type": "string",
      "maxLength": 600,
      "description": "What the song is about. Lyrics are written from this if `lyrics` is absent."
     },
     "lyrics": {
      "type": "string",
      "maxLength": 3500,
      "description": "Your lyrics with [Verse 1]/[Chorus]/[Bridge] tags."
     },
     "style": {
      "type": "string",
      "maxLength": 400,
      "description": "Production caption: genre, instruments, vocal type, mood. No real artist names."
     },
     "title": {
      "type": "string",
      "maxLength": 80
     },
     "duration": {
      "type": "integer",
      "minimum": 30,
      "maximum": 240,
      "default": 120
     },
     "takes": {
      "type": "integer",
      "minimum": 1,
      "maximum": 6,
      "default": 2,
      "description": "Takes generated; the clearest one is kept."
     },
     "instrumental": {
      "type": "boolean",
      "default": false
     },
     "bpm": {
      "type": "integer",
      "minimum": 50,
      "maximum": 200
     },
     "key": {
      "type": "string",
      "examples": [
       "A minor"
      ]
     },
     "unlisted": {
      "type": "boolean",
      "default": false
     },
     "lyrics_model": {
      "type": "string",
      "description": "The `model` returned by /api/lyrics, if those lyrics are used (for the credits)."
     },
     "lyrics_edited": {
      "type": "boolean"
     }
    }
   },
   "Song": {
    "type": "object",
    "properties": {
     "id": {
      "type": "string"
     },
     "status": {
      "type": "string",
      "enum": [
       "queued",
       "running",
       "done",
       "failed"
      ]
     },
     "stage": {
      "type": "string"
     },
     "progress": {
      "type": "number"
     },
     "position": {
      "type": "integer"
     },
     "title": {
      "type": "string"
     },
     "style": {
      "type": "string"
     },
     "lyrics": {
      "type": "string"
     },
     "duration": {
      "type": "number"
     },
     "takes": {
      "type": "integer"
     },
     "page": {
      "type": "string"
     },
     "poll": {
      "type": "string"
     },
     "error": {
      "type": [
       "string",
       "null"
      ]
     },
     "node": {
      "type": "object",
      "properties": {
       "online": {
        "type": "boolean"
       },
       "last_seen": {
        "type": [
         "string",
         "null"
        ]
       }
      }
     },
     "files": {
      "type": "object",
      "description": "filename → URL (song.mp3, video.mp4, cover.jpg, lyrics.txt, song.lrc, timeline.json, how-it-was-made.md)",
      "additionalProperties": {
       "type": "string"
      }
     },
     "credit": {
      "type": "string",
      "description": "Ready-to-paste credit line. Songs are free to use; a link back is appreciated."
     }
    }
   }
  }
 }
}