---
title: "Create a music generation task"
method: POST
path: "/api/v1/music"
tags: ["Generation"]
---

# Create a music generation task

`POST /api/v1/music`

## Request

- Base URL: `https://viewmax.studio`
- URL: `https://viewmax.studio/api/v1/music`
- Auth: HTTP bearer

Renders synchronously: the response usually already has `status: "success"` and the track in `taskUrls`. Costs `max(60, ceil(duration_seconds))` credits (default 60 s).

## Headers

- `Idempotency-Key` string

## Request body

- CreateMusicRequest
  - `prompt` string, required: Track description. When `options.style` or `options.title` is set, the prompt is treated as lyrics.
  - `options` object: `options.duration` and `options.music_length_ms` are rejected (400); use `duration_seconds`.
    - `duration_seconds` number: JSON number. Cost: `max(60, ceil(duration_seconds))` credits.
    - `instrumental` boolean: `true` for no vocals.
    - `style` string: Genre or mood. Makes the prompt be treated as lyrics; do not also send `lyrics`.
    - `title` string: Song title. Also makes the prompt be treated as lyrics.
    - `lyrics` string

## Response `200`

Task created, or the existing task for a repeated `Idempotency-Key`.

- object
  - `code` 0, required
  - `message` 'ok', required
  - `data` Task, required: Generation task. Returned by every create endpoint and by GET /api/v1/tasks/{taskId}.
    - `id` string, required: Task id. Poll GET /api/v1/tasks/{taskId} with it.
    - `status` 'pending' | 'processing' | 'success' | 'failed' | 'canceled', required: `pending`/`processing`: keep polling. `success`: read `taskUrls`. `failed`/`canceled`: terminal, credits refunded.
    - `mediaType` 'video' | 'image' | 'music' | 'audio', required
    - `scene` string: Mode or scene, e.g. `text-to-video`, `text-to-image`, `text-to-music`, `text-to-speech`, `text-to-sound-effects`.
    - `model` string: Model identifier used for the job. May differ from the catalog id sent in the request.
    - `prompt` string
    - `options` string, nullable: JSON-encoded options as priced and submitted, including filled-in defaults and `mode` for video.
    - `taskUrls` string[], required: Result URLs. Empty until the task succeeds.
    - `costCredits` integer, required: Credits charged. `0` when a plan allowance covered it.
    - `waivedCredits` integer: Normal price waived by a plan allowance; otherwise `0`.
    - `fairUseKey` string, nullable: Plan allowance slot used by this task, or `null`.
    - `taskInfo` string, nullable: JSON string. While pending/processing/success it holds job diagnostics whose shape is not stable. On `failed`/`canceled` it is `{"errorCode","error","errorMessage"}`; `errorCode` is one of `insufficient_credits`, `auth_required`, `rate_limited`, `request_cancelled`, `provider_unavailable`, `invalid_input`, `content_rejected`, `busy`, `duplicate_request`, `generic`. `errorMessage` carries the provider's reason only for `invalid_input`.
    - `taskResult` string, nullable: JSON string. Same failure payload as `taskInfo` on `failed`/`canceled`; otherwise job diagnostics with no stable shape.
    - `taskId` string, nullable: Upstream job id (diagnostic only).
    - `createdAt` string, date-time
    - `updatedAt` string, date-time
    - `userId` string
    - `creditId` string, nullable
    - `visibility` string
    - `deletedAt` string, date-time, nullable

## Other responses

- `400`: `invalid_request`: fix the request using `message` before retrying (includes disabled or offline models). `content_rejected`: change the prompt or media. When the provider rejected an accepted task, `error.task_id` is set and the task is failed and refunded.
- `401`: Missing or invalid API key (`code: -1001`).
- `402`: Balance below the task cost (`code: -1002`). No task was created; do not retry until credits are added.
- `500`: Provider or server failure. With `error.task_id` the task failed and was refunded: retry once. When the hint says the outcome is unknown, the task stays `pending` with the charge kept: poll it instead of retrying.
- `503`: External content-safety check temporarily unavailable. Retry after a short delay.

---

[API](https://skmtc.dev/viewmax/apis/viewmax-studio-api.md) · [All operations](https://skmtc.dev/viewmax/apis/viewmax-studio-api/llms.txt) · [OpenAPI document](https://skmtc.dev/viewmax/apis/viewmax-studio-api/revisions/c4f378e09f44?raw)