快速入门
开始使用我们的API
本指南将帮助您快速上手我们的API服务，了解基本概念和使用流程。按照以下步骤开始使用我们的服务：
- 创建账户: 在我们的平台注册并创建一个开发者账户。
- 获取API密钥: 登录后，在控制台生成API密钥。
- 设置开发环境: 根据您的技术栈，配置开发环境和所需的依赖。
- 发送您的第一个请求: 使用API密钥发送请求并验证响应。
设置环境
配置您的开发环境
根据您的编程语言和框架，按照以下步骤设置您的开发环境：
JavaScript/TypeScript
npm install axios或者如果您使用的是Fetch API，则不需要额外安装依赖。
Python
pip install requestsPHP
composer require guzzlehttp/guzzle身份验证
API身份验证
所有API请求都需要进行身份验证。我们使用API密钥进行身份验证，您需要在请求头中包含您的API密钥。
身份验证示例
JavaScript
// 身份验证示例代码
import axios from 'axios';
// 设置API密钥
const API_KEY = 'YOUR_API_KEY';
// 创建一个HTTP客户端，自动包含API密钥
const apiClient = axios.create({
baseURL: 'https://api.example.com/v1',
headers: {
'Content-Type': 'application/json',
'X-API-Key': API_KEY
}
});
// 现在可以使用apiClient发起请求
async function makeRequest() {
try {
const response = await apiClient.get('/user/profile');
return response.data;
} catch (error) {
console.error('API请求失败:', error);
throw error;
}
}安全提示
请确保您的API密钥安全，不要将其包含在客户端代码中。最好通过服务器端代码进行API调用，或使用安全的环境变量存储密钥。
人脸识别指南
人脸检测
人脸检测API可以识别图像中的人脸，并返回人脸位置和关键点信息。以下是使用人脸检测API的基本步骤：
- 准备一张包含人脸的图像，可以是URL或者Base64编码的图像数据。
- 发送POST请求到
/v1/face/detect端点。 - 在请求体中包含图像信息和可选的参数。
- 处理API返回的结果，包括人脸位置、关键点和属性信息。
请求示例
const response = await apiClient.post('/face/detect', {
image_url: 'https://example.com/images/photo.jpg',
return_attributes: ['age', 'gender', 'emotion']
});响应示例
{
"request_id": "1a2b3c4d5e6f",
"time_used": 127,
"faces": [
{
"face_token": "f1a2b3c4d5e6",
"face_rectangle": {
"top": 80,
"left": 115,
"width": 76,
"height": 95
},
"landmarks": {
"left_eye": {"x": 136, "y": 108},
"right_eye": {"x": 170, "y": 104},
"nose_tip": {"x": 152, "y": 135},
// 更多关键点...
},
"attributes": {
"age": {"value": 28},
"gender": {"value": "Male"},
"emotion": {"value": "Neutral"}
}
}
]
}人脸比对
人脸比对API可以比较两张照片中的人脸，计算它们的相似度。通常用于身份验证和人脸搜索场景。
使用步骤
- 准备两张包含人脸的图像。
- 发送POST请求到
/v1/face/compare端点。 - 在请求体中包含两张图像的信息。
- 处理API返回的相似度分数。
提示
相似度分数范围从0到100，分数越高表示两张脸越相似。通常认为分数大于70表示很可能是同一个人，但具体阈值可以根据您的应用场景调整。
错误处理
API错误处理
有效的错误处理是构建稳健应用程序的关键。我们的API使用标准的HTTP状态码和详细的错误消息，帮助您快速识别和解决问题。
常见错误状态码
| 状态码 | 说明 | 处理方法 |
|---|---|---|
| 400 | 参数错误或格式不正确 | 检查请求参数和格式 |
| 401 | 身份验证失败 | 检查API密钥是否有效 |
| 429 | 请求频率超限 | 降低请求频率或升级套餐 |
| 500 | 服务器内部错误 | 联系技术支持 |
错误处理示例
JavaScript
// 错误处理示例
async function detectFaces(imageUrl) {
try {
const response = await apiClient.post('/face/detect', {
image_url: imageUrl
});
return response.data;
} catch (error) {
if (error.response) {
// 服务器返回了错误状态码
if (error.response.status === 400) {
console.error('参数错误:', error.response.data.message);
} else if (error.response.status === 401) {
console.error('身份验证失败: API密钥无效或已过期');
} else if (error.response.status === 429) {
console.error('请求过于频繁: 请降低请求频率');
} else {
console.error('服务器错误:', error.response.data.message);
}
} else if (error.request) {
// 请求已发送但没有收到响应
console.error('无法连接到API服务器，请检查网络连接');
} else {
// 请求设置时出错
console.error('请求配置错误:', error.message);
}
throw error;
}
}