{"openapi":"3.1.0","info":{"title":"ПеснеГен Agent and MCP API","version":"1.0.0","description":"Public discovery plus authenticated Job-based song generation and audio processing APIs.","contact":{"email":"support@pesnegen.ru"}},"servers":[{"url":"https://pesnegen.ru","description":"Production"}],"tags":[{"name":"Discovery","description":"Public, no API key required"},{"name":"MCP","description":"Scoped user key or authenticated web session required for execution"}],"paths":{"/api/mcp/v1/tools":{"get":{"tags":["Discovery"],"operationId":"listPesnegenTools","summary":"List all PesneGen tools and JSON input schemas","security":[],"responses":{"200":{"description":"Public tool catalog","content":{"application/json":{"schema":{"type":"object","required":["tools","authentication"],"properties":{"tools":{"type":"array","items":{"$ref":"#/components/schemas/Tool"}},"authentication":{"type":"object"}}}}}}}}},"/api/mcp/v1/call":{"post":{"tags":["MCP"],"operationId":"callPesnegenTool","summary":"Call a tool through the existing REST gateway","description":"Use application/json for text tools or multipart/form-data with fields tool, input and file for audio Jobs. Paid calls reserve API credits and require Idempotency-Key; success is recorded only after the processor returns a result.","security":[{"bearerAuth":[]}],"parameters":[{"in":"header","name":"Idempotency-Key","required":false,"schema":{"type":"string"},"description":"Required for paid calls"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestToolCall"}},"multipart/form-data":{"schema":{"type":"object","required":["tool","file"],"properties":{"tool":{"type":"string","enum":["midiToSong","mp3ToMidi","midiToSheetMusic","audioToSheetMusic","convertAudio","detectChords","extractNotes","makeMinusovka","removeVocal","removeVocals","splitStems","makeKaraoke","makeReels","aiDirectorFromText","applyEffects","removeNoise","masterTrack","openEditor","analyzeTrack","generateSongFromText"]},"input":{"type":"string","description":"JSON-encoded input object"},"file":{"type":"string","format":"binary"},"idempotencyKey":{"type":"string"}}}}}},"responses":{"200":{"description":"Job submission, requires_action state, or completed synchronous result"},"400":{"description":"Invalid input or missing explicit confirmation"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing API scope"},"409":{"description":"Idempotency request still in progress"}}}},"/api/mcp/v1/me":{"get":{"tags":["MCP"],"operationId":"getMcpAccount","summary":"Return the authenticated MCP account and key metadata","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Account metadata"},"401":{"description":"Unauthorized"}}}},"/api/mcp/v1/usage":{"get":{"tags":["MCP"],"operationId":"getMcpUsage","summary":"Return the usage ledger summary","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Usage summary"},"401":{"description":"Unauthorized"}}}},"/api/mcp/v1/jobs/{jobId}":{"get":{"tags":["MCP"],"operationId":"getMcpJob","summary":"Get a user-owned job and result URLs","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"jobId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Job state"},"404":{"description":"Job not found"}}}},"/api/mcp/v1/jobs/{jobId}/cancel":{"post":{"tags":["MCP"],"operationId":"cancelMcpJob","summary":"Cancel a user-owned queued or running job","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"jobId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cancellation state"},"404":{"description":"Job not found"}}}},"/mcp":{"post":{"tags":["MCP"],"operationId":"mcpStreamableHttp","summary":"MCP Streamable HTTP JSON-RPC endpoint","description":"Supports initialize, ping, tools/list, tools/call, resources/list and resources/read. Discovery is public; execute tools require bearer authentication.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcRequest"}}}},"responses":{"200":{"description":"JSON-RPC response"},"202":{"description":"Notification accepted"},"403":{"description":"Origin rejected"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"pg_live_...","description":"User-owned scoped PesneGen API key"}},"schemas":{"Tool":{"type":"object","required":["name","title","description","inputSchema","requiredScope","defaultMode"],"properties":{"name":{"type":"string","enum":["midiToSong","mp3ToMidi","midiToSheetMusic","audioToSheetMusic","convertAudio","detectChords","extractNotes","makeMinusovka","removeVocal","removeVocals","splitStems","makeKaraoke","makeReels","aiDirectorFromText","applyEffects","removeNoise","masterTrack","openEditor","analyzeTrack","generateSongFromText"]},"title":{"type":"string"},"description":{"type":"string"},"inputSchema":{"type":"object"},"requiredScope":{"type":"string"},"defaultMode":{"type":"string","enum":["execute"]},"tokenCost":{"type":"number"},"creditCost":{"type":"number","description":"Base cost in separate API credits; held while the Job is active"},"jobBased":{"type":"boolean"},"asynchronous":{"type":"boolean"},"publicUrl":{"type":"string"}},"examples":[{"name":"midiToSong","title":"MIDI в песню","description":"Создаёт Job для песни из MIDI; если нужен редактор, Job вернёт requires_action.","inputSchema":{"type":"object","properties":{},"additionalProperties":false},"requiredScope":"tools:audio:write","defaultMode":"execute","tokenCost":0,"creditCost":1,"jobBased":true,"asynchronous":true,"publicUrl":"/midi-v-pesnyu","multipartFileSupported":true,"guestPreview":true,"terminalBilling":true,"requiresExplicitConfirmation":false},{"name":"mp3ToMidi","title":"MP3 в MIDI","description":"Создаёт Job распознавания нот и экспорта аудио в MIDI.","inputSchema":{"type":"object","properties":{},"additionalProperties":false},"requiredScope":"tools:audio:write","defaultMode":"execute","tokenCost":0,"creditCost":1,"jobBased":true,"asynchronous":true,"publicUrl":"/konverter-mp3-v-midi","multipartFileSupported":true,"guestPreview":true,"terminalBilling":true,"requiresExplicitConfirmation":false}]},"RestToolCall":{"type":"object","required":["tool","input"],"properties":{"tool":{"type":"string","enum":["midiToSong","mp3ToMidi","midiToSheetMusic","audioToSheetMusic","convertAudio","detectChords","extractNotes","makeMinusovka","removeVocal","removeVocals","splitStems","makeKaraoke","makeReels","aiDirectorFromText","applyEffects","removeNoise","masterTrack","openEditor","analyzeTrack","generateSongFromText"]},"input":{"type":"object","additionalProperties":true},"idempotencyKey":{"type":"string"}}},"JsonRpcRequest":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"null"}]},"method":{"type":"string"},"params":{"type":"object","additionalProperties":true}}}}}}