{"openapi":"3.1.0","info":{"title":"SongGPT API","version":"1.0.0","description":"## Quick start\n\n1. Create an API key in your SongGPT account and top up your separate API balance.\n2. Open authentication and enter your key. Requests use Authorization: Bearer YOUR_API_KEY.\n3. Call Generate music and save data.unique_id from the response.\n4. Pass it in the unique_ids array to Get task status, then poll for song results.\n\nRequests use /openapi/v1 on the current site. Replace sample song IDs and task identifiers with real values from your account.\n\n## Billing and retries\n\nAPI balance is separate from website credits. Generation, extensions, covers, and replacements are charged per operation; status queries have no additional charge. Refer to API product pricing for current rates. The interactive client sends real requests and may incur charges. A timeout does not prove submission failed. This release has no client idempotency-key protocol: do not automatically resubmit generation. Query an existing task first.\n\n## Parameters and results\n\nRequest structures come from the actual validation schemas; operation descriptions explain model, mode, and source requirements. Unknown fields are stripped rather than forwarded. A structurally optional field may still be required in a particular mode. Responses use code/message/data; check both HTTP status and the business code.\n\nUpload and workspace management endpoints are not included in this release. Existing upload records are available through the website. An API-only workflow can use songs[].id from generated results to extend music or create a cover."},"servers":[{"url":"/openapi/v1","description":"Current SongGPT site"}],"security":[{"ApiKey":[]}],"tags":[{"name":"Music creation","description":"Submit an asynchronous task, then query its results."},{"name":"Task status","description":"Retrieve task progress and song audio."}],"paths":{"/music/generate":{"post":{"operationId":"music_generate","summary":"Generate music","tags":["Music creation"],"description":"simple mode: describe the music to generate. Custom mode: supply your own lyrics and style.\n\nSimple mode requires prompt (a description, up to 3000 characters). Custom mode requires style and title (up to 80 characters); non-instrumental music also requires prompt (lyrics, up to 5000). Simple mode does not forward style, title, or advanced weights.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","enum":["simple","custom"],"description":"simple: generate from a description; custom: supply lyrics and style."},"model":{"const":"songgpt-v1","description":"Model identifier. Omit it to use songgpt-v1, which is currently the only available value."},"instrumental":{"type":"boolean","description":"Whether to generate instrumental music. Defaults to false."},"prompt":{"type":"string","maxLength":5000,"description":"Usually a music description in simple mode and lyrics in custom mode. Requiredness and length limits depend on the mode; see the operation description."},"style":{"type":"string","maxLength":1000,"description":"Style description, up to 1000 characters. Required in custom mode."},"title":{"type":"string","maxLength":100,"description":"Song title. Required in custom mode: up to 80 characters for generation, or 100 for extension and covers."},"vocal_gender":{"type":"string","enum":["m","f"],"description":"Vocal gender: m for male, f for female. Omit to leave unspecified. Used in custom mode; omitted upstream for instrumental generation."},"style_weight":{"type":"number","minimum":0,"maximum":1,"description":"Style weight from 0 to 1. Used in custom mode."},"weirdness":{"type":"number","minimum":0,"maximum":1,"description":"Creativity level from 0 to 1. Used in custom mode."},"negative_tags":{"type":"string","maxLength":500,"description":"Styles to exclude. Used in custom mode for generation; also supported for section replacement."},"duration":{"type":"integer","minimum":10,"maximum":360,"description":"Target duration in seconds. Only supported in custom mode; other modes return an error."},"n":{"type":"integer","minimum":1,"maximum":3,"description":"Number of results. Sent upstream only for non-instrumental simple generation; unused in other branches."},"duration_ms":{"type":"integer","minimum":3000,"maximum":600000,"description":"Target duration in milliseconds. Defaults to 60000."},"workspace_id":{"type":"string","maxLength":50,"description":"Workspace unique_id (mws_) belonging to the current account. Omit to use the default workspace."}},"required":["mode"]},"example":{"mode":"simple","model":"songgpt-v1","prompt":"Bright acoustic guitar music for a sunny morning","instrumental":true}}}},"responses":{"200":{"description":"Check the business code: 0 means success; a nonzero value means failure. Successful submission creates a task; it does not mean music is ready.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"code":{"type":"number","const":0},"message":{"type":"string"},"data":{"type":"object","properties":{"unique_id":{"type":"string"},"task_id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["unique_id","task_id"]}},"required":["code","message","data"]},{"$ref":"#/components/schemas/Error"}]},"example":{"code":0,"message":"success","data":{"unique_id":"mst_example","task_id":123}}}}},"default":{"description":"Authentication, validation, balance, or service error. Check both HTTP status and response code/message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/music/extend":{"post":{"operationId":"music_extend","summary":"Extend music","tags":["Music creation"],"description":"Continue generating from a chosen point in the source audio. Simple mode accepts an optional prompt (up to 500 characters). Custom mode requires style and title; prompt is optional (up to 5000 characters). When the source duration is known it must not exceed 8 minutes, and continue_at must be less than it.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"model":{"const":"songgpt-v1","description":"Model identifier. Omit it to use songgpt-v1, which is currently the only available value."},"source":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"library"},"song_id":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["type","song_id"]},{"type":"object","properties":{"type":{"type":"string","const":"upload"},"upload_id":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["type","upload_id"]}],"description":"Choose {type: \"library\", song_id: 123} or {type: \"upload\", upload_id: 456}. The source must belong to your account and have an audio URL. Direct URLs are not accepted. Upload endpoints are not included in this release; upload_id must refer to an existing website upload."},"continue_at":{"type":"number","exclusiveMinimum":0,"description":"Extension starting point in seconds. Must be greater than 0 and less than the source duration."},"extend_type":{"type":"string","enum":["head","tail"],"description":"Extension direction. Defaults to tail."},"mode":{"type":"string","enum":["simple","custom"],"description":"simple: generate from a description; custom: supply lyrics and style."},"instrumental":{"type":"boolean","description":"Whether to generate instrumental music. Defaults to false."},"prompt":{"type":"string","maxLength":5000,"description":"Usually a music description in simple mode and lyrics in custom mode. Requiredness and length limits depend on the mode; see the operation description."},"style":{"type":"string","maxLength":1000,"description":"Style description, up to 1000 characters. Required in custom mode."},"title":{"type":"string","maxLength":100,"description":"Song title. Required in custom mode: up to 80 characters for generation, or 100 for extension and covers."},"vocal_gender":{"type":"string","enum":["m","f"],"description":"Vocal gender: m for male, f for female. Omit to leave unspecified. Used in custom mode; omitted upstream for instrumental generation."},"style_weight":{"type":"number","minimum":0,"maximum":1,"description":"Style weight from 0 to 1. Used in custom mode."},"weirdness":{"type":"number","minimum":0,"maximum":1,"description":"Creativity level from 0 to 1. Used in custom mode."},"audio_weight":{"type":"number","minimum":0,"maximum":1,"description":"Source audio weight from 0 to 1. Used for custom extensions and covers."},"workspace_id":{"type":"string","maxLength":50,"description":"Workspace unique_id (mws_) belonging to the current account. Omit to use the default workspace."}},"required":["source","continue_at","mode"]},"example":{"model":"songgpt-v1","mode":"simple","source":{"type":"library","song_id":123},"continue_at":30}}}},"responses":{"200":{"description":"Check the business code: 0 means success; a nonzero value means failure. Successful submission creates a task; it does not mean music is ready.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"code":{"type":"number","const":0},"message":{"type":"string"},"data":{"type":"object","properties":{"unique_id":{"type":"string"},"task_id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["unique_id","task_id"]}},"required":["code","message","data"]},{"$ref":"#/components/schemas/Error"}]},"example":{"code":0,"message":"success","data":{"unique_id":"mst_example","task_id":123}}}}},"default":{"description":"Authentication, validation, balance, or service error. Check both HTTP status and response code/message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/music/remix":{"post":{"operationId":"music_remix","summary":"Create a cover","tags":["Music creation"],"description":"Reimagine the source audio in a new style. Simple mode always requires prompt (up to 500 characters); style, title, and advanced weights are not sent. Custom mode requires style and title; non-instrumental music also requires prompt (up to 5000 characters). When the source duration is known it must not exceed 8 minutes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"model":{"const":"songgpt-v1","description":"Model identifier. Omit it to use songgpt-v1, which is currently the only available value."},"source":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"library"},"song_id":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["type","song_id"]},{"type":"object","properties":{"type":{"type":"string","const":"upload"},"upload_id":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["type","upload_id"]}],"description":"Choose {type: \"library\", song_id: 123} or {type: \"upload\", upload_id: 456}. The source must belong to your account and have an audio URL. Direct URLs are not accepted. Upload endpoints are not included in this release; upload_id must refer to an existing website upload."},"mode":{"type":"string","enum":["simple","custom"],"description":"simple: generate from a description; custom: supply lyrics and style."},"instrumental":{"type":"boolean","description":"Whether to generate instrumental music. Defaults to false."},"prompt":{"type":"string","maxLength":5000,"description":"Usually a music description in simple mode and lyrics in custom mode. Requiredness and length limits depend on the mode; see the operation description."},"style":{"type":"string","maxLength":1000,"description":"Style description, up to 1000 characters. Required in custom mode."},"title":{"type":"string","maxLength":100,"description":"Song title. Required in custom mode: up to 80 characters for generation, or 100 for extension and covers."},"vocal_gender":{"type":"string","enum":["m","f"],"description":"Vocal gender: m for male, f for female. Omit to leave unspecified. Used in custom mode; omitted upstream for instrumental generation."},"style_weight":{"type":"number","minimum":0,"maximum":1,"description":"Style weight from 0 to 1. Used in custom mode."},"weirdness":{"type":"number","minimum":0,"maximum":1,"description":"Creativity level from 0 to 1. Used in custom mode."},"audio_weight":{"type":"number","minimum":0,"maximum":1,"description":"Source audio weight from 0 to 1. Used for custom extensions and covers."},"workspace_id":{"type":"string","maxLength":50,"description":"Workspace unique_id (mws_) belonging to the current account. Omit to use the default workspace."}},"required":["source","mode"]},"example":{"model":"songgpt-v1","mode":"simple","source":{"type":"library","song_id":123},"prompt":"Reimagine this song as a mellow jazz arrangement"}}}},"responses":{"200":{"description":"Check the business code: 0 means success; a nonzero value means failure. Successful submission creates a task; it does not mean music is ready.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"code":{"type":"number","const":0},"message":{"type":"string"},"data":{"type":"object","properties":{"unique_id":{"type":"string"},"task_id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["unique_id","task_id"]}},"required":["code","message","data"]},{"$ref":"#/components/schemas/Error"}]},"example":{"code":0,"message":"success","data":{"unique_id":"mst_example","task_id":123}}}}},"default":{"description":"Authentication, validation, balance, or service error. Check both HTTP status and response code/message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/music/replace":{"post":{"operationId":"music_replace","summary":"Replace a section","tags":["Music creation"],"description":"Replace one section of the source song. The source must belong to your account, have ready status, an audio URL, a known duration of at least 20 seconds, and lyrics metadata.\n\nThe end must be after the start. The selected section must span 10-60 seconds, cover no more than 50% of the source, and end within the source duration. full_lyrics, style, and title are required.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"model":{"const":"songgpt-v1","description":"Model identifier. Omit it to use songgpt-v1, which is currently the only available value."},"source_song_id":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Numeric song ID from your library (songs[].id in task results), not a task ID or song unique_id."},"full_lyrics":{"type":"string","minLength":1,"maxLength":100000,"description":"The complete edited lyrics, not just the replacement section."},"style":{"type":"string","minLength":1,"maxLength":1000,"description":"Style description, up to 1000 characters. Required in custom mode."},"title":{"type":"string","minLength":1,"maxLength":255,"description":"Song title. Required in custom mode: up to 80 characters for generation, or 100 for extension and covers."},"infill_start_s":{"type":"number","minimum":0,"description":"Replacement start in seconds. Must be before the end. Rounded to two decimal places for upstream submission."},"infill_end_s":{"type":"number","exclusiveMinimum":0,"description":"Replacement end in seconds. Must not exceed the source duration. The section must span 10–60 seconds and no more than 50% of the source duration."},"negative_tags":{"type":"string","maxLength":1000,"description":"Styles to exclude. Used in custom mode for generation; also supported for section replacement."},"workspace_id":{"type":"string","maxLength":50,"description":"Workspace unique_id (mws_) belonging to the current account. Omit to use the default workspace."}},"required":["source_song_id","full_lyrics","style","title","infill_start_s","infill_end_s"]},"example":{"source_song_id":123,"full_lyrics":"Enter the complete edited lyrics here","style":"Warm pop music","title":"A New Chorus","infill_start_s":20,"infill_end_s":40}}}},"responses":{"200":{"description":"Check the business code: 0 means success; a nonzero value means failure. Successful submission creates a task; it does not mean music is ready.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"code":{"type":"number","const":0},"message":{"type":"string"},"data":{"type":"object","properties":{"unique_id":{"type":"string"},"task_id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["unique_id","task_id"]}},"required":["code","message","data"]},{"$ref":"#/components/schemas/Error"}]},"example":{"code":0,"message":"success","data":{"unique_id":"mst_example","task_id":123}}}}},"default":{"description":"Authentication, validation, balance, or service error. Check both HTTP status and response code/message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/music/tasks/status":{"post":{"operationId":"music_status","summary":"Get task status","tags":["Task status"],"description":"No additional charge. Only tasks owned by your account are returned. Missing, deleted, or other users' tasks are omitted. An empty result does not mean generation succeeded.\n\nTask states: pending, running, partial, succeeded, failed. Use is_complete as the single signal for polling: stop once it is true.\n\nSong audio is exposed through audio_url and cover_url only after it has been transferred to this site's storage; both are null until then, so wait for is_complete. When generation succeeds but some track audio is unavailable, the task stays succeeded with is_complete true and error_message explains it - do not resubmit the generation.\n\nPolling may also trigger existing timeout failure and compensation handling. Poll every few seconds. After a timeout, query the task rather than automatically submitting another generation request.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"unique_ids":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","maxLength":50},"description":"An array of 1–20 unique_id values returned by submission. Duplicates are removed; only existing, undeleted tasks owned by your account are returned."}},"required":["unique_ids"]},"example":{"unique_ids":["replace_with_unique_id_from_submission"]}}}},"responses":{"200":{"description":"Check the business code: 0 means success; a nonzero value means failure. Successful submission creates a task; it does not mean music is ready.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"code":{"type":"number","const":0},"message":{"type":"string"},"data":{"type":"object","properties":{"tasks":{"type":"array","items":{"type":"object","properties":{"unique_id":{"type":"string"},"status":{"type":"string"},"is_complete":{"type":"boolean"},"created_at":{"anyOf":[{"type":"number"},{"type":"null"}]},"completed_at":{"anyOf":[{"type":"number"},{"type":"null"}]},"error_code":{"anyOf":[{"type":"number"},{"type":"null"}]},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}]},"songs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string"},"audio_url":{"anyOf":[{"type":"string"},{"type":"null"}]},"cover_url":{"anyOf":[{"type":"string"},{"type":"null"}]},"duration":{"anyOf":[{"type":"number"},{"type":"null"}]},"lyrics":{"anyOf":[{"type":"string"},{"type":"null"}]},"style":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","status","audio_url","cover_url","duration","lyrics","style"]}}},"required":["unique_id","status","is_complete","created_at","completed_at","error_code","error_message","songs"]}}},"required":["tasks"]}},"required":["code","message","data"]},{"$ref":"#/components/schemas/Error"}]}}}},"default":{"description":"Authentication, validation, balance, or service error. Check both HTTP status and response code/message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","description":"An API key starting with sk_api_, created in your account."}},"schemas":{"Error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer","not":{"const":0},"description":"Nonzero business error code"},"message":{"type":"string"},"data":{}}}}}}