开放平台

通过 API、MCP 与技能包把onlyfantasy的创作能力接入你的应用与 Agent：一句话生成项目，或直接提交生成任务。

概览

两种接入方式，按需选择

会话式创作

创建会话 → 发送自然语言指令 → 按序号轮询消息 → 下载产物。适合“一句话成片”这类由 Agent 规划的复杂工作流。

直接任务

向 POST /v1/tasks 提交单个生成任务并轮询结果。适合已明确模型与参数的批量生成。

Base URL
https://onlyfantasy.site/api
认证头
Authorization: Bearer slk_...

快速开始

创建会话并发送指令

cURL
# 1. 创建会话
curl -X POST https://onlyfantasy.site/api/v1/sessions \
  -H "Authorization: Bearer $ONLYFANTASY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "赛博外卖骑手短片"}'

# 2. 发送创作指令
curl -X POST https://onlyfantasy.site/api/v1/sessions/ses_123/messages \
  -H "Authorization: Bearer $ONLYFANTASY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "帮我做一个 30 秒赛博朋克短片，雨夜外卖骑手捡到机械猫，16:9"}'
示例响应
json
{
  "id": "msg_88f2",
  "seq": 2,
  "role": "assistant",
  "status": "streaming",
  "session_id": "ses_123",
  "project_id": "prj_7a1c"
}

API 密钥

用于所有接口调用的凭证

接口参考

接口列表
方法路径说明
POST/v1/sessions创建一个创作会话
POST/v1/sessions/{id}/messages向会话发送自然语言指令
GET/v1/sessions/{id}/messages?after_seq=按序号增量轮询会话消息
POST/v1/uploads上传图片/视频/音频作为输入素材
GET/v1/projects/{id}/results获取会话生成项目的产物
POST/v1/tasks直接提交一个生成任务
GET/v1/tasks/{id}查询任务状态与结果
POST/v1/tasks/{id}/cancel取消一个进行中的任务
GET/v1/models获取可用模型与计费规格
轮询任务结果
cURL
# 提交任务
curl -X POST https://onlyfantasy.site/api/v1/tasks \
  -H "Authorization: Bearer $ONLYFANTASY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "video", "model": "wan-3.0", "prompt": "雨夜霓虹街道", "duration": 5, "resolution": "1080p"}'

# 轮询状态直到 succeeded
curl https://onlyfantasy.site/api/v1/tasks/task_456 \
  -H "Authorization: Bearer $ONLYFANTASY_API_KEY"
示例响应
json
{
  "id": "task_456",
  "type": "video",
  "status": "succeeded",
  "credits_used": 60,
  "output": {
    "url": "https://onlyfantasy.site/api/files/task_456.mp4",
    "duration": 5,
    "resolution": "1080p"
  }
}

Agent 技能包

为编码型 Agent 安装onlyfantasy技能

技能包让 Claude Code、Cursor 等编码型 Agent 学会调用onlyfantasy的接口。安装后配置 ONLYFANTASY_API_KEY，即可用自然语言驱动创作。

bash
# 安装onlyfantasy技能包（供编码型 Agent 使用）
npx skills add onlyfantasy-labs/onlyfantasy-skills

# 配置环境变量
export ONLYFANTASY_API_KEY=slk_你的密钥
示例指令

帮我用onlyfantasy做一支 30 秒竖屏美食短片，暖色调，配轻快音乐，完成后把成片下载到本地。

MCP 接入

通过 Model Context Protocol 暴露画布能力

json
{
  "mcpServers": {
    "onlyfantasy": {
      "command": "npx",
      "args": ["-y", "@onlyfantasy/mcp-server"],
      "env": { "ONLYFANTASY_API_KEY": "slk_你的密钥" }
    }
  }
}
提供的工具
  • create_session创建创作会话
  • send_message向会话发送自然语言指令
  • get_messages按序号增量拉取会话消息
  • upload_file上传本地素材作为输入
  • download_results下载会话生成的产物

Webhook

任务与会话事件推送

任务完成或失败时，平台会向你的回调地址发送 POST 请求（失败自动重试 3 次）。地址必须是公网可访问的 https:// 地址。

事件类型
  • task.succeeded任务成功完成，产物可下载
  • task.failed任务失败，点数已自动退还
示例请求体
json
{
  "event": "task.succeeded",
  "created_at": 1790000000,
  "data": {
    "task_id": "task_456",
    "type": "video",
    "credits_used": 60,
    "output": { "url": "https://onlyfantasy.site/api/files/task_456.mp4" }
  }
}
签名校验
每个请求都会带上 X-OnlyFantasy-Signature: sha256=… 头，其值为用签名密钥对请求体做 HMAC-SHA256 得到的十六进制摘要。收到请求后请用相同算法重新计算并比对，一致才视为可信。

用量与限额

不同方案的调用速率与并发上限

近 14 天 API 调用

共 2,806 次（演示数据）
各方案接口速率限制
方案请求速率并发任务
免费版5 次 / 分钟1 个
基础版20 次 / 分钟2 个
专业版60 次 / 分钟5 个
团队版120 次 / 分钟10 个

插件开发

用清单文件描述你的插件并提交上架

manifest.json 示例
json
{
  "name": "高清修复",
  "version": "1.2.0",
  "description": "将图片/视频提升至 2K/4K",
  "entry": "https://cdn.example.com/plugins/upscale/entry.js",
  "permissions": ["读取资产库", "写入资产库", "消耗点数"],
  "inputs": {
    "media": { "type": "image|video", "required": true },
    "scale": { "type": "enum", "values": ["2K", "4K"], "default": "2K" }
  },
  "outputs": {
    "media": { "type": "image|video" }
  }
}
审核流程
  1. 1在开放平台提交 manifest.json 与插件入口地址，填写功能说明与截图。
  2. 2平台自动校验清单格式、权限声明与入口可达性。
  3. 3人工审核功能真实性、内容合规与权限最小化，通常 1–3 个工作日。
  4. 4审核通过后上架至插件市场，你可以发布新版本并查看安装与评分数据。

有疑问？联系开发者支持 support@onlyfantasy.site