API 接口文档 — 情感识别 API 开发指南

🔑 认证方式

                # 所有 API 调用需在请求头中携带 API Key
                curl -X POST https://followsrc.wang/api/v2/analyze/image \

                  -H "X-API-Key: fme_your_api_key_here" \

                  -F "image=@photo.jpg"

📮 响应格式

                {

                  "code": 200,

                  "msg": "成功",

                  "data": {

                    "faces": [...],

                    "total_faces": 1

                  }

                }

📖 开发者指南

从获取 API Key 到集成上线，一步步带你快速接入情感识别能力

1. 快速接入

1.1 获取 API Key

访问定价页面，选择适合的套餐：

免费试用 — 直接填写信息即可生成 API Key，每日 100 次调用
入门版/专业版 — 提交订单 → 转账 → 后台确认后自动发放 API Key
企业版 — 联系客服获取专属方案

建议先从免费版开始测试，确认接口满足需求后再升级付费套餐

1.2 鉴权方式

有两种传参方式（推荐使用请求头方式）：

                # 方式一（推荐）：请求头认证
                -H "X-API-Key: fme_your_key_here"

                # 方式二：URL 参数认证
                ?api_key=fme_your_key_here
            

请妥善保管你的 API Key，不要在前端代码中明文暴露。如果 Key 泄漏，请联系我们吊销并重新生成。

1.3 免费额度

免费套餐每日 100 次调用额度，UTC 零点重置。超出返回 HTTP 429，请在定价页面升级套餐。

2. 代码示例

以下示例演示各语言调用方式。所有示例使用同一个场景：上传图片进行人脸情绪分析。

# Python 3.7+ — 图片情绪分析
# 安装依赖：pip install requests

import requests

API_KEY = "fme_your_key_here"
URL = "https://followsrc.wang/api/v2/analyze/image"

# 方式一：上传本地图片文件
with open("photo.jpg", "rb") as f:
    resp = requests.post(
        URL,
        headers={"X-API-Key": API_KEY},
        files={"image": f}
    )

# 方式二：从 URL 下载图片分析（可选，需服务端支持）
# resp = requests.post(URL, headers={"X-API-Key": API_KEY},
#     json={"image_url": "https://example.com/face.jpg"})

data = resp.json()
print(f"状态码: {data['code']}")
print(f"检测到 {data['data']['total_faces']} 张人脸")

for face in data['data']['faces']:
    emotion = face['emotion']
    print(f"  情绪: {emotion['label']} (置信度: {emotion['confidence']:.2%})")
    print(f"  位置: x={face['bbox']['x']}, y={face['bbox']['y']}, "
          f"w={face['bbox']['w']}, h={face['bbox']['h']}")

# 输出示例：
# 状态码: 200
# 检测到 1 张人脸
#   情绪: happy (置信度: 93.25%)
#   位置: x=120, y=85, w=180, h=200
                

# cURL — 图片情绪分析

curl -X POST https://followsrc.wang/api/v2/analyze/image \
  -H "X-API-Key: fme_your_key_here" \
  -F "image=@photo.jpg" \
  | python3 -m json.tool

# 预期响应：
# {
#   "code": 200,
#   "msg": "成功",
#   "data": {
#     "total_faces": 1,
#     "faces": [{
#       "bbox": {"x": 120, "y": 85, "w": 180, "h": 200},
#       "emotion": {
#         "label": "happy",
#         "confidence": 0.9325,
#         "scores": {"happy": 0.93, "neutral": 0.04, ...}
#       }
#     }],
#     "visualization_url": "/api/v2/analyze/visualization/abc123.jpg"
#   }
# }
                

// JavaScript (Node.js / 浏览器) — 图片情绪分析
// Node.js 需要：npm install node-fetch (或使用内置 fetch 在 v18+)

const API_KEY = "fme_your_key_here";

// Node.js: 表单数据需要 FormData 模块
// const FormData = require('form-data');
// const fs = require('fs');

async function analyzeImage(imagePath) {
  const formData = new FormData();
  formData.append("image", fs.createReadStream(imagePath));

  const resp = await fetch("https://followsrc.wang/api/v2/analyze/image", {
    method: "POST",
    headers: { "X-API-Key": API_KEY },
    body: formData
  });

  const data = await resp.json();
  console.log(`检测到 ${data.data.total_faces} 张人脸`);

  data.data.faces.forEach((face, i) => {
    console.log(`人脸 #${i + 1}: ${face.emotion.label} ` +
                `(${(face.emotion.confidence * 100).toFixed(1)}%)`);
  });
}

// 浏览器端：使用 File/Blob 对象
// async function analyzeFromBrowser(fileInput) {
//   const formData = new FormData();
//   formData.append("image", fileInput.files[0]);
//   const resp = await fetch("https://followsrc.wang/api/v2/analyze/image", {
//     method: "POST",
//     headers: { "X-API-Key": API_KEY },
//     body: formData
//   });
//   return resp.json();
// }
                

// Java — 图片情绪分析（使用 OkHttp）
// Maven: com.squareup.okhttp3:okhttp:4.12.0

import okhttp3.*;
import org.json.JSONObject;

public class EmotionAnalyzer {
    private static final String API_KEY = "fme_your_key_here";
    private static final String URL = "https://followsrc.wang/api/v2/analyze/image";

    public static void main(String[] args) throws Exception {
        OkHttpClient client = new OkHttpClient.Builder()
            .connectTimeout(30, TimeUnit.SECONDS)
            .readTimeout(60, TimeUnit.SECONDS)
            .build();

        // 构建 multipart 请求体
        RequestBody fileBody = RequestBody.create(
            MediaType.parse("image/jpeg"),
            new java.io.File("photo.jpg")
        );
        MultipartBody body = new MultipartBody.Builder()
            .setType(MultipartBody.FORM)
            .addFormDataPart("image", "photo.jpg", fileBody)
            .build();

        Request request = new Request.Builder()
            .url(URL)
            .header("X-API-Key", API_KEY)
            .post(body)
            .build();

        try (Response resp = client.newCall(request).execute()) {
            JSONObject json = new JSONObject(resp.body().string());
            System.out.println("状态码: " + json.getInt("code"));
            JSONObject data = json.getJSONObject("data");
            System.out.println("检测到 " + data.getInt("total_faces") + " 张人脸");
        }
    }
}
                

3. 更多 API 调用示例

3.1 视频分析

# Python — 视频情绪分析（上传视频文件，返回逐帧分析结果）
import requests

resp = requests.post(
    "https://followsrc.wang/api/v2/analyze/video",
    headers={"X-API-Key": "fme_your_key_here"},
    files={"video": open("interview.mp4", "rb")}
)
data = resp.json()
print(f"总帧数: {data['data']['total_frames']}")
print(f"主要情绪: {data['data']['summary']['dominant_emotion']}")
print(f"情绪变化: {data['data']['summary']['emotion_transitions']}")
            

3.2 实时帧分析（WebSocket）

发送单帧 JPEG 字节数据，适合摄像头实时流场景：

# cURL — 单帧分析（发送 raw JPEG 字节）
curl -X POST https://followsrc.wang/api/v2/analyze/frame \
  -H "X-API-Key: fme_your_key_here" \
  -H "Content-Type: image/jpeg" \
  --data-binary @frame.jpg

# Python — 摄像头实时帧分析
import cv2
import requests

cap = cv2.VideoCapture(0)
while True:
    ret, frame = cap.read()
    _, jpeg = cv2.imencode('.jpg', frame, [cv2.IMWRITE_JPEG_QUALITY, 85])
    resp = requests.post(
        "https://followsrc.wang/api/v2/analyze/frame",
        headers={
            "X-API-Key": "fme_your_key_here",
            "Content-Type": "image/jpeg"
        },
        data=jpeg.tobytes()
    )
    result = resp.json()
    print(f"当前情绪: {result['data']['faces'][0]['emotion']['label']}")
                    

3.3 人脸注册与识别

# Python — 注册人脸
resp = requests.post(
    "https://followsrc.wang/api/v2/faces/register",
    headers={"X-API-Key": "fme_your_key_here"},
    files={"image": open("zhangsan.jpg", "rb")},
    data={"name": "张三"}  # 人员姓名
)
print(resp.json())  # {"person_id": "uuid", "name": "张三"}

# Python — 识别未知人脸
resp = requests.post(
    "https://followsrc.wang/api/v2/faces/recognize",
    headers={"X-API-Key": "fme_your_key_here"},
    files={"image": open("unknown.jpg", "rb")}
)
data = resp.json()
print(f"识别结果: {data['data']['name']} (相似度: {data['data']['similarity']:.2%})")
            

3.4 用量查询

# Python — 查询当前 API Key 的调用统计
resp = requests.get(
    "https://followsrc.wang/api/v2/usage",
    headers={"X-API-Key": "fme_your_key_here"}
)
data = resp.json()
print(f"今日总量: {data['data']['key_info']['daily_count']}")
print(f"每日限额: {data['data']['key_info']['daily_limit']}")
print(f"各端点明细:")
for ep in data['data']['by_endpoint']:
    print(f"  {ep['endpoint']}: {ep['count']} 次")
            

4. 错误码

HTTP 状态码	code	含义	处理方式
200	200	请求成功	正常解析 data
400	400	请求参数错误（缺少 image/格式错误）	检查请求体格式
401	401	API Key 缺失或无效	检查 X-API-Key 头
403	403	API Key 已被吊销	联系管理员
429	429	超出每日配额	升级套餐或等待次日重置
500	500	服务端内部错误	重试或联系支持
502	502	模型推理异常	联系支持

# 错误响应格式
{
  "code": 401,
  "msg": "无效的 API Key",
  "data": null
}
            

5. 最佳实践

批量分析 — 如需同时处理多张图片，建议使用并发请求（Python asyncio / 线程池），单次上传一张图片
图片优化 — 上传前将图片压缩到 1920px 以内，JPEG 质量 80-85%，可显著降低传输延迟
视频分析 — 视频文件建议控制在 100MB 以内，过长视频建议分段上传
重试策略 — 遇到 5xx 错误时，使用指数退避重试（1s → 2s → 4s → 放弃）
缓存可视化结果 — 分析返回的 visualization_url 短期内有效，建议及时下载保存
实时帧分析 — 建议帧率控制在 5-10 FPS，过高的帧率不会提升识别精度，反而消耗配额

建议在开发环境使用免费套餐测试，测试完成后升级到付费套餐再上线生产环境

6. 配额与限制

限制项目	免费版	入门版	专业版	企业版
每日调用量	100 次	1,000 次	10,000 次	不限
并发请求数	5	20	50	定制
图片大小	≤ 10MB
视频大小	≤ 50MB		≤ 200MB
视频时长	≤ 5 分钟		≤ 30 分钟
有效期	30 天	按订阅周期

7. OpenAPI 规范

我们提供完整的 OpenAPI 3.0.3 规范文档，可导入到 Postman、Insomnia、Swagger Editor 等工具：

/api/v2/openapi.json — 完整规范文件
本页上方已集成 Swagger UI，可直接浏览和测试接口

在 Postman 中导入：File → Import → Link → 输入 https://followsrc.wang/api/v2/openapi.json