---
title: "Submit Task"
method: POST
path: "/v1/common_task/ai_music/task/submit"
---

# Submit Task

`POST /v1/common_task/ai_music/task/submit`

Submit an asynchronous AI music generation task. Returns a `taskId` for polling results via the [Query Task](https://docs.topview.ai/update/reference/ai-music-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 submitted**Credits**: 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

## Headers

- `Topview-Uid` string, required
- `Authorization` string, required

## Request body

- object
  - `model` 'Topview Music' | 'Minimax Music 2.6', required — AI music model name (required). Allowed values: `Topview Music`, `Minimax Music 2.6` (case-insensitive)
  - `instrumental` boolean — 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
  - `lyrics` string — 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
  - `styles` string — 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
  - `enhancePrompt` boolean — 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`
  - `referenceAudio` object — Reference audio (optional). When provided, audio format, duration, and size are validated before the generation task is submitted
    - `fileId` string, required — Reference audio fileId (required). Must be of type audio with a format supported by the model. Topview Music: mp3/wav/flac/m4a/ogg/oga; Minimax Music 2.6: mp3/wav
    - `fileName` string — Reference audio file name (optional). Defaults to `{fileId}.{extension}` when omitted
    - `clipStart` number, float — Clip start time in seconds (optional). Defaults to 0 when omitted; must be ≥ 0
    - `clipEnd` number, float — Clip end time in seconds (optional). Defaults to the original audio duration when omitted; must be > clipStart and > 0. Topview Music reference duration must be in [20, 120] seconds; Minimax Music 2.6 in [6, 500] seconds
  - `boardId` string — Associated Board ID (optional). When provided, a corresponding boardTask is created in aigc-backend; the response may include boardId and boardTaskIds
  - `noticeUrl` string — 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

## Response `200`

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

- object
  - `code` string — Business status code; 200 on success
  - `message` string — Status message
  - `result` object — Submission result (TaskPair)
    - `taskId` string — Task ID for polling via the query API
    - `status` 'init' | 'running' | 'success' | 'fail' — Immediate acceptance status after submission; always `success` on acceptance. Use the query API for execution status (init/running/success/fail)
    - `errorMsg` string — Error message on submission failure (may be present when acceptance fails)
    - `subTaskId` string — Sub-task ID (returned in some business scenarios; usually not returned by this API)
    - `boardTaskIds` string[] — Board sub-task ID list when associated with a Board
    - `boardId` string — Board ID when associated with a Board
    - `noticeUuid` string — Async callback notification UUID (returned when noticeUrl is configured in the request body)

---

[API](https://skmtc.net/topview/apis/image-character-swap-apis-editable-in-readme.md) · [All operations](https://skmtc.net/topview/apis/image-character-swap-apis-editable-in-readme/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/topview/image-character-swap-apis-editable-in-readme/versions/83cd46ca7859/schema)