概览与快速开始

Favonis API 让你的程序把工作交给 Favonis：发出一句话即新建一个任务，Favonis 在云端电脑上规划并完成调研、数据分析、写文档和幻灯片、写代码这类多步骤的工作，再把结果和交付的文件交还给程序。每个任务都是 Favonis 里的一段工作对话，在应用的侧边栏中同样看得到，随时能打开查看过程、接着对话。Claude Code、Cursor 等 AI 工具也能通过 MCP 新建任务、查看结果和读取文件的文字内容。

能做什么

新建任务、查看状态和等待结果，向进行中的任务补充说明，让暂停的任务继续
上传附件，下载或读取任务交付的文件
列出项目和项目里的文件，在已有项目中接着工作
任务停下时通过 Webhook 接收推送，不必反复查询
在支持 MCP 的 AI 工具中新建和查看任务、读取文件的文字内容，见 MCP

通过 API 发起的任务和在应用里一样按实际用量扣除积分，套餐和价格见定价。使用前请阅读《Favonis API 使用规则》。

基本信息

项目	内容
REST	`https://api.favonis.com/v1`
MCP	`https://api.favonis.com/mcp`
鉴权	请求头 `Authorization: Bearer fvk_...`，见认证与密钥
数据格式	请求体和返回都是 UTF-8 编码的 JSON，时间是 RFC 3339 格式的字符串
OpenAPI	`https://api.favonis.com/v1/openapi.json`，无需密钥；全部接口见 API 参考

API 只供服务端调用，不开放跨域访问。请不要在网页前端调用 API，也不要把密钥写进前端代码。

快速开始

1. 创建 API 密钥

在 Favonis 中打开 设置 → 开发者 → API 密钥，新建一个密钥。密钥以 fvk_ 开头，只显示一次，请立即复制保存。创建前需要完成实名认证，步骤见如何创建和管理 API 密钥？

把密钥放进环境变量，下面的示例都从这里读取：

export FAVONIS_API_KEY="fvk_..."

2. 新建任务

通过 API 发起的任务无人值守：Favonis 不会中途提问，遇到不确定的地方按合理的假设完成，所以 prompt 要写完整。

curl https://api.favonis.com/v1/tasks \
  -H "Authorization: Bearer $FAVONIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "整理国内主要固态电池厂商公开的产能规划，交付一份 Excel 表格"}'

请求立即返回任务对象，这时 status 是 running：

{
	"id": "0196a3f2-5c1e-7d48-b2a9-6e0f41c8d375",
	"url": "https://ai.favonis.com/app/0196a3f2-5c1e-7d48-b2a9-6e0f41c8d375",
	"title": "",
	"status": "running",
	"project_id": "0196a3f2-5b90-7a11-8c3d-91e2f7a04b62",
	"created_at": "2026-11-06T09:12:03Z",
	"updated_at": "2026-11-06T09:12:03Z",
	"result": { "text": "", "files": [], "points": 0 }
}

url 在 Favonis 中打开这个任务，可以实时查看它正在做什么。

3. 等待结果

带上 wait 参数查看任务：任务仍在运行时，请求最多等待 25 秒，任务停下后立即返回。重复这一步，直到 status 不再是 running。

curl "https://api.favonis.com/v1/tasks/$TASK_ID?wait=25" \
  -H "Authorization: Bearer $FAVONIS_API_KEY"

完成后 status 变为 completed，result.text 是回复的最后一段正文，result.files 列出这一轮交付的文件：

{
	"id": "0196a3f2-5c1e-7d48-b2a9-6e0f41c8d375",
	"status": "completed",
	"title": "国内固态电池厂商产能规划",
	"result": {
		"text": "已整理 12 家厂商公开的产能规划，表格按投产年份排序……",
		"files": [
			{
				"id": "0196a3f9-1d27-7e05-a8c4-3b6f2d91e0a8",
				"version_id": "0196a3f9-1d28-7c90-9f13-5a7e04b6c2d1",
				"path": "固态电池产能规划.xlsx",
				"name": "固态电池产能规划.xlsx",
				"size": 48213,
				"mime": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
			}
		],
		"points": 1280
	}
}

用 GET /v1/files/{id} 取得文件的下载地址，见文件与项目。任务也可能停在 paused，例如空间的积分用完时，各状态的含义和处理方式见任务。

完整示例

下面两段程序完成同一件事：新建任务，等待它停下，再打印回复和交付文件的下载地址。查看任务时，HTTP 客户端的超时要长于 wait 的秒数。

Python

import os

import requests

API = "https://api.favonis.com/v1"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['FAVONIS_API_KEY']}"


def call(method, path, **kwargs):
    response = session.request(method, f"{API}{path}", timeout=60, **kwargs)
    if not response.ok:
        raise RuntimeError(f"{response.status_code} {response.json().get('code')}")
    return response.json()


task = call("POST", "/tasks", json={"prompt": "整理国内主要固态电池厂商公开的产能规划，交付一份 Excel 表格"})
while task["status"] == "running":
    task = call("GET", f"/tasks/{task['id']}", params={"wait": 25})

result = task.get("result") or {}
print(task["status"], result.get("text"))
for file in result.get("files") or []:
    print(file["name"], call("GET", f"/files/{file['id']}")["download_url"])

Node.js

const API = "https://api.favonis.com/v1";
const headers = {
	Authorization: `Bearer ${process.env.FAVONIS_API_KEY}`,
	"Content-Type": "application/json",
};

async function call(method, path, body) {
	const response = await fetch(`${API}${path}`, {
		method,
		headers,
		body: body && JSON.stringify(body),
		signal: AbortSignal.timeout(60_000),
	});
	const data = await response.json();
	if (!response.ok) throw new Error(`${response.status} ${data.code}`);
	return data;
}

let task = await call("POST", "/tasks", {
	prompt: "整理国内主要固态电池厂商公开的产能规划，交付一份 Excel 表格",
});
while (task.status === "running") {
	task = await call("GET", `/tasks/${task.id}?wait=25`);
}

console.log(task.status, task.result?.text);
for (const file of task.result?.files ?? []) {
	const { download_url } = await call("GET", `/files/${file.id}`);
	console.log(file.name, download_url);
}

示例需要 Node.js 18 及以上版本，保存为 .mjs 文件运行。正式接入时，建议在新建任务时带上幂等键，并改用 Webhook 接收结果。