{"openapi":"3.1.0","info":{"title":"JarvisHub 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。开源单工作区下不再按用户过滤。","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"]},"meta":{"type":"object","additionalProperties":{}}}},"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","imageFission","mosaic","composeVideo","audio","subtitle","webHero","pptDeck"]},"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"]},"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":{"sourceNodeId":{"type":"string","minLength":1},"assetId":{"type":"string","minLength":1},"assetRefId":{"type":"string","minLength":1},"url":{"type":"string","minLength":1},"role":{"type":"string","minLength":1},"weight":{"type":"number"},"relationshipKind":{"type":"string","enum":["primary","reference"]},"note":{"type":"string"},"name":{"type":"string"}}}},"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","single_variable_expansion","approved_keyframe_selection","video_plan","video_execution","result_persistence"]},"approvalStatus":{"type":"string","enum":["needs_confirmation","approved","rejected"]},"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}}}}}},"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","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","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":{}},"mergeStrategy":{"type":"string","enum":["skip-equal","overwrite","fail"]},"webHeroRewindFromPhase":{"type":"string","enum":["preview_generation","preview_visual_spec","asset_inventory","asset_resolution","section_codegen"]}},"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"},"webHeroRewinds":{"type":"array","items":{"type":"object","properties":{"nodeId":{"type":"string"},"rewindPhase":{"type":"string","enum":["preview_generation","preview_visual_spec","asset_inventory","asset_resolution","section_codegen"]},"clearedFields":{"type":"array","items":{"type":"string"}}},"required":["nodeId","rewindPhase","clearedFields"]},"default":[]}},"required":["deletedNodes","deletedEdges","createdNodes","createdEdges","patchedNodes","appendedArrays"]},"idMap":{"type":"object","properties":{"nodes":{"type":"object","additionalProperties":{"type":"string"}},"edges":{"type":"object","additionalProperties":{"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"]},"meta":{"type":"object","additionalProperties":{}}}}},"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","minLength":1},"providerKind":{"type":"string","enum":["remote","mcp"]},"args":{"type":"object","additionalProperties":{},"default":{}},"context":{"type":"object","properties":{"projectId":{"type":"string","minLength":1},"flowId":{"type":"string","minLength":1},"nodeId":{"type":"string","minLength":1}}},"run":{"type":"object","properties":{"runId":{"type":"string","minLength":1},"toolCallId":{"type":"string","minLength":1},"idempotencyKey":{"type":"string","minLength":1},"publicChatRunId":{"type":"string","minLength":1},"sessionKey":{"type":"string","minLength":1},"agentId":{"type":"string","minLength":1},"parentToolCallId":{"type":"string","minLength":1},"llmTurnIndex":{"type":"integer","minimum":0},"executionBatchIndex":{"type":"integer","minimum":0},"executionBatchCallIndex":{"type":"integer","minimum":0},"executionBatchCallCount":{"type":"integer","exclusiveMinimum":0},"toolCallIndex":{"type":"integer","minimum":0},"schemaVersion":{"type":"number","enum":[2]},"invocationPath":{"type":"array","items":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"layoutStageIndex":{"type":"integer","minimum":0},"executionBatchCallIndex":{"type":"integer","minimum":0},"executionBatchCallCount":{"type":"integer","exclusiveMinimum":0},"toolCallIndex":{"type":"integer","minimum":0},"toolCallId":{"type":"string","minLength":1}},"required":["agentId","layoutStageIndex","executionBatchCallIndex","executionBatchCallCount","toolCallIndex","toolCallId"]},"maxItems":8},"layoutStagePath":{"type":"array","items":{"type":"integer","minimum":0},"maxItems":8},"layoutItemPath":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","minimum":0},"count":{"type":"integer","exclusiveMinimum":0}},"required":["index","count"]},"maxItems":8}},"required":["toolCallId"]}},"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":{}},"effects":{"type":"object","additionalProperties":{}}},"required":["ok","content"]}}}}}}},"/public/vision":{"post":{"tags":["Public API"],"summary":"图像理解 /public/vision","description":"便捷图像理解接口：创建 image_to_prompt 任务并直接返回文本（常见用法：根据图片反推可复现的英文提示词）。模型来自统一 model config；支持外部 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 解析；未提供时只会使用统一 model config 中已启用的模型，不注入内置默认模型。","example":"your-enabled-vision-model"},"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":"your-enabled-vision-model","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":{"type":"object","properties":{}}}},"required":["error"]},"example":{"error":"Invalid request body","issues":[]}}}},"401":{"description":"Model config missing or invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":["object","null"],"properties":{}}},"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":{"type":"object","properties":{}}}},"required":["error"]},"example":{"error":"Invalid request body","issues":[]}}}},"401":{"description":"Model config missing or invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":["object","null"],"properties":{}}},"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"]},"sourceUrl":{"type":["string","null"]},"modelInputUrl":{"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":{"type":"object","properties":{}}}},"required":["error"]},"example":{"error":"Invalid request body","issues":[]}}}},"401":{"description":"Model config missing or invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":["object","null"],"properties":{}}},"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":"image_to_video","prompt":"雨夜霓虹街头，一只白猫缓慢走过…","extras":{"modelAlias":"your-video-model-alias","durationSeconds":10,"referenceImages":["https://example.com/reference.png"]}}}}}},"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"]},"sourceUrl":{"type":["string","null"]},"modelInputUrl":{"type":["string","null"]}},"required":["type","url"]}},"raw":{}},"required":["id","kind","status","assets"]}},"required":["vendor","result"]},"example":{"vendor":"apimart","result":{"id":"task_01HXYZ...","kind":"image_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":{"type":"object","properties":{}}}},"required":["error"]},{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{"type":["object","null"],"properties":{}}},"required":["error","code"]}]},"example":{"error":"Unsupported task kind for public API","code":"unsupported_task_kind","details":{"kind":"text_to_video"}}}}},"401":{"description":"Model config missing or invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":["object","null"],"properties":{}}},"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 时会默认启用（除非显式传 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":"一张电影感海报，中文“JarvisHub”，高细节，干净背景"},"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":"一张电影感海报，中文“JarvisHub”，高细节，干净背景","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"]},"sourceUrl":{"type":["string","null"]},"modelInputUrl":{"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":{"type":"object","properties":{}}}},"required":["error"]},"example":{"error":"Invalid request body","issues":[]}}}},"401":{"description":"Model config missing or invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":["object","null"],"properties":{}}},"required":["message","error","code"]}}}}}}},"/public/video":{"post":{"tags":["Public API"],"summary":"生成视频 /public/video","description":"便捷视频接口：创建 image_to_video 任务。视频生成必须通过 extras.referenceImages 提供至少一张真实参考图 URL；provider 与模型只来自统一 model config，不读取旧环境变量固定路由。","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","referenceImages":["https://example.com/reference.png"]}}}}},"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"]},"sourceUrl":{"type":["string","null"]},"modelInputUrl":{"type":["string","null"]}},"required":["type","url"]}},"raw":{}},"required":["id","kind","status","assets"]}},"required":["vendor","result"]},"example":{"vendor":"apimart","result":{"id":"task_01HXYZ...","kind":"image_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":{"type":"object","properties":{}}}},"required":["error"]},"example":{"error":"Invalid request body","issues":[]}}}},"401":{"description":"Model config missing or invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":["object","null"],"properties":{}}},"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":"image_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"]},"sourceUrl":{"type":["string","null"]},"modelInputUrl":{"type":["string","null"]}},"required":["type","url"]}},"raw":{}},"required":["id","kind","status","assets"]}},"required":["vendor","result"]},"example":{"vendor":"apimart","result":{"id":"task_01HXYZ...","kind":"image_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":{"type":"object","properties":{}}}},"required":["error"]},{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{"type":["object","null"],"properties":{}}},"required":["error","code"]}]},"example":{"error":"vendor is required (or the task vendor cannot be inferred)","code":"vendor_required"}}}},"401":{"description":"Model config missing or invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":["object","null"],"properties":{}}},"required":["message","error","code"]}}}}}}}},"webhooks":{}}