API基础
基本信息
我们的API使用RESTful架构,所有数据以JSON格式传输。API的基本URL为:
https://api.example.com/v1
所有API请求都需要通过HTTPS进行,不支持HTTP请求。API版本在URL路径中指定,当前最新版本为v1。
请求格式
对于POST请求,请求体应为JSON格式,并设置Content-Type头为application/json。
响应格式
所有API响应均为JSON格式,包含请求的处理结果。成功的响应通常包含一个data字段,而错误响应则包含error字段。
认证
API密钥认证
所有API请求都需要在请求头中包含有效的API密钥进行认证。在X-API-Key头中传递您的API密钥:
认证方式
在每个请求的头部中添加X-API-Key字段,值为您的API密钥。
JavaScript
// 使用API密钥进行认证
const headers = {
'Content-Type': 'application/json',
'X-API-Key': 'YOUR_API_KEY'
};
// 发送请求
fetch('https://api.example.com/v1/face/detect', {
method: 'POST',
headers: headers,
body: JSON.stringify({
image_url: 'https://example.com/images/photo.jpg'
})
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
安全提示
请妥善保管您的API密钥,不要在客户端代码中暴露它。建议通过后端服务器中转API请求,以保护您的API密钥安全。
错误处理
错误响应格式
当API请求失败时,服务器会返回相应的HTTP状态码和JSON格式的错误信息。
错误响应示例
{
"error": {
"code": "invalid_parameter",
"message": "参数'image_url'无效或缺失",
"details": {
"field": "image_url",
"reason": "required"
}
}
}
常见HTTP状态码
状态码 | 描述 |
---|---|
200 OK | 请求成功 |
400 Bad Request | 请求参数错误 |
401 Unauthorized | 认证失败 |
404 Not Found | 请求的资源不存在 |
429 Too Many Requests | 请求频率超过限制 |
500 Internal Server Error | 服务器内部错误 |
错误处理最佳实践
JavaScript
// 错误处理示例
async function callApi(endpoint, data) {
try {
const response = await fetch(`https://api.example.com/v1/${endpoint}`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-API-Key': 'YOUR_API_KEY'
},
body: JSON.stringify(data)
});
// 检查HTTP状态码
if (!response.ok) {
const errorData = await response.json();
// 处理不同类型的错误
switch (response.status) {
case 400:
throw new Error(`参数错误: ${errorData.message}`);
case 401:
throw new Error('认证失败: API密钥无效或已过期');
case 404:
throw new Error(`资源不存在: ${errorData.message}`);
case 429:
throw new Error('请求频率超限: 请降低请求速率或升级套餐');
default:
throw new Error(`服务器错误 (${response.status}): ${errorData.message}`);
}
}
// 成功响应
return await response.json();
} catch (error) {
console.error('API调用失败:', error);
throw error;
}
}
速率限制
API请求限制
为了确保服务质量和公平使用,我们对API请求实施了速率限制。限制根据您的套餐类型而有所不同。
限制规则
套餐 | 每分钟请求数 | 每天请求数 |
---|---|---|
免费 | 10 | 1,000 |
基础 | 60 | 10,000 |
专业 | 300 | 100,000 |
企业 | 定制 | 定制 |
超出限制
当您超出速率限制时,API将返回429 Too Many Requests状态码。响应头中会包含以下信息:
- X-RateLimit-Limit: 当前时间窗口内的请求限制
- X-RateLimit-Remaining: 当前时间窗口内剩余的请求数
- X-RateLimit-Reset: 当前时间窗口重置的时间戳(Unix时间)
提示
建议在应用中实现指数退避算法,以便在遇到速率限制时自动调整请求频率。
人脸检测API
POST
人脸检测
检测图像中的人脸,并返回人脸位置和属性信息
/face/detect
参数
名称 | 类型 | 必填 | 描述 |
---|---|---|---|
image_url | string | 是 | 图像的URL地址 |
return_attributes | array | 否 | 需要返回的人脸属性,如age、gender、emotion等 |
return_landmark | boolean | 否 | 是否返回人脸关键点信息 |
响应
状态码 | 描述 |
---|---|
200 | 成功返回检测结果 |
400 | 请求参数错误 |
401 | 未授权,API密钥无效 |
人脸比对API
POST
人脸比对
比较两张图像中的人脸,计算相似度
/face/compare
参数
名称 | 类型 | 必填 | 描述 |
---|---|---|---|
image_url1 | string | 是 | 第一张图像的URL地址 |
image_url2 | string | 是 | 第二张图像的URL地址 |
return_face_data | boolean | 否 | 是否返回人脸数据 |
响应
状态码 | 描述 |
---|---|
200 | 成功返回比对结果 |
400 | 请求参数错误 |
401 | 未授权,API密钥无效 |
3D重建API
POST
3D模型重建
从多张图像重建3D模型
/3d/reconstruct
参数
名称 | 类型 | 必填 | 描述 |
---|---|---|---|
image_urls | array | 是 | 图像URL数组,建议提供至少3张不同角度的图像 |
quality | string | 否 | 重建质量,可选值:low、medium、high,默认为medium |
format | string | 否 | 输出格式,可选值:obj、stl、glb,默认为obj |
响应
状态码 | 描述 |
---|---|
200 | 成功返回重建结果 |
400 | 请求参数错误 |
401 | 未授权,API密钥无效 |
429 | 请求频率超限 |