{"openapi":"3.1.0","info":{"title":"lehuoAI Hono API","version":"0.1.0"},"components":{"schemas":{"DemoTask":{"type":"object","properties":{"name":{"type":"string","minLength":1,"example":"lorem"},"slug":{"type":"string","minLength":1,"example":"lorem-1"},"description":{"type":"string","example":"任务描述（可选）"},"completed":{"type":"boolean","default":false,"example":false},"due_date":{"type":"string","format":"date-time","example":"2026-01-01T00:00:00.000Z"}},"required":["name","slug","due_date"]},"ZodIssue":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}}},"required":["code","message","path"]},"ValidationErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","enum":["请求参数不合法"]},"issues":{"type":"array","items":{"$ref":"#/components/schemas/ZodIssue"}}},"required":["success","error"]},"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"],"example":{"success":false,"error":"Task slug already exists"}}},"parameters":{},"responses":{},"requestBodies":{},"headers":{},"securitySchemes":{},"examples":{},"links":{},"callbacks":{}},"paths":{"/api/tasks":{"get":{"tags":["Demo Tasks"],"summary":"列出示例任务","parameters":[{"schema":{"type":["integer","null"],"minimum":0,"default":0,"description":"分页页码（从 0 开始）","example":0},"required":false,"name":"page","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"是否已完成过滤（true/false，可选）","example":"false"},"required":false,"name":"isCompleted","in":"query"}],"responses":{"200":{"description":"返回任务列表","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"tasks":{"type":"array","items":{"$ref":"#/components/schemas/DemoTask"}}},"required":["success","tasks"],"example":{"success":true,"tasks":[{"name":"lorem","slug":"lorem-1","description":"任务描述（可选）","completed":false,"due_date":"2026-01-01T00:00:00.000Z"}]}}}}},"400":{"description":"请求参数不合法","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}}}},"post":{"tags":["Demo Tasks"],"summary":"创建示例任务","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/DemoTask"},{"description":"示例任务对象"}]}}}},"responses":{"200":{"description":"返回创建后的任务","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"task":{"$ref":"#/components/schemas/DemoTask"}},"required":["success","task"],"example":{"success":true,"task":{"name":"lorem","slug":"lorem-1","description":"任务描述（可选）","completed":false,"due_date":"2026-01-01T00:00:00.000Z"}}}}}},"400":{"description":"请求参数不合法","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"409":{"description":"任务 slug 已存在","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/tasks/{taskSlug}":{"get":{"tags":["Demo Tasks"],"summary":"获取单个示例任务","parameters":[{"schema":{"type":"string","minLength":1,"description":"任务 slug","example":"lorem-1"},"required":true,"name":"taskSlug","in":"path"}],"responses":{"200":{"description":"返回任务","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"task":{"$ref":"#/components/schemas/DemoTask"}},"required":["success","task"],"example":{"success":true,"task":{"name":"lorem","slug":"lorem-1","description":"任务描述（可选）","completed":false,"due_date":"2026-01-01T00:00:00.000Z"}}}}}},"400":{"description":"请求参数不合法","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"404":{"description":"任务不存在","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"example":{"success":false,"error":"Task not found"}}]}}}}}},"delete":{"tags":["Demo Tasks"],"summary":"删除示例任务","parameters":[{"schema":{"type":"string","minLength":1,"description":"任务 slug","example":"lorem-1"},"required":true,"name":"taskSlug","in":"path"}],"responses":{"200":{"description":"返回被删除的任务","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"task":{"$ref":"#/components/schemas/DemoTask"}},"required":["success","task"],"example":{"success":true,"task":{"name":"lorem","slug":"lorem-1","description":"任务描述（可选）","completed":false,"due_date":"2026-01-01T00:00:00.000Z"}}}}}},"400":{"description":"请求参数不合法","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"404":{"description":"任务不存在","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"example":{"success":false,"error":"Task not found"}}]}}}}}}},"/public/projects/{projectId}/flows":{"get":{"tags":["Public API"],"summary":"Dev-only: list project flows","description":"列出 project 下的 flow。dev bypass 下为全量列举；非 dev bypass 下按当前用户 owner_id 过滤。","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"projectId","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","updatedAt"]}}},"required":["items"]}}}}}}},"/public/flows/{id}":{"get":{"tags":["Public API"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"flow graph payload","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"data":{"type":"object","properties":{"nodes":{"type":"array","items":{},"default":[]},"edges":{"type":"array","items":{},"default":[]},"viewport":{"type":["object","null"],"properties":{"x":{"type":"number"},"y":{"type":"number"},"zoom":{"type":"number"}},"required":["x","y","zoom"]}}},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","data","createdAt","updatedAt"]}}}}}}},"/public/flows/{id}/patch":{"post":{"tags":["Public API"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"allowOverwrite":{"type":"boolean"},"deleteNodeIds":{"type":"array","items":{"type":"string","minLength":1}},"deleteEdgeIds":{"type":"array","items":{"type":"string","minLength":1}},"createNodes":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","enum":["taskNode"]},"position":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"}},"required":["x","y"]},"data":{"type":"object","properties":{"kind":{"type":"string","enum":["text","image","imageEdit","video","storyboard","novelDoc","scriptDoc","storyboardScript","cameraRef","workflowInput","workflowOutput","storyboardImage","imageFission","mosaic","composeVideo","audio","subtitle"]},"label":{"type":"string"},"referenceImages":{"type":"array","items":{"type":"string","minLength":1}},"anchorBindings":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["character","scene","prop","shot","story","asset","context","authority_base_frame"]},"refId":{"type":"string","minLength":1},"entityId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"sourceBookId":{"type":"string","minLength":1},"sourceNodeId":{"type":"string","minLength":1},"assetId":{"type":"string","minLength":1},"assetRefId":{"type":"string","minLength":1},"imageUrl":{"type":"string","minLength":1},"referenceView":{"type":"string","enum":["three_view","role_card"]},"category":{"type":"string","minLength":1},"note":{"type":"string","minLength":1}},"required":["kind"]}},"assetInputs":{"type":"array","items":{"type":"object","properties":{"assetId":{"type":"string","minLength":1},"assetRefId":{"type":"string","minLength":1},"url":{"type":"string","minLength":1},"role":{"type":"string","minLength":1},"weight":{"type":"number"},"note":{"type":"string"},"name":{"type":"string"}},"required":["url"]}},"nodeWidth":{"type":"number"},"nodeHeight":{"type":"number"},"productionLayer":{"type":"string","enum":["evidence","constraints","anchors","expansion","execution","results"]},"creationStage":{"type":"string","enum":["source_understanding","constraint_definition","world_anchor_lock","character_anchor_lock","shot_anchor_lock","single_variable_expansion","approved_keyframe_selection","video_plan","video_execution","result_persistence"]},"approvalStatus":{"type":"string","enum":["needs_confirmation","approved","rejected"]},"storyboardEditorGrid":{"type":"string","enum":["2x2","3x2","3x3","5x5"]},"storyboardEditorAspect":{"type":"string","enum":["1:1","4:3","16:9","9:16"]},"storyboardEditorCollapsed":{"type":"boolean"},"storyboardEditorEditMode":{"type":"boolean"},"storyboardEditorCells":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"imageUrl":{"type":["string","null"],"minLength":1},"label":{"type":"string"},"prompt":{"type":"string"},"sourceKind":{"type":"string"},"sourceNodeId":{"type":"string","minLength":1},"sourceIndex":{"type":"integer","minimum":0},"shotNo":{"type":"integer","minimum":1},"aspect":{"type":"string"}},"required":["id"]}},"imageCameraControl":{"type":"object","properties":{"enabled":{"type":"boolean"},"presetId":{"type":"string","minLength":1},"azimuthDeg":{"type":"number"},"elevationDeg":{"type":"number"},"distance":{"type":"number"}}},"imageLightingRig":{"type":"object","properties":{"main":{"type":"object","properties":{"enabled":{"type":"boolean"},"presetId":{"type":"string","minLength":1},"azimuthDeg":{"type":"number"},"elevationDeg":{"type":"number"},"intensity":{"type":"number"},"colorHex":{"type":"string","minLength":1}}},"fill":{"type":"object","properties":{"enabled":{"type":"boolean"},"presetId":{"type":"string","minLength":1},"azimuthDeg":{"type":"number"},"elevationDeg":{"type":"number"},"intensity":{"type":"number"},"colorHex":{"type":"string","minLength":1}}}}},"productionMetadata":{"type":"object","properties":{"chapterGrounded":{"type":"boolean","enum":[true]},"lockedAnchors":{"type":"object","properties":{"character":{"type":"array","items":{"type":"string"}},"scene":{"type":"array","items":{"type":"string"}},"shot":{"type":"array","items":{"type":"string"}},"continuity":{"type":"array","items":{"type":"string"}},"missing":{"type":"array","items":{"type":"string"}}},"required":["character","scene","shot","continuity","missing"]},"authorityBaseFrame":{"type":"object","properties":{"status":{"type":"string","enum":["planned","confirmed"]},"source":{"type":"string","minLength":1},"reason":{"type":"string","minLength":1},"nodeId":{"type":["string","null"],"minLength":1}},"required":["status","source","reason"]}},"required":["chapterGrounded","lockedAnchors","authorityBaseFrame"]}},"required":["kind"]},"parentId":{"type":"string","minLength":1},"selected":{"type":"boolean"},"draggable":{"type":"boolean"},"selectable":{"type":"boolean"},"focusable":{"type":"boolean"},"dragHandle":{"type":"string","minLength":1}},"required":["type","position","data"]},{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","enum":["groupNode"]},"position":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"}},"required":["x","y"]},"data":{"type":"object","properties":{"label":{"type":"string"},"isGroup":{"type":"boolean"},"groupKind":{"type":"string"}}},"style":{"type":"object","properties":{"width":{"type":"number"},"height":{"type":"number"}},"required":["width","height"]},"parentId":{"type":"string","minLength":1},"selected":{"type":"boolean"},"draggable":{"type":"boolean"},"selectable":{"type":"boolean"},"focusable":{"type":"boolean"}},"required":["type","position","data","style"]}]}},"createEdges":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"source":{"type":"string","minLength":1},"target":{"type":"string","minLength":1},"sourceHandle":{"type":"string","minLength":1},"targetHandle":{"type":"string","minLength":1},"type":{"type":"string","minLength":1},"label":{"type":"string"},"data":{"type":"object","additionalProperties":{}}},"required":["source","target"]}},"patchNodeData":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"data":{"type":"object","additionalProperties":{}}},"required":["id","data"]}},"appendNodeArrays":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"key":{"type":"string","minLength":1},"items":{"type":"array","items":{},"minItems":1}},"required":["id","key","items"]}}}}}}},"responses":{"200":{"description":"patched flow data","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"flowId":{"type":"string"},"updatedAt":{"type":"string"},"stats":{"type":"object","properties":{"deletedNodes":{"type":"number"},"deletedEdges":{"type":"number"},"createdNodes":{"type":"number"},"createdEdges":{"type":"number"},"patchedNodes":{"type":"number"},"appendedArrays":{"type":"number"}},"required":["deletedNodes","deletedEdges","createdNodes","createdEdges","patchedNodes","appendedArrays"]},"data":{"type":"object","properties":{"nodes":{"type":"array","items":{},"default":[]},"edges":{"type":"array","items":{},"default":[]},"viewport":{"type":["object","null"],"properties":{"x":{"type":"number"},"y":{"type":"number"},"zoom":{"type":"number"}},"required":["x","y","zoom"]}}}},"required":["ok","flowId","updatedAt","stats","data"]}}}}}}},"/public/agents/tools/execute":{"post":{"tags":["Public API"],"summary":"Execute project-scoped agents bridge tools","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"toolName":{"type":"string","enum":["lehuoai_project_flows_list","lehuoai_project_context_get","lehuoai_books_list","lehuoai_book_index_get","lehuoai_book_chapter_get","lehuoai_book_storyboard_plan_get","lehuoai_book_storyboard_plan_upsert","lehuoai_storyboard_source_bundle_get","lehuoai_storyboard_continuity_get","lehuoai_node_context_bundle_get","lehuoai_video_review_bundle_get","lehuoai_pipeline_runs_list","lehuoai_pipeline_run_get","lehuoai_executions_list","lehuoai_execution_get","lehuoai_execution_node_runs_get","lehuoai_execution_events_list","lehuoai_flow_get","lehuoai_flow_patch","lehuoai_image_generate_to_canvas","lehuoai_video_generate_to_canvas"]},"args":{"type":"object","additionalProperties":{},"default":{}},"canvasProjectId":{"type":"string","minLength":1},"canvasFlowId":{"type":"string","minLength":1},"canvasNodeId":{"type":"string","minLength":1}},"required":["toolName"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"content":{"type":"string"},"data":{"type":"object","additionalProperties":{}}},"required":["ok","content"]}}}}}}},"/public/agents/chat":{"post":{"tags":["Public API"],"summary":"Agents 对话 /public/agents/chat","description":"新的 agents 专用对话链路。该入口不再经过旧的多 vendor 公共聊天编排，只负责把用户/项目/画布工具事实透传给 agents-cli。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vendor":{"type":"string","description":"指定厂商 key（默认 auto）；vendor=auto 会从系统级已启用且已配置的厂商列表中依次重试，直到成功或候选耗尽。","example":"auto"},"vendorCandidates":{"type":"array","items":{"type":"string"},"description":"当 vendor=auto 时用于限制候选厂商列表（仅用于自动回退范围与顺序；最终仍会过滤掉系统级未启用/未配置的厂商）。","example":["apimart"]},"prompt":{"type":"string","minLength":1},"displayPrompt":{"type":"string","minLength":1,"maxLength":2000,"description":"可选：用户侧展示/持久化用的当前轮文案。若 prompt 为系统生成的隐式提示，可用该字段保留用户真实触发语义。","example":"基于「镜头 12」继续"},"modelKey":{"type":"string"},"modelAlias":{"type":"string"},"systemPrompt":{"type":"string"},"temperature":{"type":"number","minimum":0,"maximum":2},"model":{"type":"string","description":"OpenAI responses 兼容字段：模型别名/模型名。服务端会按 model catalog 映射到对应 vendor。","example":"gemini-2.5-pro"},"input":{"anyOf":[{"type":"string"},{"type":"array","items":{}}],"description":"OpenAI responses 兼容字段：支持字符串或消息数组。若传入该字段，服务端会自动提取用户文本与参考图。","example":"你好，帮我总结这段文案。"},"instructions":{"type":"string","description":"OpenAI responses 兼容字段：系统提示词。会映射到 systemPrompt。","example":"请用中文回答。"},"max_output_tokens":{"type":"integer","minimum":1},"tool_choice":{},"tools":{"type":"array","items":{}},"stream":{"type":"boolean"},"response_format":{},"mode":{"type":"string","enum":["chat","auto"],"description":"对话模式（默认 chat）；auto 表示统一的最高质量 agents 执行模式，只负责执行强度与完成态要求，不负责本地业务意图分流。具体创作场景语义必须由 skill 选择或 agents 语义决策触发，不能由本地 route 注入。","example":"auto"},"sessionKey":{"type":"string","minLength":1,"maxLength":10000,"description":"会话键（建议前端稳定传递）。服务端按 userId + sessionKey 隔离并持久化聊天历史，用于跨轮记忆。","example":"canvas-main:default"},"canvasProjectId":{"type":"string","minLength":1,"maxLength":120,"description":"可选：当前画布项目 ID（用于 agents-cli 在对话中定位“当前项目”）。","example":"13b29494-8a2e-4cca-8172-8c778642be8f"},"canvasFlowId":{"type":"string","minLength":1,"maxLength":120,"description":"可选：当前 Flow ID（用于 agents-cli 在对话中定位“当前画布/工作流”）。","example":"96bb2e49-fb93-4fd6-b64b-22777a7b185e"},"canvasNodeId":{"type":"string","minLength":1,"maxLength":120,"description":"可选：当前用户选中的节点 ID（用于 agents-cli 直接读取当前节点证据包）。","example":"96a6e963-0eaa-47cf-ab9f-15c79491424f"},"chatContext":{"type":"object","properties":{"currentProjectName":{"type":"string","minLength":1,"maxLength":200},"workspaceAction":{"type":"string","enum":["chapter_script_generation","chapter_asset_generation","shot_video_generation"]},"skill":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":120},"name":{"type":"string","minLength":1,"maxLength":120}}},"selectedNodeLabel":{"type":"string","minLength":1,"maxLength":200},"selectedNodeKind":{"type":"string","minLength":1,"maxLength":120},"selectedNodeTextPreview":{"type":"string","minLength":1,"maxLength":2000},"selectedReference":{"type":"object","properties":{"nodeId":{"type":"string","minLength":1,"maxLength":120},"label":{"type":"string","minLength":1,"maxLength":200},"kind":{"type":"string","minLength":1,"maxLength":120},"anchorBindings":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["character","scene","prop","shot","story","asset","context","authority_base_frame"]},"refId":{"type":"string","minLength":1,"maxLength":160},"entityId":{"type":"string","minLength":1,"maxLength":160},"label":{"type":"string","minLength":1,"maxLength":200},"sourceBookId":{"type":"string","minLength":1,"maxLength":120},"sourceNodeId":{"type":"string","minLength":1,"maxLength":120},"assetId":{"type":"string","minLength":1,"maxLength":120},"assetRefId":{"type":"string","minLength":1,"maxLength":160},"imageUrl":{"type":"string","minLength":1,"maxLength":2048},"referenceView":{"type":"string","enum":["three_view","role_card"]},"category":{"type":"string","minLength":1,"maxLength":120},"note":{"type":"string","minLength":1,"maxLength":500}},"required":["kind"]},"maxItems":24},"imageUrl":{"type":"string","minLength":1,"maxLength":2048},"sourceUrl":{"type":"string","minLength":1,"maxLength":2048},"bookId":{"type":"string","minLength":1,"maxLength":120},"chapterId":{"type":"string","minLength":1,"maxLength":120},"shotNo":{"type":"integer","minimum":1},"productionLayer":{"type":"string","minLength":1,"maxLength":120},"creationStage":{"type":"string","minLength":1,"maxLength":120},"approvalStatus":{"type":"string","minLength":1,"maxLength":120},"hasUpstreamTextEvidence":{"type":"boolean"},"hasDownstreamComposeVideo":{"type":"boolean"},"storyboardSelectionContext":{"type":"object","properties":{"version":{"type":"number","enum":[1]},"scope":{"type":"string","enum":["chunk","frame"]},"taskId":{"type":"string","minLength":1,"maxLength":200},"planId":{"type":"string","minLength":1,"maxLength":200},"chunkId":{"type":"string","minLength":1,"maxLength":200},"chunkIndex":{"type":"integer","minimum":0,"maximum":9999},"groupSize":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[4]},{"type":"number","enum":[9]},{"type":"number","enum":[25]}]},"shotStart":{"type":"integer","minimum":1,"maximum":5000},"shotEnd":{"type":"integer","minimum":1,"maximum":5000},"shotNo":{"type":"integer","minimum":1,"maximum":5000},"frameIndex":{"type":"integer","minimum":0,"maximum":24},"title":{"type":"string","minLength":1,"maxLength":200},"imageUrl":{"type":"string","minLength":1,"maxLength":10000},"sourceBookId":{"type":"string","minLength":1,"maxLength":200},"materialChapter":{"type":"integer","minimum":1,"maximum":9999},"storyContext":{"type":"string","minLength":1,"maxLength":4000},"shotPrompt":{"type":"string","minLength":1,"maxLength":12000},"storyboardScript":{"type":"string","minLength":1,"maxLength":20000},"modelKey":{"type":"string","minLength":1,"maxLength":200},"aspectRatio":{"type":"string","minLength":1,"maxLength":40},"referenceBindings":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["continuity_tail","role","reference","scene_prop","spell_fx"]},"refId":{"type":"string","minLength":1,"maxLength":200},"label":{"type":"string","minLength":1,"maxLength":200},"imageUrl":{"type":"string","minLength":1,"maxLength":10000}},"required":["kind","label","imageUrl"],"additionalProperties":false},"maxItems":12}},"required":["version","scope"],"additionalProperties":false}}}},"description":"前端传给 agents bridge 的结构化对话上下文。用于后端统一构建 system prompt，避免前端自行拼接整段 prompt。"},"generationContract":{"type":"object","properties":{"version":{"type":"string","enum":["v1"]},"lockedAnchors":{"type":"array","items":{"type":"string","minLength":1,"maxLength":240},"maxItems":12},"editableVariable":{"type":["string","null"],"minLength":1,"maxLength":240},"forbiddenChanges":{"type":"array","items":{"type":"string","minLength":1,"maxLength":240},"maxItems":12},"approvedKeyframeId":{"type":["string","null"],"minLength":1,"maxLength":160}},"required":["version","lockedAnchors","editableVariable","forbiddenChanges","approvedKeyframeId"],"additionalProperties":false,"description":"薄执行合同：用于把当前已锁定的连续性锚点、唯一可编辑变量、禁止漂移项和已确认关键帧状态，从 /public/agents/chat 显式传给 agents bridge 与 agents-cli。"},"bookId":{"type":"string","minLength":1,"maxLength":120,"description":"可选：当前书籍 ID（用于按用户/书籍维度召回业务记忆）。","example":"book_demo_01"},"chapterId":{"type":"string","minLength":1,"maxLength":120,"description":"可选：当前章节 ID（用于章节连续性与分镜记忆召回）。","example":"chapter_03"},"requestedImageCount":{"type":"integer","minimum":1,"maximum":15,"description":"期望产图数量（主要用于 mode=auto 的回填与兜底出图目标张数）。","example":1},"aspectRatio":{"type":"string","maxLength":20,"description":"期望画幅比例（例如 1:1 / 4:3 / 3:4 / 16:9 / 9:16）。用于 auto 兜底出图。","example":"9:16"},"referenceImages":{"type":"array","items":{"type":"string"},"description":"参考图片 URL 列表（用于 chat/auto 模式；建议按需提供，不限制数量）。","example":["https://example.com/reference.png"]},"assetInputs":{"type":"array","items":{"type":"object","properties":{"assetId":{"type":"string","minLength":1,"maxLength":120},"assetRefId":{"type":"string","minLength":1,"maxLength":160},"url":{"type":"string","minLength":1,"maxLength":2048},"role":{"type":"string","enum":["target","reference","character","scene","prop","product","style","context","mask"],"description":"资产角色：target=被改造目标；reference/character/scene/prop/product/style/context/mask=辅助参考。","example":"reference"},"weight":{"type":"number","minimum":0,"maximum":1,"description":"该资产参考权重，0-1。","example":0.8},"note":{"type":"string","maxLength":500,"description":"该资产的补充说明（简短）。","example":"保留角色发型和服饰轮廓"},"name":{"type":"string","minLength":1,"maxLength":200,"description":"该资产的稳定命名引用，可供 agents 以 @name 语义使用。","example":"女主角色卡"}}},"description":"多资产输入契约（推荐）。用于把目标图/参考图/角色图等结构化传给 agents-cli，不再写死“仅两图”或固定张数上限。"},"disableQualityReview":{"type":"boolean","description":"是否禁用候选图质检/排序流程（默认 true）。开启后会强制走“直接生成”路径，不做逐张候选评审。","example":true},"debug":{"type":"boolean","description":"是否回显调试日志（默认 false）。开启后响应会附带 debugLogs/debug，便于定位自动生成链路问题。","example":true},"planOnly":{"type":"boolean","description":"仅输出规划偏好。对 agents 专用聊天入口这不是本地硬拦截；bridge 仍会保留执行工具，由 agents 基于真实意图与证据自主决定是否只返回规划或直接执行。","example":true},"forceAssetGeneration":{"type":"boolean","description":"强制本轮优先尝试真实资产生成/生成节点落地，而不是只给提示词或抽象建议。若证据或权限不足导致无法生成，应显式失败并返回缺口。","example":true}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"vendor":{"type":"string"},"text":{"type":"string"},"assets":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"url":{"type":"string"},"thumbnailUrl":{"type":"string"},"assetId":{"type":"string"},"assetRefId":{"type":"string"},"vendor":{"type":"string"},"modelKey":{"type":"string"},"taskId":{"type":"string"}}}},"agentDecision":{"type":"object","properties":{"executionKind":{"type":"string","enum":["plan","execute","generate","answer"]},"canvasAction":{"type":"string","enum":["create_canvas_workflow","write_canvas","none"]},"assetCount":{"type":"integer","minimum":0},"projectStateRead":{"type":"boolean"},"requiresConfirmation":{"type":"boolean"},"reason":{"type":"string","minLength":1,"maxLength":500}},"required":["executionKind","canvasAction","assetCount","projectStateRead","requiresConfirmation","reason"]},"trace":{"type":"object","properties":{"requestId":{"type":"string"},"sessionId":{"type":"string"},"outputMode":{"type":"string","enum":["plan_with_assets","plan_only","direct_assets","text_only"]},"toolEvidence":{"type":"object","properties":{"toolNames":{"type":"array","items":{"type":"string"}},"readProjectState":{"type":"boolean"},"readBookList":{"type":"boolean"},"readBookIndex":{"type":"boolean"},"readChapter":{"type":"boolean"},"readStoryboardHistory":{"type":"boolean"},"readMaterialAssets":{"type":"boolean"},"generatedAssets":{"type":"boolean"},"wroteCanvas":{"type":"boolean"}},"required":["toolNames","readProjectState","readBookList","readBookIndex","readChapter","readStoryboardHistory","readMaterialAssets","generatedAssets","wroteCanvas"]},"toolStatusSummary":{"type":"object","properties":{"totalToolCalls":{"type":"integer","minimum":0},"succeededToolCalls":{"type":"integer","minimum":0},"failedToolCalls":{"type":"integer","minimum":0},"deniedToolCalls":{"type":"integer","minimum":0},"blockedToolCalls":{"type":"integer","minimum":0},"runMs":{"type":["number","null"]}},"required":["totalToolCalls","succeededToolCalls","failedToolCalls","deniedToolCalls","blockedToolCalls","runMs"]},"canvasMutation":{"type":"object","properties":{"deletedNodeIds":{"type":"array","items":{"type":"string"}},"deletedEdgeIds":{"type":"array","items":{"type":"string"}},"createdNodeIds":{"type":"array","items":{"type":"string"}},"patchedNodeIds":{"type":"array","items":{"type":"string"}},"executableNodeIds":{"type":"array","items":{"type":"string"}}},"required":["deletedNodeIds","deletedEdgeIds","createdNodeIds","patchedNodeIds","executableNodeIds"]},"diagnosticFlags":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"severity":{"type":"string","enum":["high","medium"]},"title":{"type":"string"},"detail":{"type":"string"}},"required":["code","severity","title","detail"]}},"canvasPlan":{"type":"object","properties":{"tagPresent":{"type":"boolean"},"normalized":{"type":"boolean"},"parseSuccess":{"type":"boolean"},"error":{"type":"string"},"errorCode":{"type":"string"},"errorDetail":{"type":"string"},"schemaIssues":{"type":"array","items":{"type":"string"}},"detectedTagName":{"type":"string"},"nodeCount":{"type":"integer","minimum":0},"edgeCount":{"type":"integer","minimum":0},"nodeKinds":{"type":"array","items":{"type":"string"}},"hasAssetUrls":{"type":"boolean"},"action":{"type":"string"},"summary":{"type":"string"},"reason":{"type":"string"},"rawPayload":{"type":"string"}},"required":["tagPresent","normalized","parseSuccess","error","errorCode","errorDetail","schemaIssues","detectedTagName","nodeCount","edgeCount","nodeKinds","hasAssetUrls","action","summary","reason","rawPayload"]},"todoList":{"type":"object","properties":{"sourceToolCallId":{"type":"string","minLength":1},"items":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string","minLength":1},"completed":{"type":"boolean"},"status":{"type":"string","enum":["pending","in_progress","completed"]}},"required":["text","completed","status"]},"minItems":1,"maxItems":20},"totalCount":{"type":"integer","minimum":1},"completedCount":{"type":"integer","minimum":0},"inProgressCount":{"type":"integer","minimum":0},"pendingCount":{"type":"integer","minimum":0}},"required":["sourceToolCallId","items","totalCount","completedCount","inProgressCount","pendingCount"]},"todoEvents":{"type":"array","items":{"type":"object","properties":{"sourceToolCallId":{"type":"string","minLength":1},"items":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string","minLength":1},"completed":{"type":"boolean"},"status":{"type":"string","enum":["pending","in_progress","completed"]}},"required":["text","completed","status"]},"minItems":1,"maxItems":20},"totalCount":{"type":"integer","minimum":1},"completedCount":{"type":"integer","minimum":0},"inProgressCount":{"type":"integer","minimum":0},"pendingCount":{"type":"integer","minimum":0},"atMs":{"type":["integer","null"],"minimum":0},"startedAt":{"type":["string","null"]},"finishedAt":{"type":["string","null"]},"durationMs":{"type":["integer","null"],"minimum":0}},"required":["sourceToolCallId","items","totalCount","completedCount","inProgressCount","pendingCount","atMs","startedAt","finishedAt","durationMs"]},"maxItems":32},"runtime":{"type":"object","properties":{"profile":{"type":"string","enum":["general","code","unknown"]},"registeredToolNames":{"type":"array","items":{"type":"string"},"maxItems":256},"registeredTeamToolNames":{"type":"array","items":{"type":"string"},"maxItems":64},"requiredSkills":{"type":"array","items":{"type":"string"},"maxItems":32},"loadedSkills":{"type":"array","items":{"type":"string"},"maxItems":64},"allowedSubagentTypes":{"type":"array","items":{"type":"string"},"maxItems":16},"requireAgentsTeamExecution":{"type":"boolean"},"contextDiagnostics":{"type":"object","properties":{"totalChars":{"type":"integer","minimum":0},"totalBudgetChars":{"type":"integer","minimum":0},"sources":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"kind":{"type":"string","minLength":1},"summary":{"type":"string","minLength":1},"chars":{"type":"integer","minimum":0},"budgetChars":{"type":"integer","minimum":0},"truncated":{"type":"boolean"}},"required":["id","kind","summary","chars","budgetChars","truncated"]},"maxItems":16}},"required":["totalChars","totalBudgetChars","sources"]},"capabilitySnapshot":{"type":"object","properties":{"providers":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","minLength":1},"name":{"type":"string","minLength":1},"toolNames":{"type":"array","items":{"type":"string"},"maxItems":128},"toolCount":{"type":"integer","minimum":0}},"required":["kind","name","toolNames","toolCount"]},"maxItems":12},"exposedToolNames":{"type":"array","items":{"type":"string"},"maxItems":256},"exposedTeamToolNames":{"type":"array","items":{"type":"string"},"maxItems":64}},"required":["providers","exposedToolNames","exposedTeamToolNames"]},"policySummary":{"type":"object","properties":{"totalDecisions":{"type":"integer","minimum":0},"allowCount":{"type":"integer","minimum":0},"denyCount":{"type":"integer","minimum":0},"requiresApprovalCount":{"type":"integer","minimum":0},"uniqueDeniedSignatures":{"type":"array","items":{"type":"string"},"maxItems":32}},"required":["totalDecisions","allowCount","denyCount","requiresApprovalCount","uniqueDeniedSignatures"]},"canvasCapabilities":{"type":"object","properties":{"version":{"type":["string","null"]},"localCanvasToolNames":{"type":"array","items":{"type":"string"},"maxItems":128},"remoteToolNames":{"type":"array","items":{"type":"string"},"maxItems":128},"nodeKinds":{"type":"array","items":{"type":"string"},"maxItems":128}},"required":["version","localCanvasToolNames","remoteToolNames","nodeKinds"]}},"required":["profile","registeredToolNames","registeredTeamToolNames","requiredSkills","loadedSkills","allowedSubagentTypes","requireAgentsTeamExecution"]},"turnVerdict":{"type":"object","properties":{"status":{"type":"string","enum":["satisfied","partial","failed"]},"reasons":{"type":"array","items":{"type":"string","minLength":1},"minItems":1}},"required":["status","reasons"]}},"required":["outputMode","toolEvidence","toolStatusSummary","diagnosticFlags","canvasPlan","turnVerdict"]},"debugLogs":{"type":"array","items":{"type":"string"}},"debug":{"type":"object","properties":{"mode":{"type":"string","enum":["chat","auto"]},"referenceImagesCount":{"type":"number"},"rawAssetCount":{"type":"number"},"autoJsonAssetCount":{"type":"number"},"mergedAssetCount":{"type":"number"},"autoJson":{"type":"object","properties":{"present":{"type":"boolean"},"total":{"type":"number"},"valid":{"type":"number"},"empty":{"type":"number"}},"required":["present"]}}}},"required":["id","vendor","text"]}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"issues":{"type":"array","items":{}}},"required":["error"]}}}},"401":{"description":"Unauthorized (missing/invalid JWT or API key)","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"error":{"type":"string"},"code":{"type":"string"},"details":{}},"required":["message","error","code"]}}}}}}},"/public/vision":{"post":{"tags":["Public API"],"summary":"图像理解 /public/vision","description":"便捷图像理解接口：创建 image_to_prompt 任务并直接返回文本（常见用法：根据图片反推可复现的英文提示词）。默认使用 gemini-3.1-flash-image-preview；支持外部 prompt 透传；图片输入支持 imageUrl 或 imageData（二选一）。失败会显式返回错误，不做 draw 降级。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vendor":{"type":"string","description":"指定厂商 key（默认 auto）；vendor=auto 会从系统级已启用且已配置的厂商列表中依次重试，直到成功或候选耗尽。","example":"auto"},"vendorCandidates":{"type":"array","items":{"type":"string"},"description":"当 vendor=auto 时用于限制候选厂商列表（仅用于自动回退范围与顺序；最终仍会过滤掉系统级未启用/未配置的厂商）。","example":["yunwu"]},"imageUrl":{"type":"string","description":"图片 URL（http(s)）；也支持传相对路径（以本次请求的 origin 补全）。","example":"https://github.com/dianping/cat/raw/master/cat-home/src/main/webapp/images/logo/cat_logo03.png"},"imageData":{"type":"string","description":"图片 DataURL（data:image/*;base64,...）。","example":"data:image/png;base64,..."},"prompt":{"type":"string","description":"图片理解任务提示词（可选；为空时服务端会使用默认指令）。若调用方已提供 prompt，服务端会原样透传，不做静默改写或自动拼接。","example":"请详细分析我提供的图片，推测可用于复现它的英文提示词，包含主体、环境、镜头、光线和风格。输出必须是纯英文提示词，不要添加中文备注或翻译。"},"modelKey":{"type":"string","description":"模型 Key（厂商内；可选）。","example":"gemini-1.5-pro-latest"},"modelAlias":{"type":"string","description":"模型别名（Public 统一别名；推荐）。若其值恰好等于真实 model_key，服务端也会按精确 model_key 兼容解析。仅在 modelAlias / modelKey 都未提供时，才默认使用 gemini-3.1-flash-image-preview。","example":"gemini-3.1-flash-image-preview"},"systemPrompt":{"type":"string","description":"系统提示词（可选）。","example":"请用中文回答。"},"temperature":{"type":"number","minimum":0,"maximum":2,"description":"采样温度（可选）。","example":0.2}}},"example":{"vendor":"auto","imageUrl":"https://github.com/dianping/cat/raw/master/cat-home/src/main/webapp/images/logo/cat_logo03.png","prompt":"请详细分析我提供的图片，推测可用于复现它的英文提示词，包含主体、环境、镜头、光线和风格。输出必须是纯英文提示词，不要添加中文备注或翻译。","modelAlias":"gemini-3.1-flash-image-preview","temperature":0.2}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"vendor":{"type":"string"},"text":{"type":"string"}},"required":["id","vendor","text"]},"example":{"id":"task_01HXYZ...","vendor":"openai","text":"A clean minimal logo of a cat..."}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"issues":{"type":"array","items":{}}},"required":["error"]},"example":{"error":"Invalid request body","issues":[]}}}},"401":{"description":"Unauthorized (missing/invalid JWT or API key)","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"error":{"type":"string"},"code":{"type":"string"},"details":{}},"required":["message","error","code"]}}}}}}},"/public/oss/upload":{"post":{"tags":["Public API"],"summary":"上传到对象存储 /public/oss/upload","description":"JSON 方式上传文件到对象存储（兼容 RustFS / Cloudflare R2）。支持 sourceUrl（远端 URL）或 dataUrl（base64）。会自动落库为当前用户资产并返回可访问 URL。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sourceUrl":{"type":"string","description":"待上传的远端文件 URL（http/https）。","example":"https://example.com/sample.mp4"},"dataUrl":{"type":"string","description":"待上传文件的 Data URL（data:<mime>;base64,...）。","example":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."},"fileName":{"type":"string","description":"原始文件名（可选，用于扩展名推断）。","example":"sample.mp4"},"contentType":{"type":"string","description":"内容类型（可选；优先于 fileName 推断）。","example":"video/mp4"},"name":{"type":"string","description":"资产展示名（可选）。","example":"产品演示视频"},"prompt":{"type":"string"},"vendor":{"type":"string"},"modelKey":{"type":"string"},"taskKind":{"type":"string"}}},"example":{"sourceUrl":"https://example.com/sample.mp4","fileName":"sample.mp4","contentType":"video/mp4","name":"产品演示视频"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["image","video","file"]},"url":{"type":"string"},"key":{"type":"string"},"contentType":{"type":"string"},"size":{"type":["number","null"]}},"required":["id","name","type","url","key","contentType","size"]},"example":{"id":"asset_01HXYZ...","name":"产品演示视频","type":"video","url":"https://assets.example.com/uploads/user/u_1/20260212/xxx.mp4","key":"uploads/user/u_1/20260212/xxx.mp4","contentType":"video/mp4","size":1200345}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"issues":{"type":"array","items":{}}},"required":["error"]},"example":{"error":"Invalid request body","issues":[]}}}},"401":{"description":"Unauthorized (missing/invalid JWT or API key)","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"error":{"type":"string"},"code":{"type":"string"},"details":{}},"required":["message","error","code"]}}}}}}},"/public/video/understand":{"post":{"tags":["Public API"],"summary":"视频理解 /public/video/understand","description":"显式视频理解接口。内部走统一任务入口 kind=chat，并透传 videoFileUri/videoMimeType 到上游多模态模型。默认建议不传 vendorCandidates，由系统级动态配置决定可用厂商；只有调用方明确要锁定厂商时再传。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vendor":{"type":"string","description":"厂商 key（默认 auto；推荐配合 vendorCandidates=['gemini']）。","example":"auto"},"vendorCandidates":{"type":"array","items":{"type":"string"},"description":"vendor=auto 时候选厂商（建议只放 gemini）。","example":["gemini"]},"prompt":{"type":"string","minLength":1,"description":"视频理解任务提示词（例如总结、提取分镜、问答等）。","example":"请总结视频内容并输出 5 个镜头段落。"},"videoFileUri":{"type":"string","minLength":1,"description":"Gemini Files API 返回的 file_uri（可选；若未提供可用 videoUrl/videoData 自动上传）。","example":"https://generativelanguage.googleapis.com/v1beta/files/abc123"},"videoUrl":{"type":"string","description":"远程视频 URL（http/https）。当未传 videoFileUri 时，服务端会下载并上传为 Gemini file_uri。","example":"https://example.com/sample.mp4"},"videoData":{"type":"string","description":"视频 Data URL（data:video/*;base64,...）。当未传 videoFileUri 时，服务端会上传为 Gemini file_uri。","example":"data:video/mp4;base64,AAAAIGZ0eXBpc29tAAACAGlzb20..."},"videoMimeType":{"type":"string","description":"视频 MIME（默认 video/mp4）。","example":"video/mp4"},"modelAlias":{"type":"string","description":"模型别名（推荐文本模型别名）。","example":"gemini-3-flash-preview"},"modelKey":{"type":"string","description":"模型 key（可选）。","example":"gemini-3-flash-preview"},"systemPrompt":{"type":"string","description":"系统提示词（可选）。","example":"请用中文回答。"},"temperature":{"type":"number","minimum":0,"maximum":2,"description":"采样温度（可选）。","example":0.2}},"required":["prompt"]},"example":{"vendor":"auto","prompt":"请总结视频内容并给出 5 道题（含答案）。","videoUrl":"https://example.com/sample.mp4","videoMimeType":"video/mp4","modelAlias":"gemini-3-flash-preview"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"vendor":{"type":"string"},"text":{"type":"string"},"result":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["chat","prompt_refine","text_to_image","image_to_prompt","image_to_video","text_to_video","image_edit"]},"status":{"type":"string","enum":["queued","running","succeeded","failed"]},"assets":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["image","video"]},"url":{"type":"string"},"thumbnailUrl":{"type":["string","null"]},"assetId":{"type":["string","null"]},"assetRefId":{"type":["string","null"]},"assetName":{"type":["string","null"]}},"required":["type","url"]}},"raw":{}},"required":["id","kind","status","assets"]}},"required":["id","vendor","text","result"]}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"issues":{"type":"array","items":{}}},"required":["error"]},"example":{"error":"Invalid request body","issues":[]}}}},"401":{"description":"Unauthorized (missing/invalid JWT or API key)","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"error":{"type":"string"},"code":{"type":"string"},"details":{}},"required":["message","error","code"]}}}}}}},"/public/tasks":{"post":{"tags":["Public API"],"summary":"统一任务入口 /public/tasks","description":"统一任务入口：当你希望完全复用内部 TaskRequest 结构时使用（支持 image/video/chat 等）。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vendor":{"type":"string","description":"指定厂商 key（默认 auto）；vendor=auto 会从系统级已启用且已配置的厂商列表中依次重试，直到成功或候选耗尽。","example":"auto"},"vendorCandidates":{"type":"array","items":{"type":"string"},"description":"当 vendor=auto 时用于限制候选厂商列表（仅用于自动回退范围与顺序；最终仍会过滤掉系统级未启用/未配置的厂商）。","example":["apimart"]},"request":{"type":"object","properties":{"kind":{"type":"string","enum":["chat","prompt_refine","text_to_image","image_to_prompt","image_to_video","text_to_video","image_edit"]},"prompt":{"type":"string"},"negativePrompt":{"type":"string"},"seed":{"type":"number"},"width":{"type":"number"},"height":{"type":"number"},"steps":{"type":"number"},"cfgScale":{"type":"number"},"extras":{"type":"object","additionalProperties":{}}},"required":["kind","prompt"]}},"required":["request"]},"example":{"vendor":"auto","request":{"kind":"text_to_video","prompt":"雨夜霓虹街头，一只白猫缓慢走过…","extras":{"modelAlias":"<YOUR_VIDEO_MODEL_ALIAS>","durationSeconds":10}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"vendor":{"type":"string"},"result":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["chat","prompt_refine","text_to_image","image_to_prompt","image_to_video","text_to_video","image_edit"]},"status":{"type":"string","enum":["queued","running","succeeded","failed"]},"assets":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["image","video"]},"url":{"type":"string"},"thumbnailUrl":{"type":["string","null"]},"assetId":{"type":["string","null"]},"assetRefId":{"type":["string","null"]},"assetName":{"type":["string","null"]}},"required":["type","url"]}},"raw":{}},"required":["id","kind","status","assets"]}},"required":["vendor","result"]},"example":{"vendor":"veo","result":{"id":"task_01HXYZ...","kind":"text_to_video","status":"queued","assets":[],"raw":{}}}}}},"400":{"description":"Invalid request body / unsupported task kind","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"error":{"type":"string"},"issues":{"type":"array","items":{}}},"required":["error"]},{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}},"required":["error","code"]}]},"example":{"error":"Unsupported task kind for public API","code":"unsupported_task_kind","details":{"kind":"image_to_video"}}}}},"401":{"description":"Unauthorized (missing/invalid JWT or API key)","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"error":{"type":"string"},"code":{"type":"string"},"details":{}},"required":["message","error","code"]}}}}}}},"/public/draw":{"post":{"tags":["Public API"],"summary":"绘图 /public/draw","description":"便捷绘图接口：创建 text_to_image 或 image_edit 任务（vendor=auto 会在系统级已启用且已配置的厂商列表中依次重试，直到成功或候选耗尽）。支持通过 width/height 或 extras.aspectRatio/extras.resolution 配置尺寸/分辨率，但不同 vendor 支持不一致；如需严格像素宽高，建议指定 vendor=qwen。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vendor":{"type":"string","description":"指定厂商 key（默认 auto）；vendor=auto 会从系统级已启用且已配置的厂商列表中依次重试，直到成功或候选耗尽。","example":"auto"},"vendorCandidates":{"type":"array","items":{"type":"string"},"description":"当 vendor=auto 时用于限制候选厂商列表（仅用于自动回退范围与顺序；最终仍会过滤掉系统级未启用/未配置的厂商）。","example":["apimart"]},"async":{"type":"boolean","description":"是否异步执行（立即返回 taskId，结果通过 /public/tasks/result 轮询）。默认 false；当 vendor=tuzi 或 vendor=auto 且 extras.modelAlias 以 nano-banana 开头时，为避免请求超时会默认启用（除非显式传 async=false）。","example":true},"kind":{"type":"string","enum":["text_to_image","image_edit"],"description":"任务类型（默认 text_to_image）。","example":"text_to_image"},"prompt":{"type":"string","minLength":1,"description":"提示词（必填）。","example":"一张电影感海报，中文“lehuoAI”，高细节，干净背景"},"negativePrompt":{"type":"string","description":"反向提示词（可选；不同厂商可能忽略）。","example":"low quality, blurry, watermark"},"seed":{"type":"number","description":"随机种子（可选；不同厂商可能忽略）。","example":42},"width":{"type":"number","description":"宽度（像素）。目前仅 qwen 会严格使用；其他厂商可能仅用于推断横竖构图/选择 portrait/landscape。","example":1328},"height":{"type":"number","description":"高度（像素）。目前仅 qwen 会严格使用；其他厂商可能仅用于推断横竖构图/选择 portrait/landscape。","example":1328},"steps":{"type":"number","description":"采样步数（可选；不同厂商可能忽略）。","example":30},"cfgScale":{"type":"number","description":"提示词强度/CFG（可选；不同厂商可能忽略）。","example":7},"extras":{"type":"object","additionalProperties":{},"description":"额外参数透传（常用：modelAlias/modelKey/aspectRatio/referenceImages/resolution）。不同厂商/通道支持不一致。","example":{"modelAlias":"nano-banana-pro","aspectRatio":"1:1"}}},"required":["prompt"]},"example":{"vendor":"auto","kind":"text_to_image","prompt":"一张电影感海报，中文“lehuoAI”，高细节，干净背景","extras":{"modelAlias":"nano-banana-pro","aspectRatio":"1:1"}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"vendor":{"type":"string"},"result":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["chat","prompt_refine","text_to_image","image_to_prompt","image_to_video","text_to_video","image_edit"]},"status":{"type":"string","enum":["queued","running","succeeded","failed"]},"assets":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["image","video"]},"url":{"type":"string"},"thumbnailUrl":{"type":["string","null"]},"assetId":{"type":["string","null"]},"assetRefId":{"type":["string","null"]},"assetName":{"type":["string","null"]}},"required":["type","url"]}},"raw":{}},"required":["id","kind","status","assets"]}},"required":["vendor","result"]},"example":{"vendor":"gemini","result":{"id":"task_01HXYZ...","kind":"text_to_image","status":"queued","assets":[],"raw":{}}}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"issues":{"type":"array","items":{}}},"required":["error"]},"example":{"error":"Invalid request body","issues":[]}}}},"401":{"description":"Unauthorized (missing/invalid JWT or API key)","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"error":{"type":"string"},"code":{"type":"string"},"details":{}},"required":["message","error","code"]}}}}}}},"/public/video":{"post":{"tags":["Public API"],"summary":"生成视频 /public/video","description":"便捷视频接口：创建 text_to_video 任务（vendor=auto 会在系统级已启用且已配置的厂商列表中依次重试，直到成功或候选耗尽；可通过 extras.modelAlias 指定模型（推荐；兼容 extras.modelKey））。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vendor":{"type":"string","description":"指定厂商 key（默认 auto）；vendor=auto 会从系统级已启用且已配置的厂商列表中依次重试，直到成功或候选耗尽。","example":"auto"},"vendorCandidates":{"type":"array","items":{"type":"string"},"description":"当 vendor=auto 时用于限制候选厂商列表（仅用于自动回退范围与顺序；最终仍会过滤掉系统级未启用/未配置的厂商）。","example":["apimart"]},"prompt":{"type":"string","minLength":1},"durationSeconds":{"type":"number"},"extras":{"type":"object","additionalProperties":{}}},"required":["prompt"]},"example":{"vendor":"auto","prompt":"雨夜霓虹街头，一只白猫缓慢走过…","durationSeconds":10,"extras":{"modelAlias":"<YOUR_VIDEO_MODEL_ALIAS>"}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"vendor":{"type":"string"},"result":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["chat","prompt_refine","text_to_image","image_to_prompt","image_to_video","text_to_video","image_edit"]},"status":{"type":"string","enum":["queued","running","succeeded","failed"]},"assets":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["image","video"]},"url":{"type":"string"},"thumbnailUrl":{"type":["string","null"]},"assetId":{"type":["string","null"]},"assetRefId":{"type":["string","null"]},"assetName":{"type":["string","null"]}},"required":["type","url"]}},"raw":{}},"required":["id","kind","status","assets"]}},"required":["vendor","result"]},"example":{"vendor":"veo","result":{"id":"task_01HXYZ...","kind":"text_to_video","status":"queued","assets":[],"raw":{}}}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"issues":{"type":"array","items":{}}},"required":["error"]},"example":{"error":"Invalid request body","issues":[]}}}},"401":{"description":"Unauthorized (missing/invalid JWT or API key)","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"error":{"type":"string"},"code":{"type":"string"},"details":{}},"required":["message","error","code"]}}}}}}},"/public/tasks/result":{"post":{"tags":["Public API"],"summary":"查询任务结果 /public/tasks/result","description":"轮询任务状态与结果；支持 vendor=auto 自动基于 taskId 推断。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"taskId":{"type":"string","minLength":1},"vendor":{"type":"string","description":"任务所属厂商（可选）；不传或传 auto 时会尝试基于 taskId 推断；若无法推断则需要显式传 vendor。","example":"auto"},"taskKind":{"type":"string","enum":["chat","prompt_refine","text_to_image","image_to_prompt","image_to_video","text_to_video","image_edit"]},"prompt":{"type":["string","null"]}},"required":["taskId"]},"example":{"taskId":"task_01HXYZ...","taskKind":"text_to_video"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"vendor":{"type":"string"},"result":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["chat","prompt_refine","text_to_image","image_to_prompt","image_to_video","text_to_video","image_edit"]},"status":{"type":"string","enum":["queued","running","succeeded","failed"]},"assets":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["image","video"]},"url":{"type":"string"},"thumbnailUrl":{"type":["string","null"]},"assetId":{"type":["string","null"]},"assetRefId":{"type":["string","null"]},"assetName":{"type":["string","null"]}},"required":["type","url"]}},"raw":{}},"required":["id","kind","status","assets"]}},"required":["vendor","result"]},"example":{"vendor":"veo","result":{"id":"task_01HXYZ...","kind":"text_to_video","status":"running","assets":[],"raw":{}}}}}},"400":{"description":"Invalid request body / vendor required","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"error":{"type":"string"},"issues":{"type":"array","items":{}}},"required":["error"]},{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}},"required":["error","code"]}]},"example":{"error":"vendor is required (or the task vendor cannot be inferred)","code":"vendor_required"}}}},"401":{"description":"Unauthorized (missing/invalid JWT or API key)","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"error":{"type":"string"},"code":{"type":"string"},"details":{}},"required":["message","error","code"]}}}}}}}},"webhooks":{}}