鉴权

V2Fun API 使用 Bearer Token 认证方式。每条请求都需要在 HTTP 头中携带一个有效的 API Key。

获取 API Key

API Key 通过 V2Fun 开发者控制台管理。请联系我们或前往账号后台创建和管理您的密钥。

妥善保管密钥

API Key 相当于密码。请勿将其硬编码在客户端代码、公开仓库或日志中。

发起认证请求

在每条请求的 Authorization 头中携带您的 API Key：

Authorization: Bearer YOUR_API_KEY

代码示例

cURL

curl -X POST "https://api.v2fun.art/api/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "夕阳下的山脉"}'

JavaScript

const response = await fetch("https://api.v2fun.art/api/v1/images/generations", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ prompt: "夕阳下的山脉" })
});

Python

import requests

response = requests.post(
    "https://api.v2fun.art/api/v1/images/generations",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={"prompt": "夕阳下的山脉"}
)

API Key 权限范围（Scope）

每个 API Key 被授予一个或多个 Scope，决定其可以访问的接口。调用未授权的接口将返回 403 Forbidden。

Scope	说明
image:prompt	图像描述生成与提示词增强
image:imgen	文本生成图像
image:imgedit	图像编辑
model:mesh	文本 / 图像生成 3D 模型
model:texture	3D 模型纹理生成
model:remesh	3D 模型网格优化
model:convert	3D 模型格式转换
model:render	3D 模型渲染
motion:animate	动画迁移（Retargeting）
motion:query	动作检索
video:capture	视频动作捕捉（姿态检测、动作检测）
asset:read	读取生成的资产文件

INFO

如需访问当前未分配给您密钥的 Scope，请联系我们申请。

安全建议

• 使用环境变量 — 将密钥存储在 .env 文件或密钥管理服务中，不要硬编码。
• 最小权限原则 — 仅申请您的应用实际需要的 Scope。
• 定期轮换 — 定期重新生成密钥；若怀疑泄露，立即更换。
• 禁止记录密钥 — 确保日志系统在落盘前过滤掉 Authorization 请求头。

认证错误说明

HTTP 状态码	错误码	含义
401 Unauthorized	UNAUTHORIZED	Authorization 头缺失、格式错误或密钥已失效
403 Forbidden	FORBIDDEN	密钥有效，但无权访问该接口所需的 Scope

收到 401 时，请确认：

1. Authorization 头存在且格式为 Bearer YOUR_API_KEY。
2. 密钥未被吊销或过期。
3. 请求发向了正确的 API Host。