# Create a music generation job

Submit a new AI music generation request. Returns `202 Accepted` with a queued job you can poll for status and result.

Supply an `Idempotency-Key` header (or `idempotency_key` in the body) so a retried request returns the same job instead of generating twice. The header takes precedence over the body field.

## Path parameters

**`organization_id`** string required

The organization the job is scoped to. The caller must belong to it.

## Headers

**`Idempotency-Key`** string optional

A repeat request with the same key (and the same org/user) returns the existing job instead of creating a duplicate. Takes precedence over the body `idempotency_key`.

## Request Body

**`engine`** string required

Internal engine key to generate with (from [List available music engines](/docs/api-reference/music/engines)).

**`prompt`** string required

Natural-language description of the music to generate (genre, mood, instruments, structure).

**`duration_seconds`** integer required

Requested track length in seconds. Must be positive and within the selected engine's maximum.

**`mode`** string optional · Defaults to `creation`

Generation mode: `creation` produces a single complete track; `focus` produces chained focus-friendly segments.

**`instrumental`** boolean optional · Defaults to `false`

When `true`, generate instrumental-only audio with no vocals.

**`lyrics`** string optional

User-provided lyrics. Only accepted when the engine supports lyrics input and the track is not instrumental.

**`seed_track_id`** string optional

Id of an existing track (`mtrack_`-prefixed) to seed/continue from.

**`style_tags`** array optional

Style/genre tags to steer the generation.

**`title`** string optional

Human-friendly title for the resulting track.

**`idempotency_key`** string optional

Idempotency key (the `Idempotency-Key` header takes precedence when both are present).

## Returns

A music generation job object. On success the `track` summary and `playback_url` are populated.

**`id`** string · Job id (`mgen_`-prefixed).

**`status`** string · One of `queued`, `running`, `succeeded`, `failed`, `cancelled`, `refused`.

**`progress`** integer · Generation progress, 0–100.

**`engine`** string · Internal engine key the job targets.

**`mode`** string · `creation` or `focus`.

**`created_at`** string · When the job was created (UTC).

**`result_track_id`** string · Id of the produced track once succeeded.

**`error_message`** string · User-safe error description when the job failed.

**`refusal_reason`** string · Reason the request was refused, when `status` is `refused`.

**`playback_url`** string · Short-TTL signed URL for the master audio, present only on a succeeded job.

**`track`** object · Embedded [track summary](/docs/api-reference/music/get-track), present only on a succeeded job.

Example

```bash cURL
curl -X POST "https://api.aitronos.com/v1/music/org_abc123/generations" \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Idempotency-Key: gen-2026-06-28-001" \
  -H "Content-Type: application/json" \
  -d '{
    "engine": "studio",
    "prompt": "Upbeat lo-fi hip-hop with mellow piano and vinyl crackle",
    "duration_seconds": 120,
    "instrumental": true,
    "title": "Late Night Study"
  }'
```


```python Python SDK
from aitronos import Aitronos  # pip install aitronos-sdk

client = Aitronos(api_key="your-api-key")

job = client.post(
    "/v1/music/org_abc123/generations",
    json={
        "engine": "studio",
        "prompt": "Upbeat lo-fi hip-hop with mellow piano",
        "duration_seconds": 120,
        "instrumental": True,
    },
    headers={"Idempotency-Key": "gen-2026-06-28-001"},
)
print(job["id"], job["status"])
```


```python Python
import os
import requests

api_key = os.environ["FREDDY_API_KEY"]

response = requests.post(
    "https://api.aitronos.com/v1/music/org_abc123/generations",
    headers={
        "X-API-Key": api_key,
        "Idempotency-Key": "gen-2026-06-28-001",
    },
    json={
        "engine": "studio",
        "prompt": "Upbeat lo-fi hip-hop with mellow piano",
        "duration_seconds": 120,
        "instrumental": True,
    },
)
print(response.json()["id"])
```


```javascript JavaScript
const apiKey = process.env.FREDDY_API_KEY;

const response = await fetch('https://api.aitronos.com/v1/music/org_abc123/generations', {
  method: 'POST',
  headers: {
    'X-API-Key': apiKey,
    'Idempotency-Key': 'gen-2026-06-28-001',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    engine: 'studio',
    prompt: 'Upbeat lo-fi hip-hop with mellow piano',
    duration_seconds: 120,
    instrumental: true,
  }),
});

const job = await response.json();
console.log(job.id, job.status);
```

**Response:**


```json 202 Accepted
{
  "id": "mgen_2f8b1c4e9a7d",
  "status": "queued",
  "progress": 0,
  "engine": "studio",
  "mode": "creation",
  "created_at": "2026-06-28T10:30:00Z",
  "result_track_id": null,
  "error_message": null,
  "refusal_reason": null,
  "playback_url": null,
  "track": null
}
```

Errors

```json 401 Unauthorized
{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_REQUIRED",
    "message": "Authentication required. Please provide a valid API key.",
    "system_message": "Missing or invalid authorization header",
    "type": "authentication_error",
    "status": 401,
    "details": {},
    "trace_id": "req_abc123xyz",
    "timestamp": "2026-06-28T10:30:00Z"
  }
}
```


```json 403 Forbidden
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "You do not have permission to access this resource.",
    "system_message": "USE_MUSIC_GENERATION capability required",
    "type": "authorization_error",
    "status": 403,
    "details": {},
    "trace_id": "req_def456uvw",
    "timestamp": "2026-06-28T10:30:00Z"
  }
}
```


```json 422 Validation Error
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request contains invalid parameters.",
    "system_message": "duration_seconds exceeds the engine maximum",
    "type": "validation_error",
    "status": 422,
    "details": { "field": "duration_seconds" },
    "trace_id": "req_ghi789rst",
    "timestamp": "2026-06-28T10:30:00Z"
  }
}
```

## Related Resources

- [Get a generation job](/docs/api-reference/music/get-generation)
- [List generation jobs](/docs/api-reference/music/list-generations)
- [Cancel a generation job](/docs/api-reference/music/cancel-generation)
- [List available music engines](/docs/api-reference/music/engines)