> ## Documentation Index
> Fetch the complete documentation index at: https://tryunsora.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create song

> Queue a Mureka AI music generation job and poll until complete.

Creates a music generation job powered by [Mureka AI on WaveSpeed](https://wavespeed.ai/models/mureka-ai). Credits are deducted when the job is queued. Poll [Poll music status](/api-reference/music/poll-status) with the returned `generation.id` until `status` is `COMPLETED` or `FAILED`.

For the dashboard UI (models, lyrics, playback, and the global player), see [Music generator](/guides/music-generator/overview) and [Playback & player](/guides/music-generator/playback).

## Headers

| Header            | Required | Description                                                          |
| ----------------- | -------- | -------------------------------------------------------------------- |
| `Authorization`   | Yes      | `Bearer uns_live_*` API key or Clerk JWT                             |
| `Idempotency-Key` | No       | Max 128 chars. Replays the same response for 24h on API key requests |
| `Content-Type`    | Yes      | `application/json`                                                   |

## Request body

<ParamField body="lyrics" type="string" required>
  Song lyrics. Required for song models (`auto`, `mureka-9`, `mureka-8`, `mureka-o2`, `mureka-7.6`). Max 3000 characters.
</ParamField>

<ParamField body="prompt" type="string" required>
  Style prompt — genre, mood, tempo, vocal style. Max 1024 characters.
</ParamField>

<ParamField body="model" type="string">
  Model key. Default: `auto` (Mureka V9).

  | `model`      | Display name      | Credits | Notes                         |
  | ------------ | ----------------- | ------- | ----------------------------- |
  | `auto`       | Mureka V9 (Auto)  | 5       | Full song with lyrics         |
  | `mureka-9`   | Mureka V9         | 5       | Full song with lyrics         |
  | `mureka-8`   | Mureka V8         | 5       | Full song with lyrics         |
  | `mureka-o2`  | Mureka O2         | 6       | Full song with lyrics         |
  | `mureka-7.6` | Mureka V7.6       | 4       | Full song with lyrics         |
  | `mureka-7.5` | Mureka V7.5 (BGM) | 4       | Instrumental background music |
</ParamField>

<ParamField body="output_format" type="string">
  Output audio format: `mp3`, `wav`, or `flac`. Default: `mp3`.
</ParamField>

## Async completion

Poll [Poll music status](/api-reference/music/poll-status) with `generation.id` until `status` is `COMPLETED` or `FAILED`. Webhooks are not supported on the public API.

## Response

```json theme={null}
{
  "success": true,
  "generation": {
    "id": "cm123abc",
    "status": "QUEUED"
  },
  "creditsDeducted": 5,
  "creditsRemaining": 95
}
```

## Example

<RequestExample>
  ```bash Basic theme={null} theme={null}
  curl -X POST "https://mvp.tryunsora.com/api/v1/music-generations/create" \
    -H "Authorization: Bearer uns_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "lyrics": "[Verse]\nNeon rain falls on the city street\nI hear your voice in the midnight heat",
      "prompt": "r&b, slow, passionate, male vocal",
      "model": "auto",
      "output_format": "mp3"
    }'
  ```
</RequestExample>

## Errors

| HTTP  | When                                                    |
| ----- | ------------------------------------------------------- |
| `400` | Missing/invalid lyrics, prompt, model, or output format |
| `401` | Invalid auth                                            |
| `402` | Insufficient credits                                    |
| `404` | User not found                                          |
| `429` | Rate limit exceeded                                     |
| `500` | Server error                                            |


## OpenAPI

````yaml POST /music-generations/create
openapi: 3.1.0
info:
  title: Unsora API
  version: 1.2.0
  description: >-
    Public API for Unsora integrations. Authenticate with Clerk JWT or
    uns_live_* API key. API keys are rate-limited to 60 requests/minute and
    support idempotency keys. Async jobs complete via polling GET
    /image/status/{id}.
servers:
  - url: https://mvp.tryunsora.com/api/v1
    description: Versioned API (recommended)
security: []
tags:
  - name: Clippings
  - name: Connect
  - name: Image Generations
  - name: Music Generations
  - name: Influencer Studio
  - name: Posts
  - name: Thumbnails
  - name: User
  - name: Video Generations
paths:
  /music-generations/create:
    post:
      tags:
        - Music Generations
      summary: Create Mureka AI music generation job
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
            maxLength: 128
          description: >-
            Optional. Replays the original response for 24h when using an API
            key.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMusicGenerationRequest'
      responses:
        '200':
          description: Job queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateMusicGenerationResponse'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Insufficient credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
      security:
        - bearerAuth: []
components:
  schemas:
    CreateMusicGenerationRequest:
      type: object
      properties:
        lyrics:
          type: string
          description: Song lyrics (required for song models, up to 3000 chars)
        prompt:
          type: string
          description: Style prompt — genre, mood, vocal style (up to 1024 chars)
        model:
          type: string
          default: auto
          description: >-
            Model key: auto, mureka-9, mureka-8, mureka-o2, mureka-7.6,
            mureka-7.5
        output_format:
          type: string
          enum:
            - mp3
            - wav
            - flac
          default: mp3
      required:
        - prompt
    CreateMusicGenerationResponse:
      type: object
      properties:
        success:
          type: boolean
        generation:
          type: object
          properties:
            id:
              type: string
            status:
              type: string
          required:
            - id
            - status
        creditsDeducted:
          type: number
        creditsRemaining:
          type: number
      required:
        - success
        - generation
        - creditsDeducted
        - creditsRemaining
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
        error:
          type: string
        code:
          type: string
        message:
          type: string
      required:
        - error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Clerk session JWT or Unsora API key (uns_live_*)

````