{"openapi": "3.1.0", "info": {"title": "MuziekMakenMetAI Developer API", "version": "1.0.0", "description": "Asynchrone API voor originele muziekgeneratie met eigen opgeslagen resultaten."}, "servers": [{"url": "https://muziekmakenmetai.nl/api/v1"}], "components": {"securitySchemes": {"bearerAuth": {"type": "http", "scheme": "bearer"}}, "schemas": {"Generation": {"type": "object", "properties": {"id": {"type": "string", "format": "uuid"}, "object": {"const": "music_generation"}, "status": {"enum": ["queued", "processing", "succeeded", "failed"]}, "model": {"enum": ["music-v1", "music-v1-pro", "music-v2", "music-v2-mini", "music-v2-wild"]}, "created_at": {"type": "string", "format": "date-time"}, "completed_at": {"type": ["string", "null"], "format": "date-time"}, "tracks": {"type": "array", "items": {"type": "object", "properties": {"id": {"type": "string"}, "title": {"type": "string"}, "duration_seconds": {"type": ["number", "null"]}, "audio_url": {"type": "string", "format": "uri"}, "image_url": {"type": ["string", "null"], "format": "uri"}}, "required": ["id", "title", "duration_seconds", "audio_url", "image_url"]}}}, "required": ["id", "object", "status", "model", "created_at", "completed_at", "tracks"]}, "GenerationInput": {"type": "object", "additionalProperties": false, "properties": {"model": {"type": "string", "enum": ["music-v1", "music-v1-pro", "music-v2", "music-v2-mini", "music-v2-wild"], "default": "music-v1", "description": "music-v2 is ons nieuwste model en de aanrader: natuurlijkere zang, rijkere details en eigen stemmen. music-v2-mini is sneller, music-v2-wild is gewaagder. music-v1 en music-v1-pro zijn de vorige generatie en blijven werken. Alle modellen kosten \u00e9\u00e9n credit per generatie."}, "prompt": {"type": "string", "maxLength": 5000, "description": "Maximaal 500 tekens in de standaardmodus en 5.000 tekens in custom_mode."}, "custom_mode": {"type": "boolean", "default": false, "description": "False: prompt is een muziekbeschrijving. True: prompt is de volledige songtekst en style is verplicht."}, "instrumental": {"type": "boolean", "default": false, "description": "Vraag een track zonder zang."}, "style": {"type": "string", "maxLength": 1000, "description": "Verplicht in custom_mode; beschrijf genre, instrumenten, tempo en sfeer."}, "title": {"type": "string", "maxLength": 80}, "language": {"type": "string", "maxLength": 40, "default": "Nederlands", "examples": ["Nederlands", "Engels", "Duits", "Frans", "Spaans"], "description": "Volledige taalnaam. Andere talen zijn toegestaan; de kwaliteit kan per taal verschillen."}, "vocal_gender": {"type": "string", "enum": ["male", "female"], "description": "Alleen in custom_mode en alleen relevant voor tracks met zang."}, "style_weight": {"type": "number", "minimum": 0, "maximum": 1, "description": "Alleen in custom_mode. Hogere waarden volgen style sterker."}, "creativity": {"type": "number", "minimum": 0, "maximum": 1, "description": "Alleen in custom_mode. Hogere waarden geven meer variatie."}, "audio_weight": {"type": "number", "minimum": 0, "maximum": 1, "description": "Alleen in custom_mode. Gewicht van gekoppelde persona-audio."}, "duration_seconds": {"type": "integer", "minimum": 10, "maximum": 360, "description": "Alleen beschikbaar met music-v1-pro of een music-v2-model en custom_mode=true."}, "variety": {"type": "integer", "minimum": 0, "maximum": 4, "default": 1, "description": "Alleen in custom_mode en alleen met music-v2-modellen. 0 = strikt volgens prompt en style, 1 = standaard balans, 2 = wat meer variatie, 3 = duidelijk losser met de input, 4 = maximaal verrassend."}, "negative_tags": {"type": "array", "items": {"type": "string"}, "description": "Alleen in custom_mode; alle waarden samen maximaal 300 tekens."}, "persona_id": {"type": "string", "description": "Eigen persona van dit account; alleen in custom_mode."}, "persona_type": {"type": "string", "enum": ["style", "voice"], "description": "Vereist persona_id. Zonder persona_type gebruikt de API style. Type voice werkt alleen met music-v2-modellen."}}, "required": ["prompt"], "allOf": [{"if": {"properties": {"custom_mode": {"const": true}}, "required": ["custom_mode"]}, "then": {"properties": {"prompt": {"maxLength": 5000}}}, "else": {"properties": {"prompt": {"maxLength": 500}}}}]}, "Error": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string"}, "message": {"type": "string"}}, "required": ["code", "message"]}}, "required": ["error"]}, "Account": {"type": "object", "properties": {"object": {"const": "developer_account"}, "key_prefix": {"type": "string"}, "credits": {"type": "integer", "description": "Totaal API-inzetbaar saldo: API-credits plus niet-verlopende songcredits. Exclusief maandcredits."}, "api_credits": {"type": "integer", "description": "Credits die alleen in de API geldig zijn."}, "song_credits": {"type": "integer", "description": "Niet-verlopende songcredits die ook in de API werken. Maandcredits van Plus en Pro zijn uitgesloten."}, "webhook_configured": {"type": "boolean"}, "requests_per_minute": {"type": "integer"}}, "required": ["object", "key_prefix", "credits", "api_credits", "song_credits", "webhook_configured", "requests_per_minute"]}, "WebhookEndpoint": {"type": "object", "properties": {"object": {"const": "webhook_endpoint"}, "url": {"type": ["string", "null"], "format": "uri"}, "signing_secret": {"type": ["string", "null"]}}, "required": ["object", "url", "signing_secret"]}, "WebhookEvent": {"type": "object", "properties": {"id": {"type": "string", "format": "uuid"}, "type": {"enum": ["music.generation.succeeded", "music.generation.failed"]}, "data": {"$ref": "#/components/schemas/Generation"}}, "required": ["id", "type", "data"]}}}, "security": [{"bearerAuth": []}], "paths": {"/music/generations/": {"post": {"summary": "Start een muziekgeneratie", "parameters": [{"name": "Idempotency-Key", "in": "header", "required": true, "schema": {"type": "string", "maxLength": 128}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GenerationInput"}}}}, "responses": {"202": {"description": "Generatie gestart", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Generation"}}}}, "200": {"description": "Bestaande generatie voor dezelfde Idempotency-Key en requestbody", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Generation"}}}}, "4XX": {"description": "Requestfout", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/music/generations/{id}/": {"get": {"summary": "Lees de status en eigen assets", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "Actuele generatie", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Generation"}}}}}}}, "/account/": {"get": {"summary": "Lees credits en limieten", "responses": {"200": {"description": "Account", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Account"}}}}}}}, "/webhook/": {"put": {"summary": "Stel \u00e9\u00e9n publieke HTTPS-webhook in", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "properties": {"url": {"type": "string", "format": "uri"}}, "required": ["url"]}}}}, "responses": {"200": {"description": "Webhook en signing secret", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookEndpoint"}}}}}}}, "/capabilities/": {"get": {"security": [], "summary": "Lees modellen en parameters", "responses": {"200": {"description": "Capabilities"}}}}}, "webhooks": {"generationStatus": {"post": {"summary": "Terminaal generatie-event", "description": "Bereken de hex HMAC-SHA256 van `<timestamp>.<exacte ruwe UTF-8 requestbody>` met het signing secret. De signatureheader bevat `sha256=<hex>`. Gebruik de event-UUID voor deduplicatie; de eventnaam staat in het JSON-veld `type`.", "parameters": [{"name": "X-MMMAI-Event", "in": "header", "required": true, "description": "Unieke event-UUID voor deduplicatie.", "schema": {"type": "string", "format": "uuid"}}, {"name": "X-MMMAI-Timestamp", "in": "header", "required": true, "schema": {"type": "string"}}, {"name": "X-MMMAI-Signature", "in": "header", "required": true, "schema": {"type": "string"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookEvent"}}}}, "responses": {"200": {"description": "Ontvangen"}}}}}}