{"openapi":"3.0.3","info":{"title":"Comentu (啃馒头) v2 API","version":"2.0.0","description":"Comentu v2 API — 弹幕评论智能预演系统。支持 JWT 和 API Key 双通道认证，提供任务管理、内容预览、批量操作和 Webhook 回调。","contact":{"name":"Comentu Team"}},"servers":[{"url":"/api/v2","description":"v2 API base path"}],"paths":{"/auth/login":{"post":{"tags":["Auth"],"summary":"用户登录","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginRequest"},"example":{"email":"user@example.com","password":"secret123"}}}},"responses":{"200":{"description":"登录成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginResponse"}}}},"400":{"$ref":"#/components/responses/ValidationError"}}}},"/auth/register":{"post":{"tags":["Auth"],"summary":"用户注册","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterRequest"}}}},"responses":{"201":{"description":"注册成功"},"400":{"$ref":"#/components/responses/ValidationError"}}}},"/auth/refresh":{"post":{"tags":["Auth"],"summary":"刷新 JWT Token","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string"}}}}}},"responses":{"200":{"description":"Token 刷新结果"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/tasks":{"post":{"tags":["Tasks"],"summary":"创建任务","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTaskRequest"},"example":{"platform":"bilibili","videoUrl":"https://www.bilibili.com/video/BV1xx","interactionType":"comment","confirmationMode":"manual"}}}},"responses":{"201":{"description":"任务创建成功"},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"}}},"get":{"tags":["Tasks"],"summary":"查询任务列表","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"responses":{"200":{"description":"任务列表"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/tasks/{taskId}":{"get":{"tags":["Tasks"],"summary":"查询单个任务","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"任务详情"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/tasks/batch":{"post":{"tags":["Tasks","Batch"],"summary":"批量创建任务","description":"批量创建多个任务，每个任务独立处理，部分失败不影响其他任务。","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchCreateTasksRequest"},"example":{"tasks":[{"platform":"bilibili","videoUrl":"https://bilibili.com/video/BV1xx"},{"platform":"xiaohongshu","videoUrl":"https://xiaohongshu.com/note/123"}]}}}},"responses":{"200":{"description":"批量创建结果","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchCreateTasksResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/tasks/batch-status":{"post":{"tags":["Tasks","Batch"],"summary":"批量查询任务状态","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["taskIds"],"properties":{"taskIds":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"批量任务状态"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/preview/batch-confirm":{"post":{"tags":["Preview","Batch"],"summary":"批量确认预览","description":"批量确认多个预览会话，支持 autoConfirm 参数。","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchConfirmRequest"},"example":{"sessionIds":["session-1","session-2"],"autoConfirm":true}}}},"responses":{"200":{"description":"批量确认结果"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/webhooks":{"post":{"tags":["Webhooks"],"summary":"注册 Webhook","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookRegisterRequest"},"example":{"url":"https://example.com/webhook","events":["task:status_changed","task:send_verified"],"secret":"my-webhook-secret"}}}},"responses":{"201":{"description":"Webhook 注册成功"},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"}}},"get":{"tags":["Webhooks"],"summary":"查询已注册的 Webhooks","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Webhook 列表"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/webhooks/{webhookId}":{"delete":{"tags":["Webhooks"],"summary":"删除 Webhook","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"webhookId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Webhook 已删除"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/openapi.json":{"get":{"tags":["Documentation"],"summary":"OpenAPI 3.0 规范文档","responses":{"200":{"description":"OpenAPI JSON spec"}}}},"/mcp-tools.json":{"get":{"tags":["Documentation"],"summary":"MCP Tool Definition 文件","responses":{"200":{"description":"MCP tools JSON"}}}},"/docs/agent-guide":{"get":{"tags":["Documentation"],"summary":"Agent 集成文档 (Markdown)","responses":{"200":{"description":"Agent guide in Markdown","content":{"text/markdown":{"schema":{"type":"string"}}}}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token obtained from /auth/login"},"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Long-lived API key (format: ck_live_... or ck_test_...)"}},"schemas":{"LoginRequest":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":1}}},"LoginResponse":{"type":"object","properties":{"token":{"type":"string"},"clientId":{"type":"string"}}},"RegisterRequest":{"type":"object","required":["name","email","password"],"properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":6}}},"CreateTaskRequest":{"type":"object","required":["platform","videoUrl"],"properties":{"platform":{"type":"string","enum":["bilibili","xiaohongshu","douyin","youtube","tiktok"]},"videoUrl":{"type":"string","format":"uri"},"interactionType":{"type":"string","enum":["comment","danmaku","like"],"default":"comment"},"confirmationMode":{"type":"string","enum":["manual","auto","full_auto"],"default":"manual"}}},"BatchCreateTasksRequest":{"type":"object","required":["tasks"],"properties":{"tasks":{"type":"array","items":{"$ref":"#/components/schemas/CreateTaskRequest"},"minItems":1,"maxItems":100}}},"BatchCreateTasksResponse":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"success":{"type":"boolean"},"taskId":{"type":"string"},"error":{"type":"string"}}}},"totalSucceeded":{"type":"integer"},"totalFailed":{"type":"integer"}}},"BatchConfirmRequest":{"type":"object","required":["sessionIds"],"properties":{"sessionIds":{"type":"array","items":{"type":"string"}},"autoConfirm":{"type":"boolean","default":false}}},"WebhookRegisterRequest":{"type":"object","required":["url","events","secret"],"properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"},"description":"Event types to subscribe: task:status_changed, task:preview_ready, task:send_verified, account:health_alert, *"},"secret":{"type":"string","minLength":8,"description":"HMAC-SHA256 signing secret"}}},"StructuredError":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Additional error details"}}}},"responses":{"ValidationError":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"},"example":{"code":"VALIDATION_ERROR","message":"Missing required fields: platform","details":[{"field":"platform","message":"platform is required"}]}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"},"example":{"code":"UNAUTHORIZED","message":"Invalid or expired JWT token","details":null}}}}}}}