{ "components": { "schemas": { "Error": { "properties": { "code": { "description": "错误码，例如 error.invalid_input", "type": "string" }, "fields": { "additionalProperties": { "type": "string" }, "description": "这个错误附带的参数，例如参数不合法时的 detail", "type": "object" } }, "required": [ "code" ], "type": "object" } }, "securitySchemes": { "bearerAuth": { "description": "在 Favonis 设置的“开发者”中创建的 API 密钥（fvk_ 开头）", "scheme": "bearer", "type": "http" } } }, "info": { "title": "Favonis API", "version": "1.0.0" }, "openapi": "3.1.0", "paths": { "/v1/files/{id}": { "get": { "description": "返回文件信息和 2 小时内有效的下载地址。", "operationId": "get_file", "parameters": [ { "description": "文件 ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "文件 ID" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "size": { "type": "integer", "description": "字节数" }, "mime": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "download_url": { "type": "string", "description": "下载地址，到期前可直接 GET" }, "download_expires_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "size", "created_at", "updated_at", "download_url", "download_expires_at" ] } } }, "description": "成功" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "失败" } }, "summary": "查看文件" } }, "/v1/files/{id}/content": { "get": { "description": "读取文件的文字内容（文档、表格、幻灯片会先转成文字），从 offset 字节起最多返回 10 万字。文字还在提取中时返回 file_not_ready，稍后重试；没有文字内容的文件（例如图片）返回空 text。", "operationId": "read_file", "parameters": [ { "description": "文件 ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "文件 ID" } }, { "description": "起始字节位置，默认 0；上一次返回 truncated 时，传入上一次的 next_offset", "in": "query", "name": "offset", "required": false, "schema": { "type": "integer", "description": "起始字节位置，默认 0；上一次返回 truncated 时，传入上一次的 next_offset", "minimum": 0 } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "text": { "type": "string", "description": "文件的文字内容；没有文字内容的文件为空" }, "truncated": { "type": "boolean", "description": "之后仍有内容" }, "next_offset": { "type": "integer", "description": "truncated 时下一次读取的 offset" } }, "required": [ "id", "name", "text", "truncated" ] } } }, "description": "成功" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "失败" } }, "summary": "读取文件内容" } }, "/v1/me": { "get": { "description": "返回这个密钥代表的账号、可用积分，以及密钥本月的花费。", "operationId": "get_account", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "账号 ID" }, "name": { "type": "string", "description": "账号显示名" }, "workspace_id": { "type": "string", "description": "付款的工作区：个人账号是其本身，团队中的成员账号是所在团队" }, "points": { "type": "integer", "description": "工作区可用积分" }, "key": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "read_only": { "type": "boolean" }, "monthly_cap": { "type": [ "null", "integer" ], "description": "每月积分上限；为空表示不限" }, "month_points": { "type": "integer", "description": "本月通过该密钥发起的任务已消耗的积分" } }, "required": [ "id", "name", "read_only", "monthly_cap", "month_points" ] } }, "required": [ "id", "name", "workspace_id", "points", "key" ] } } }, "description": "成功" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "失败" } }, "summary": "查看账号" } }, "/v1/models": { "get": { "description": "列出可用的模型和各自的档位；新建任务时通过 model 和 level 指定，不指定时使用默认模型。", "operationId": "list_models", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": [ "null", "array" ], "items": { "type": "object", "properties": { "id": { "type": "string", "description": "新建任务时作为 model 传入" }, "name": { "type": "string" }, "levels": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "档位名称，新建任务时作为 level 传入；第一个是默认档位" }, "default": { "type": "boolean", "description": "不指定 model 时使用该模型" } }, "required": [ "id", "name", "levels", "default" ] } }, "next": { "type": "string", "description": "下一页的位置，作为 after 传回；无下一页时不返回" } }, "required": [ "data" ] } } }, "description": "成功" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "失败" } }, "summary": "列出模型" } }, "/v1/projects": { "get": { "description": "列出账号的项目，最近编辑的在前；新建任务时可通过 project_id 指定所在项目。", "operationId": "list_projects", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": [ "null", "array" ], "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "created_at", "updated_at" ] } }, "next": { "type": "string", "description": "下一页的位置，作为 after 传回；无下一页时不返回" } }, "required": [ "data" ] } } }, "description": "成功" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "失败" } }, "summary": "列出项目" } }, "/v1/projects/{id}/files": { "get": { "description": "列出项目中一个文件夹的直接子项，path 为空时是根目录。任务的 project_id 即它所在的项目。", "operationId": "list_project_files", "parameters": [ { "description": "项目 ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "项目 ID" } }, { "description": "文件夹在项目中的路径，例如 reports/2026；不填时为根目录", "in": "query", "name": "path", "required": false, "schema": { "type": "string", "description": "文件夹在项目中的路径，例如 reports/2026；不填时为根目录" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": [ "null", "array" ], "items": { "type": "object", "properties": { "name": { "type": "string" }, "path": { "type": "string" }, "kind": { "type": "string", "description": "file 或 folder" }, "file_id": { "type": "string", "description": "文件 ID，仅文件有" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "name", "path", "kind", "updated_at" ] } }, "next": { "type": "string", "description": "下一页的位置，作为 after 传回；无下一页时不返回" } }, "required": [ "data" ] } } }, "description": "成功" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "失败" } }, "summary": "列出项目文件" } }, "/v1/tasks": { "get": { "description": "按创建时间倒序列出任务，不带结果。", "operationId": "list_tasks", "parameters": [ { "description": "只列出该状态的任务：running、waiting_input、paused、completed 或 cancelled", "in": "query", "name": "status", "required": false, "schema": { "type": "string", "description": "只列出该状态的任务：running、waiting_input、paused、completed 或 cancelled", "enum": [ "running", "waiting_input", "paused", "completed", "cancelled" ] } }, { "description": "每页最多条数，1 到 100，默认 20", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "description": "每页最多条数，1 到 100，默认 20", "minimum": 1, "maximum": 100 } }, { "description": "上一页返回的 next", "in": "query", "name": "after", "required": false, "schema": { "type": "string", "description": "上一页返回的 next" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": [ "null", "array" ], "items": { "type": "object", "properties": { "id": { "type": "string", "description": "任务 ID" }, "url": { "type": "string", "description": "在 Favonis 中打开该任务的地址" }, "title": { "type": "string", "description": "任务标题；第一轮回复结束前可能为空" }, "status": { "type": "string", "description": "running、waiting_input、paused、completed 或 cancelled；以后可能增加新值" }, "reason": { "type": "string", "description": "status 为 paused 时停下的原因，例如 insufficient_credits、by_user；以后可能增加新值" }, "project_id": { "type": [ "null", "string" ], "description": "任务所在的项目" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "result": { "type": [ "null", "object" ], "properties": { "text": { "type": "string", "description": "回复的最后一段正文（Markdown）；仅在 completed 和 waiting_input 时返回" }, "files": { "type": [ "null", "array" ], "items": { "type": "object", "properties": { "id": { "type": "string", "description": "文件 ID，可通过 GET /v1/files/{id} 获取下载地址" }, "version_id": { "type": "string" }, "path": { "type": "string", "description": "文件在项目里的路径" }, "name": { "type": "string" }, "size": { "type": "integer", "description": "字节数" }, "mime": { "type": "string" } }, "required": [ "id", "version_id", "path", "name", "size" ] }, "description": "这一轮交付的文件" }, "questions": { "type": [ "null", "array" ], "items": { "type": "object", "properties": { "id": { "type": "string", "description": "问题 ID，回答时作为 question_id 传回" }, "text": { "type": "string" }, "options": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "建议的回答；也可以回答其他内容" } }, "required": [ "id", "text" ] }, "description": "status 为 waiting_input 时等待回答的问题" }, "points": { "type": "integer", "description": "这一轮已结算的积分消耗" } }, "description": "最新一轮回复的结果；任务列表里不返回", "required": [ "text", "files", "points" ] } }, "required": [ "id", "url", "title", "status", "project_id", "created_at", "updated_at" ] } }, "next": { "type": "string", "description": "下一页的位置，作为 after 传回；无下一页时不返回" } }, "required": [ "data" ] } } }, "description": "成功" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "失败" } }, "summary": "列出任务" }, "post": { "description": "把一件工作交给 Favonis：它在云端电脑上规划并完成，可以调研、分析数据、写文档和幻灯片、写代码。执行中不会停下来提问，遇到不确定的地方按合理的假设完成并在结果中说明。立即返回任务，可通过 get_task 的 wait 参数等待结果。会消耗积分。", "operationId": "create_task", "parameters": [ { "description": "同一个密钥、同一个键重发时返回第一次建好的任务，不会重复建", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "description": "要交给 Favonis 的工作，描述越具体越好", "maxLength": 1000000, "pattern": "\\S" }, "project_id": { "type": "string", "description": "任务所在的项目；不填时是一个独立任务，有自己的文件" }, "file_ids": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "附件的文件 ID，由完成上传接口返回" }, "model": { "type": "string", "description": "模型 ID，见 list_models；不填时使用默认模型" }, "level": { "type": "string", "description": "模型的档位名称，见 list_models；不填时使用该模型的第一档" } }, "required": [ "prompt" ], "additionalProperties": false } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "任务 ID" }, "url": { "type": "string", "description": "在 Favonis 中打开该任务的地址" }, "title": { "type": "string", "description": "任务标题；第一轮回复结束前可能为空" }, "status": { "type": "string", "description": "running、waiting_input、paused、completed 或 cancelled；以后可能增加新值" }, "reason": { "type": "string", "description": "status 为 paused 时停下的原因，例如 insufficient_credits、by_user；以后可能增加新值" }, "project_id": { "type": [ "null", "string" ], "description": "任务所在的项目" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "result": { "type": [ "null", "object" ], "properties": { "text": { "type": "string", "description": "回复的最后一段正文（Markdown）；仅在 completed 和 waiting_input 时返回" }, "files": { "type": [ "null", "array" ], "items": { "type": "object", "properties": { "id": { "type": "string", "description": "文件 ID，可通过 GET /v1/files/{id} 获取下载地址" }, "version_id": { "type": "string" }, "path": { "type": "string", "description": "文件在项目里的路径" }, "name": { "type": "string" }, "size": { "type": "integer", "description": "字节数" }, "mime": { "type": "string" } }, "required": [ "id", "version_id", "path", "name", "size" ] }, "description": "这一轮交付的文件" }, "questions": { "type": [ "null", "array" ], "items": { "type": "object", "properties": { "id": { "type": "string", "description": "问题 ID，回答时作为 question_id 传回" }, "text": { "type": "string" }, "options": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "建议的回答；也可以回答其他内容" } }, "required": [ "id", "text" ] }, "description": "status 为 waiting_input 时等待回答的问题" }, "points": { "type": "integer", "description": "这一轮已结算的积分消耗" } }, "description": "最新一轮回复的结果；任务列表里不返回", "required": [ "text", "files", "points" ] } }, "required": [ "id", "url", "title", "status", "project_id", "created_at", "updated_at" ] } } }, "description": "成功" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "失败" } }, "summary": "新建任务" } }, "/v1/tasks/{id}": { "delete": { "description": "把任务移到回收站，可在 Favonis 里恢复；回收站里的任务不再出现在列表里。", "operationId": "delete_task", "parameters": [ { "description": "任务 ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "任务 ID" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "id", "deleted" ] } } }, "description": "成功" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "失败" } }, "summary": "删除任务" }, "get": { "description": "返回任务的状态和最新一轮的结果。wait 大于 0 且任务仍在运行时，最多等待 wait 秒，任务停下后立即返回。", "operationId": "get_task", "parameters": [ { "description": "任务 ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "任务 ID" } }, { "description": "任务仍在运行时最多等待的秒数，0 到 25；任务停下后立即返回", "in": "query", "name": "wait", "required": false, "schema": { "type": "integer", "description": "任务仍在运行时最多等待的秒数，0 到 25；任务停下后立即返回", "minimum": 0, "maximum": 25 } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "任务 ID" }, "url": { "type": "string", "description": "在 Favonis 中打开该任务的地址" }, "title": { "type": "string", "description": "任务标题；第一轮回复结束前可能为空" }, "status": { "type": "string", "description": "running、waiting_input、paused、completed 或 cancelled；以后可能增加新值" }, "reason": { "type": "string", "description": "status 为 paused 时停下的原因，例如 insufficient_credits、by_user；以后可能增加新值" }, "project_id": { "type": [ "null", "string" ], "description": "任务所在的项目" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "result": { "type": [ "null", "object" ], "properties": { "text": { "type": "string", "description": "回复的最后一段正文（Markdown）；仅在 completed 和 waiting_input 时返回" }, "files": { "type": [ "null", "array" ], "items": { "type": "object", "properties": { "id": { "type": "string", "description": "文件 ID，可通过 GET /v1/files/{id} 获取下载地址" }, "version_id": { "type": "string" }, "path": { "type": "string", "description": "文件在项目里的路径" }, "name": { "type": "string" }, "size": { "type": "integer", "description": "字节数" }, "mime": { "type": "string" } }, "required": [ "id", "version_id", "path", "name", "size" ] }, "description": "这一轮交付的文件" }, "questions": { "type": [ "null", "array" ], "items": { "type": "object", "properties": { "id": { "type": "string", "description": "问题 ID，回答时作为 question_id 传回" }, "text": { "type": "string" }, "options": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "建议的回答；也可以回答其他内容" } }, "required": [ "id", "text" ] }, "description": "status 为 waiting_input 时等待回答的问题" }, "points": { "type": "integer", "description": "这一轮已结算的积分消耗" } }, "description": "最新一轮回复的结果；任务列表里不返回", "required": [ "text", "files", "points" ] } }, "required": [ "id", "url", "title", "status", "project_id", "created_at", "updated_at" ] } } }, "description": "成功" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "失败" } }, "summary": "查看任务" } }, "/v1/tasks/{id}/cancel": { "post": { "description": "停止正在进行的这一轮，任务变为 cancelled；之后仍可发消息开始新的一轮。", "operationId": "cancel_task", "parameters": [ { "description": "任务 ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "任务 ID" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "任务 ID" }, "url": { "type": "string", "description": "在 Favonis 中打开该任务的地址" }, "title": { "type": "string", "description": "任务标题；第一轮回复结束前可能为空" }, "status": { "type": "string", "description": "running、waiting_input、paused、completed 或 cancelled；以后可能增加新值" }, "reason": { "type": "string", "description": "status 为 paused 时停下的原因，例如 insufficient_credits、by_user；以后可能增加新值" }, "project_id": { "type": [ "null", "string" ], "description": "任务所在的项目" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "result": { "type": [ "null", "object" ], "properties": { "text": { "type": "string", "description": "回复的最后一段正文（Markdown）；仅在 completed 和 waiting_input 时返回" }, "files": { "type": [ "null", "array" ], "items": { "type": "object", "properties": { "id": { "type": "string", "description": "文件 ID，可通过 GET /v1/files/{id} 获取下载地址" }, "version_id": { "type": "string" }, "path": { "type": "string", "description": "文件在项目里的路径" }, "name": { "type": "string" }, "size": { "type": "integer", "description": "字节数" }, "mime": { "type": "string" } }, "required": [ "id", "version_id", "path", "name", "size" ] }, "description": "这一轮交付的文件" }, "questions": { "type": [ "null", "array" ], "items": { "type": "object", "properties": { "id": { "type": "string", "description": "问题 ID，回答时作为 question_id 传回" }, "text": { "type": "string" }, "options": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "建议的回答；也可以回答其他内容" } }, "required": [ "id", "text" ] }, "description": "status 为 waiting_input 时等待回答的问题" }, "points": { "type": "integer", "description": "这一轮已结算的积分消耗" } }, "description": "最新一轮回复的结果；任务列表里不返回", "required": [ "text", "files", "points" ] } }, "required": [ "id", "url", "title", "status", "project_id", "created_at", "updated_at" ] } } }, "description": "成功" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "失败" } }, "summary": "取消任务" } }, "/v1/tasks/{id}/messages": { "post": { "description": "按任务当前状态处理：运行中作为补充说明，等待回答时作为回答，暂停时作为补充并继续执行（不带内容即直接继续），已完成或已取消时开始新的一轮。会消耗积分。", "operationId": "send_task_message", "parameters": [ { "description": "任务 ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string", "description": "任务 ID" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "description": "消息内容，最多 100 万字；回答问题时即为答案，最多 10 万字", "maxLength": 1000000 }, "file_ids": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "附件的文件 ID，由完成上传接口返回" }, "question_id": { "type": "string", "description": "任务等待回答时要回答的问题；不填时回答第一个" } }, "additionalProperties": false } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "任务 ID" }, "url": { "type": "string", "description": "在 Favonis 中打开该任务的地址" }, "title": { "type": "string", "description": "任务标题；第一轮回复结束前可能为空" }, "status": { "type": "string", "description": "running、waiting_input、paused、completed 或 cancelled；以后可能增加新值" }, "reason": { "type": "string", "description": "status 为 paused 时停下的原因，例如 insufficient_credits、by_user；以后可能增加新值" }, "project_id": { "type": [ "null", "string" ], "description": "任务所在的项目" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "result": { "type": [ "null", "object" ], "properties": { "text": { "type": "string", "description": "回复的最后一段正文（Markdown）；仅在 completed 和 waiting_input 时返回" }, "files": { "type": [ "null", "array" ], "items": { "type": "object", "properties": { "id": { "type": "string", "description": "文件 ID，可通过 GET /v1/files/{id} 获取下载地址" }, "version_id": { "type": "string" }, "path": { "type": "string", "description": "文件在项目里的路径" }, "name": { "type": "string" }, "size": { "type": "integer", "description": "字节数" }, "mime": { "type": "string" } }, "required": [ "id", "version_id", "path", "name", "size" ] }, "description": "这一轮交付的文件" }, "questions": { "type": [ "null", "array" ], "items": { "type": "object", "properties": { "id": { "type": "string", "description": "问题 ID，回答时作为 question_id 传回" }, "text": { "type": "string" }, "options": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "建议的回答；也可以回答其他内容" } }, "required": [ "id", "text" ] }, "description": "status 为 waiting_input 时等待回答的问题" }, "points": { "type": "integer", "description": "这一轮已结算的积分消耗" } }, "description": "最新一轮回复的结果；任务列表里不返回", "required": [ "text", "files", "points" ] } }, "required": [ "id", "url", "title", "status", "project_id", "created_at", "updated_at" ] } } }, "description": "成功" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "失败" } }, "summary": "给任务发消息" } }, "/v1/uploads": { "post": { "description": "上传一个文件作为任务附件，最大 32 MiB：先提交文件大小和 SHA-256 申请上传，按返回的地址和表单字段直传，再调用完成上传。内容已存在时无需直传，直接完成上传。", "operationId": "create_upload", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "文件名，带扩展名，最多 255 字", "minLength": 1, "maxLength": 255, "pattern": "^[^/\\\\]+$" }, "size": { "type": "integer", "description": "字节数，最大 32 MiB", "minimum": 0 }, "sha256": { "type": "string", "description": "文件内容的 SHA-256，64 位小写十六进制", "pattern": "^[0-9a-f]{64}$" }, "mime": { "type": "string", "description": "文件类型，最多 100 个字符；不填时按文件名判断", "maxLength": 100, "pattern": "^[\\x20-\\x7e]*$" } }, "required": [ "name", "size", "sha256" ], "additionalProperties": false } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "完成上传时传回" }, "upload": { "type": [ "null", "object" ], "properties": { "url": { "type": "string", "description": "以 multipart/form-data 格式 POST 到该地址" }, "fields": { "type": "object", "description": "按原样放入表单的字段；文件内容作为最后一个字段 file 提交", "additionalProperties": { "type": "string" } } }, "description": "直传的地址和表单字段；不返回时表示内容已存在，直接完成上传", "required": [ "url", "fields" ] } }, "required": [ "token" ] } } }, "description": "成功" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "失败" } }, "summary": "申请上传" } }, "/v1/uploads/complete": { "post": { "description": "直传完成后调用，返回文件；将文件 ID 放入新建任务或发消息的 file_ids。附件 48 小时内未使用将被清理。", "operationId": "complete_upload", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "create_upload 返回的 token" } }, "required": [ "token" ], "additionalProperties": false } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "size": { "type": "integer", "description": "字节数" }, "mime": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "size", "created_at", "updated_at" ] } } }, "description": "成功" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "失败" } }, "summary": "完成上传" } } }, "security": [ { "bearerAuth": [] } ], "servers": [ { "url": "https://api.favonis.com" } ] }