API 参考

本页列出 Favonis API v1 的全部接口，内容由 OpenAPI 文档生成。接口地址是https://api.favonis.com，每个请求都要带上请求头Authorization: Bearer fvk_...，见认证与密钥。

OpenAPI 文档：https://api.favonis.com/v1/openapi.json（OpenAPI 3.1，当前版本 1.0.0），公开访问，无需密钥，可以用它生成客户端代码或导入接口调试工具。
请求体和返回都是 JSON；只读密钥只能调用 GET 接口。
失败时返回 HTTP 状态码和 {"code": "error.…", "fields": {…}}，见错误码与限制。
返回里可能出现本页没有列出的字段和取值，请忽略不认识的部分。

任务

新建任务

POST/v1/tasks

把一件工作交给 Favonis：它在云端电脑上规划并完成，可以调研、分析数据、写文档和幻灯片、写代码。执行中不会停下来提问，遇到不确定的地方按合理的假设完成并在结果中说明。立即返回任务，可通过 get_task 的 wait 参数等待结果。会消耗积分。

请求头

Idempotency-Keystring
同一个密钥、同一个键重发时返回第一次建好的任务，不会重复建

请求体

promptstring必填
要交给 Favonis 的工作，描述越具体越好
project_idstring
任务所在的项目；不填时是一个独立任务，有自己的文件
file_idsstring[] | null
附件的文件 ID，由完成上传接口返回
modelstring
模型 ID，见 list_models；不填时使用默认模型
levelstring
模型的档位名称，见 list_models；不填时使用该模型的第一档

idstring
任务 ID
urlstring
在 Favonis 中打开该任务的地址
titlestring
任务标题；第一轮回复结束前可能为空
statusstring
running、waiting_input、paused、completed 或 cancelled；以后可能增加新值
reasonstring可选
status 为 paused 时停下的原因，例如 insufficient_credits、by_user；以后可能增加新值
project_idstring | null
任务所在的项目
created_atstring
updated_atstring
resultobject | null可选
最新一轮回复的结果；任务列表里不返回
result 的 4 个字段
- textstring
  回复的最后一段正文（Markdown）；仅在 completed 和 waiting_input 时返回
- filesobject[] | null
  这一轮交付的文件
  files 的 6 个字段
  - idstring
    文件 ID，可通过 GET /v1/files/{id} 获取下载地址
  - version_idstring
  - pathstring
    文件在项目里的路径
  - namestring
  - sizeinteger
    字节数
  - mimestring可选
- questionsobject[] | null可选
  status 为 waiting_input 时等待回答的问题
  questions 的 3 个字段
  - idstring
    问题 ID，回答时作为 question_id 传回
  - textstring
  - optionsstring[] | null可选
    建议的回答；也可以回答其他内容
- pointsinteger
  这一轮已结算的积分消耗

查看任务

GET/v1/tasks/{id}

返回任务的状态和最新一轮的结果。wait 大于 0 且任务仍在运行时，最多等待 wait 秒，任务停下后立即返回。

路径参数

idstring必填
任务 ID

查询参数

waitinteger
任务仍在运行时最多等待的秒数，0 到 25；任务停下后立即返回

idstring
任务 ID
urlstring
在 Favonis 中打开该任务的地址
titlestring
任务标题；第一轮回复结束前可能为空
statusstring
running、waiting_input、paused、completed 或 cancelled；以后可能增加新值
reasonstring可选
status 为 paused 时停下的原因，例如 insufficient_credits、by_user；以后可能增加新值
project_idstring | null
任务所在的项目
created_atstring
updated_atstring
resultobject | null可选
最新一轮回复的结果；任务列表里不返回
result 的 4 个字段
- textstring
  回复的最后一段正文（Markdown）；仅在 completed 和 waiting_input 时返回
- filesobject[] | null
  这一轮交付的文件
  files 的 6 个字段
  - idstring
    文件 ID，可通过 GET /v1/files/{id} 获取下载地址
  - version_idstring
  - pathstring
    文件在项目里的路径
  - namestring
  - sizeinteger
    字节数
  - mimestring可选
- questionsobject[] | null可选
  status 为 waiting_input 时等待回答的问题
  questions 的 3 个字段
  - idstring
    问题 ID，回答时作为 question_id 传回
  - textstring
  - optionsstring[] | null可选
    建议的回答；也可以回答其他内容
- pointsinteger
  这一轮已结算的积分消耗

列出任务

GET/v1/tasks

按创建时间倒序列出任务，不带结果。

查询参数

statusstring
只列出该状态的任务：running、waiting_input、paused、completed 或 cancelled
limitinteger
每页最多条数，1 到 100，默认 20
afterstring
上一页返回的 next

dataobject[] | null
data 的 9 个字段
- idstring
  任务 ID
- urlstring
  在 Favonis 中打开该任务的地址
- titlestring
  任务标题；第一轮回复结束前可能为空
- statusstring
  running、waiting_input、paused、completed 或 cancelled；以后可能增加新值
- reasonstring可选
  status 为 paused 时停下的原因，例如 insufficient_credits、by_user；以后可能增加新值
- project_idstring | null
  任务所在的项目
- created_atstring
- updated_atstring
- resultobject | null可选
  最新一轮回复的结果；任务列表里不返回
  result 的 4 个字段
  - textstring
    回复的最后一段正文（Markdown）；仅在 completed 和 waiting_input 时返回
  - filesobject[] | null
    这一轮交付的文件
    files 的 6 个字段
    idstring
    文件 ID，可通过 GET /v1/files/{id} 获取下载地址
    version_idstring
    pathstring
    文件在项目里的路径
    namestring
    sizeinteger
    字节数
    mimestring可选
  - questionsobject[] | null可选
    status 为 waiting_input 时等待回答的问题
    questions 的 3 个字段
    idstring
    问题 ID，回答时作为 question_id 传回
    textstring
    optionsstring[] | null可选
    建议的回答；也可以回答其他内容
  - pointsinteger
    这一轮已结算的积分消耗
nextstring可选
下一页的位置，作为 after 传回；无下一页时不返回

给任务发消息

POST/v1/tasks/{id}/messages

按任务当前状态处理：运行中作为补充说明，等待回答时作为回答，暂停时作为补充并继续执行（不带内容即直接继续），已完成或已取消时开始新的一轮。会消耗积分。

路径参数

idstring必填
任务 ID

请求体

textstring
消息内容，最多 100 万字；回答问题时即为答案，最多 10 万字
file_idsstring[] | null
附件的文件 ID，由完成上传接口返回
question_idstring
任务等待回答时要回答的问题；不填时回答第一个

idstring
任务 ID
urlstring
在 Favonis 中打开该任务的地址
titlestring
任务标题；第一轮回复结束前可能为空
statusstring
running、waiting_input、paused、completed 或 cancelled；以后可能增加新值
reasonstring可选
status 为 paused 时停下的原因，例如 insufficient_credits、by_user；以后可能增加新值
project_idstring | null
任务所在的项目
created_atstring
updated_atstring
resultobject | null可选
最新一轮回复的结果；任务列表里不返回
result 的 4 个字段
- textstring
  回复的最后一段正文（Markdown）；仅在 completed 和 waiting_input 时返回
- filesobject[] | null
  这一轮交付的文件
  files 的 6 个字段
  - idstring
    文件 ID，可通过 GET /v1/files/{id} 获取下载地址
  - version_idstring
  - pathstring
    文件在项目里的路径
  - namestring
  - sizeinteger
    字节数
  - mimestring可选
- questionsobject[] | null可选
  status 为 waiting_input 时等待回答的问题
  questions 的 3 个字段
  - idstring
    问题 ID，回答时作为 question_id 传回
  - textstring
  - optionsstring[] | null可选
    建议的回答；也可以回答其他内容
- pointsinteger
  这一轮已结算的积分消耗

取消任务

POST/v1/tasks/{id}/cancel

停止正在进行的这一轮，任务变为 cancelled；之后仍可发消息开始新的一轮。

路径参数

idstring必填
任务 ID

idstring
任务 ID
urlstring
在 Favonis 中打开该任务的地址
titlestring
任务标题；第一轮回复结束前可能为空
statusstring
running、waiting_input、paused、completed 或 cancelled；以后可能增加新值
reasonstring可选
status 为 paused 时停下的原因，例如 insufficient_credits、by_user；以后可能增加新值
project_idstring | null
任务所在的项目
created_atstring
updated_atstring
resultobject | null可选
最新一轮回复的结果；任务列表里不返回
result 的 4 个字段
- textstring
  回复的最后一段正文（Markdown）；仅在 completed 和 waiting_input 时返回
- filesobject[] | null
  这一轮交付的文件
  files 的 6 个字段
  - idstring
    文件 ID，可通过 GET /v1/files/{id} 获取下载地址
  - version_idstring
  - pathstring
    文件在项目里的路径
  - namestring
  - sizeinteger
    字节数
  - mimestring可选
- questionsobject[] | null可选
  status 为 waiting_input 时等待回答的问题
  questions 的 3 个字段
  - idstring
    问题 ID，回答时作为 question_id 传回
  - textstring
  - optionsstring[] | null可选
    建议的回答；也可以回答其他内容
- pointsinteger
  这一轮已结算的积分消耗

删除任务

DELETE/v1/tasks/{id}

把任务移到回收站，可在 Favonis 里恢复；回收站里的任务不再出现在列表里。

路径参数

idstring必填
任务 ID

idstring
deletedboolean

文件

申请上传

POST/v1/uploads

上传一个文件作为任务附件，最大 32 MiB：先提交文件大小和 SHA-256 申请上传，按返回的地址和表单字段直传，再调用完成上传。内容已存在时无需直传，直接完成上传。

请求体

namestring必填
文件名，带扩展名，最多 255 字
sizeinteger必填
字节数，最大 32 MiB
sha256string必填
文件内容的 SHA-256，64 位小写十六进制
mimestring
文件类型，最多 100 个字符；不填时按文件名判断

tokenstring
完成上传时传回
uploadobject | null可选
直传的地址和表单字段；不返回时表示内容已存在，直接完成上传
upload 的 2 个字段
- urlstring
  以 multipart/form-data 格式 POST 到该地址
- fieldsmap<string, string>
  按原样放入表单的字段；文件内容作为最后一个字段 file 提交

完成上传

POST/v1/uploads/complete

直传完成后调用，返回文件；将文件 ID 放入新建任务或发消息的 file_ids。附件 48 小时内未使用将被清理。

请求体

tokenstring必填
create_upload 返回的 token

idstring
namestring
sizeinteger
字节数
mimestring可选
created_atstring
updated_atstring

查看文件

GET/v1/files/{id}

返回文件信息和 2 小时内有效的下载地址。

路径参数

idstring必填
文件 ID

idstring
namestring
sizeinteger
字节数
mimestring可选
created_atstring
updated_atstring
download_urlstring
下载地址，到期前可直接 GET
download_expires_atstring

读取文件内容

GET/v1/files/{id}/content

读取文件的文字内容（文档、表格、幻灯片会先转成文字），从 offset 字节起最多返回 10 万字。文字还在提取中时返回 file_not_ready，稍后重试；没有文字内容的文件（例如图片）返回空 text。

路径参数

idstring必填
文件 ID

查询参数

offsetinteger
起始字节位置，默认 0；上一次返回 truncated 时，传入上一次的 next_offset

idstring
namestring
textstring
文件的文字内容；没有文字内容的文件为空
truncatedboolean
之后仍有内容
next_offsetinteger可选
truncated 时下一次读取的 offset

项目

列出项目

GET/v1/projects

列出账号的项目，最近编辑的在前；新建任务时可通过 project_id 指定所在项目。

dataobject[] | null
data 的 4 个字段
- idstring
- namestring
- created_atstring
- updated_atstring
nextstring可选
下一页的位置，作为 after 传回；无下一页时不返回

列出项目文件

GET/v1/projects/{id}/files

列出项目中一个文件夹的直接子项，path 为空时是根目录。任务的 project_id 即它所在的项目。

路径参数

idstring必填
项目 ID

查询参数

pathstring
文件夹在项目中的路径，例如 reports/2026；不填时为根目录

dataobject[] | null
data 的 5 个字段
- namestring
- pathstring
- kindstring
  file 或 folder
- file_idstring可选
  文件 ID，仅文件有
- updated_atstring
nextstring可选
下一页的位置，作为 after 传回；无下一页时不返回

模型与账号

列出模型

GET/v1/models

列出可用的模型和各自的档位；新建任务时通过 model 和 level 指定，不指定时使用默认模型。

dataobject[] | null
data 的 4 个字段
- idstring
  新建任务时作为 model 传入
- namestring
- levelsstring[] | null
  档位名称，新建任务时作为 level 传入；第一个是默认档位
- defaultboolean
  不指定 model 时使用该模型
nextstring可选
下一页的位置，作为 after 传回；无下一页时不返回

查看账号

GET/v1/me

返回这个密钥代表的账号、可用积分，以及密钥本月的花费。

idstring
账号 ID
namestring
账号显示名
workspace_idstring
付款的工作区：个人账号是其本身，团队中的成员账号是所在团队
pointsinteger
工作区可用积分
keyobject
key 的 5 个字段
- idstring
- namestring
- read_onlyboolean
- monthly_capinteger | null
  每月积分上限；为空表示不限
- month_pointsinteger
  本月通过该密钥发起的任务已消耗的积分