API参考

详细的API文档,包括端点、参数、响应格式和示例代码

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请求实施了速率限制。限制根据您的套餐类型而有所不同。

限制规则

套餐每分钟请求数每天请求数
免费101,000
基础6010,000
专业300100,000
企业定制定制

超出限制

当您超出速率限制时,API将返回429 Too Many Requests状态码。响应头中会包含以下信息:

  • X-RateLimit-Limit: 当前时间窗口内的请求限制
  • X-RateLimit-Remaining: 当前时间窗口内剩余的请求数
  • X-RateLimit-Reset: 当前时间窗口重置的时间戳(Unix时间)

提示

建议在应用中实现指数退避算法,以便在遇到速率限制时自动调整请求频率。

人脸检测API

POST

人脸检测

检测图像中的人脸,并返回人脸位置和属性信息

/face/detect

参数

名称类型必填描述
image_urlstring图像的URL地址
return_attributesarray需要返回的人脸属性,如age、gender、emotion等
return_landmarkboolean是否返回人脸关键点信息

响应

状态码描述
200成功返回检测结果
400请求参数错误
401未授权,API密钥无效

人脸比对API

POST

人脸比对

比较两张图像中的人脸,计算相似度

/face/compare

参数

名称类型必填描述
image_url1string第一张图像的URL地址
image_url2string第二张图像的URL地址
return_face_databoolean是否返回人脸数据

响应

状态码描述
200成功返回比对结果
400请求参数错误
401未授权,API密钥无效

3D重建API

POST

3D模型重建

从多张图像重建3D模型

/3d/reconstruct

参数

名称类型必填描述
image_urlsarray图像URL数组,建议提供至少3张不同角度的图像
qualitystring重建质量,可选值:low、medium、high,默认为medium
formatstring输出格式,可选值:obj、stl、glb,默认为obj

响应

状态码描述
200成功返回重建结果
400请求参数错误
401未授权,API密钥无效
429请求频率超限

准备好开始集成了吗?

查看我们的代码示例和开发指南,快速将API集成到您的应用中。