# patternGenerate

> Part of the MAP Audio Music API docs. Index of every page: https://map.audio/developers/music-api/llms.txt. OpenAPI document: https://map.audio/developers/music-api/openapi.json.

`POST https://api.map.audio/v1/pattern/generate`

Generate seeded genre patterns with the shared MIDI corpus; optionally write MIDI.

Generate seeded drum and bass patterns in a genre from PAM's MIDI corpus, returned as notes per cell and a MIDI file. It renders no audio, so it is free; render presets to audio with POST /v1/renders. Free: it counts in GET /v1/usage, never in render-minutes. Answers 200 with the finished job when it ends within `Prefer: wait=N` (30 s unless sent, at most 60), else 202 with the job to poll.

Auth: `Authorization: Bearer` with an API key or a map.audio access token. Send `Prefer: wait=N` (0 to 60) to receive the finished job when it ends within N seconds; otherwise the answer is `202` with the job. Send `Idempotency-Key` to retry safely: the same key and body return the same result for 24 hours. MCP tool: `pattern_generate`.

## Body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `genre` | "trap" \| "drill" \| "boombap" \| "dnb" \| "house" \| "techno" \| "idm" | no | Pattern genre. Default `"trap"`. |
| `seed` | integer | no | Reproducible seed; zero draws a random seed. From 0 to 4294967295. Default `0`. |
| `bpm` | number | no | MIDI tempo in beats per minute. From 20 to 400. Default `120`. |
| `bars` | integer | no | Length in bars (1..64): pattern generation uses four beats and defaults to 1; preset rendering uses the preset time signature and defaults to 4. From 1 to 64. |
| `cells` | string | no | Comma-separated PAM cell IDs (1..12); factory roles are used. Default `"1,2,3,6"`. |
| `density` | number | no | Pattern density; absent uses genre default. From 0 to 1. |
| `syncopation` | number | no | Pattern syncopation; absent uses genre default. From 0 to 1. |
| `coherence` | number | no | Cross-cell pattern coherence. From 0 to 1. Default `0.5`. |
| `metadata` | map of string | no | Up to 20 string pairs stored with the job. At most 20 entries. |

## Example

```sh
curl -sS "https://api.map.audio/v1/pattern/generate" \
  -H "Authorization: Bearer $MAP_API_KEY" \
  -H "Map-Version: 2026-11-01" \
  -H "Prefer: wait=30" \
  -H "Content-Type: application/json" \
  -d '{"genre":"house","bpm":124,"bars":4,"seed":42}'
```

### Request: Four bars of house at 124 BPM

```json
{
  "genre": "house",
  "bpm": 124,
  "bars": 4,
  "seed": 42
}
```

### 200: Finished

```json
{
  "object": "job",
  "id": "job_01M6BPRFPCH9EBPY7B6JKM7CE1",
  "operation": "patternGenerate",
  "status": "succeeded",
  "livemode": false,
  "sequence": 3,
  "progress": 1,
  "queuePosition": null,
  "createdAt": "2026-11-01T14:03:31.512Z",
  "startedAt": "2026-11-01T14:03:33.104Z",
  "finishedAt": "2026-11-01T14:03:41.877Z",
  "estimate": {
    "audioSeconds": 0,
    "renderMinutes": 0
  },
  "result": {
    "outputs": [
      {
        "role": "midi",
        "name": null,
        "cell": null,
        "file": "file_01M6BPRMNR7PYGFNA66BX2YJ8M",
        "sha256": "13d41d922519699fc14a7587130eceee7d0f149414350000578de1564866a0d4",
        "bytes": 1214,
        "format": "mid",
        "sampleRate": null,
        "durationSeconds": null,
        "url": "https://api.map.audio/v1/download/file_01M6BPRMNR7PYGFNA66BX2YJ8M?expires=1793545422&signature=GQ2GkmPjqXuxxBSSM4NKBCY7OjU7w3YSeZBrCoxxtbY",
        "expiresAt": "2026-11-01T15:03:42.000Z"
      }
    ],
    "seed": 42,
    "command": {
      "ok": true,
      "seed": 42,
      "genre": "house",
      "bpm": 124,
      "lengthBeats": 16,
      "roles": {
        "1": "kick",
        "2": "snare",
        "3": "hihat",
        "6": "bass"
      },
      "corpus": true,
      "midiPath": "file_01M6BPRMNR7PYGFNA66BX2YJ8M"
    },
    "provenance": {
      "object": "provenance",
      "id": "prov_01M6BPRVA8ZC7F7J737SQ0EPN2",
      "jobId": "job_01M6BPRFPCH9EBPY7B6JKM7CE1",
      "createdAt": "2026-11-01T14:03:41.877Z",
      "engine": {
        "product": "pam",
        "version": null,
        "runtime": "native-linux-x86_64",
        "image": "registry.cloudflare.com/c7c2e61448617e81ced650f444fb6787/pam-render@sha256:5c5ffe3fabc103e277280fbd65a08988d31361f00fe7857e36f603d67bcec42d"
      },
      "seed": 42,
      "presets": [],
      "packs": [],
      "userFiles": [],
      "inputs": [],
      "outputs": [
        {
          "file": "file_01M6BPRMNR7PYGFNA66BX2YJ8M",
          "sha256": "13d41d922519699fc14a7587130eceee7d0f149414350000578de1564866a0d4"
        }
      ],
      "planner": null,
      "contracts": {
        "api": "2026-11-01",
        "pam.cli": 1
      },
      "aiModels": [],
      "audioByModel": false,
      "license": {
        "id": "lic_api_prototype_test",
        "commercialUse": false,
        "attribution": true
      },
      "kid": "6c2f0a9d4b7e1358",
      "signature": "ed25519:LEVZHpOHj8BMGZgJh-_Y7SmKbqDlBDR8LqY-XelU6GYK8lntZqg3rRK4b3BH8cy25bK0iWzOXFXmkiGHEYue7A"
    }
  },
  "error": null,
  "usage": {
    "renderMinutes": 0,
    "audioSeconds": 0,
    "computeMs": 6273
  },
  "metadata": {},
  "urls": {
    "self": "https://api.map.audio/v1/jobs/job_01M6BPRFPCH9EBPY7B6JKM7CE1",
    "events": "https://api.map.audio/v1/jobs/job_01M6BPRFPCH9EBPY7B6JKM7CE1/events",
    "cancel": "https://api.map.audio/v1/jobs/job_01M6BPRFPCH9EBPY7B6JKM7CE1/cancel"
  }
}
```

### 202: Still running

```json
{
  "object": "job",
  "id": "job_01M6BPRFPCH9EBPY7B6JKM7CE1",
  "operation": "patternGenerate",
  "status": "running",
  "livemode": false,
  "sequence": 2,
  "progress": 0,
  "queuePosition": null,
  "createdAt": "2026-11-01T14:03:31.512Z",
  "startedAt": "2026-11-01T14:03:33.104Z",
  "finishedAt": null,
  "estimate": {
    "audioSeconds": 0,
    "renderMinutes": 0
  },
  "result": null,
  "error": null,
  "usage": null,
  "metadata": {},
  "urls": {
    "self": "https://api.map.audio/v1/jobs/job_01M6BPRFPCH9EBPY7B6JKM7CE1",
    "events": "https://api.map.audio/v1/jobs/job_01M6BPRFPCH9EBPY7B6JKM7CE1/events",
    "cancel": "https://api.map.audio/v1/jobs/job_01M6BPRFPCH9EBPY7B6JKM7CE1/cancel"
  }
}
```

### 400: Invalid request

```json
{
  "error": {
    "type": "invalid_request",
    "code": "invalid_request",
    "message": "genre must be one of trap, drill, boombap, dnb, house, techno or idm; got \"polka\".",
    "param": "genre",
    "retryable": false,
    "jobId": null,
    "docUrl": "https://map.audio/developers/music-api/errors#invalid_request",
    "requestId": "9a3f7c2e5b1d8f40-LHR"
  }
}
```

## Responses

- `200`: The finished job: `result.outputs` link each file it wrote and `result.command` is the engine's own result.
- `202`: The job, still running when `Prefer: wait` ran out; poll `urls.self`.
- `400`: Invalid request
- `default`: Any other error: `error.code` names it, `error.param` the field at fault, and `error.docUrl` its entry in the error catalogue.

## Errors

- [`invalid_request`](https://map.audio/developers/music-api/errors#invalid_request)
- [`unsupported_media_type`](https://map.audio/developers/music-api/errors#unsupported_media_type)
- [`payload_too_large`](https://map.audio/developers/music-api/errors#payload_too_large)
- [`terms_required`](https://map.audio/developers/music-api/errors#terms_required)
- [`concurrency_limit`](https://map.audio/developers/music-api/errors#concurrency_limit)
- [`idempotency_key_reused`](https://map.audio/developers/music-api/errors#idempotency_key_reused)
- [`idempotency_in_flight`](https://map.audio/developers/music-api/errors#idempotency_in_flight)
- [`queue_unavailable`](https://map.audio/developers/music-api/errors#queue_unavailable)