Sign in

v1

latestOpenAPI 3.0.32026-07-241112213.6 KB

Submit Task

Submit an asynchronous AI music generation task. Returns a taskId for polling results via the Query Task API.Models: Supports Topview Music and Minimax Music 2.6 (pass the displayName; case-insensitive).Parameter rules:- When instrumental=true (instrumental only), styles is required and lyrics is ignored and not sent to the backend- When instrumental=false (with vocals), at least one of lyrics or styles must be provided- When enhancePrompt=true, styles is required; the system asynchronously enhances the style description before submitting generation- When referenceAudio is provided, audio format and duration are validated before generation is submittedCredits: Charged after task completion. Use costCredit in the query response to check consumption.Common error codes:- 4012: Invalid model- 4013: styles is required when instrumental=true- 4014: At least one of lyrics or styles is required when instrumental=false- 4015: lyrics exceeds maximum length- 4016: styles exceeds maximum length- 4017~4021: Invalid referenceAudio parameter/format/duration/size/clip range- 4022: Non-empty styles is required when enhancePrompt is enabled- 4100: Insufficient credits

post/v1/common_task/ai_music/task/submit

Headers

Topview-Uidstring required

User ID

Authorizationstring required

API key for authentication. Format: Bearer {apiKey}

Request body

model'Topview Music' | 'Minimax Music 2.6' required

AI music model name (required). Allowed values: Topview Music, Minimax Music 2.6 (case-insensitive)

instrumentalboolean

Whether to generate instrumental music (no vocals). When true, styles is required and lyrics is ignored. When false or omitted, at least one of lyrics or styles must be provided

lyricsstring

Lyrics text (conditionally required). When instrumental=false, at least one of lyrics or styles must be non-empty; ignored when instrumental=true. Max length varies by model: Topview Music 5000 chars, Minimax Music 2.6 3500 chars

stylesstring

Music style description (conditionally required). Required when instrumental=true; when instrumental=false, at least one of lyrics or styles must be non-empty; required when enhancePrompt=true. Max length varies by model: Topview Music 1000 chars, Minimax Music 2.6 2000 chars

enhancePromptboolean

Whether to asynchronously enhance the styles description. When enabled, the system calls an LLM to optimize the style text before submitting generation; requires non-empty styles

boardIdstring

Associated Board ID (optional). When provided, a corresponding boardTask is created in aigc-backend; the response may include boardId and boardTaskIds

noticeUrlstring

Callback URL on task completion (optional). When configured, the response includes noticeUuid and the system sends a notification to this URL when the task finishes

Example request

{
  "model": "Topview Music",
  "lyrics": "This is a test music",
  "styles": "Hip Hop, Boom Bap",
  "enhancePrompt": true,
  "referenceAudio": {
    "fileId": "file_abc123",
    "fileName": "demo.mp3",
    "clipEnd": 30
  },
  "boardId": "board_xxx",
  "noticeUrl": "https://example.com/topview/callback"
}

Response

Accepted successfully (task created and queued; poll the query API for execution result)

codestring

Business status code; 200 on success

messagestring

Status message

Example response

{
  "code": "200",
  "message": "Success",
  "result": {
    "taskId": "6f4b5a8c9d0e1f2a3b4c5d6",
    "status": "success"
  }
}