AIDataset API 文档总览

AIDataset 开放API是平台面向开发者提供的标准化数据集调用接口集合，完整定义全平台统一Token计量规则、接口调用方法、鉴权流程与业务能力规范。本文档为API全局总览手册，统一约定所有接口的接入标准、Token扣费逻辑、流量限流、报错处理、调用示例，是开发对接、成本管控、权限配置的核心基础规范。

一、文档说明

本文档面向所有对接AIDataset数据服务的内部研发、第三方企业与个人开发者，完整覆盖接口调用全生命周期相关规范：包含RESTful接口定义、AK/SK鉴权流程、Token消耗计费标准、请求/响应结构体、通用错误码、分级限流策略、多语言调用示例等内容。平台全部开放接口遵循统一设计范式，请求格式、Token统计口径、异常返回逻辑完全标准化，降低多接口对接与维护成本。

• 统一Token计量：全接口统一Token消耗统计规则，区分读取、写入、批量处理、大文件分片等不同场景扣费标准，计费口径全局唯一
• 标准化调用范式：全部接口遵循RESTful设计规范，请求方式、传参格式、返回JSON结构、Header鉴权规则统一无差异
• 全业务能力覆盖：涵盖数据集检索、样本读写、批量导入导出、用量查询、账户Token余额、权限管理等全链路业务接口
• 多语言接入示例：配套Python/Java/Go/HTTP原生请求代码模板，快速完成本地调试与线上集成
• 完整可观测体系：记录每一次调用Token消耗、请求耗时、操作账号、数据范围，支持账单对账、异常调用审计与用量预警

二、接入方案说明

平台区分两套独立API接入通道，两套体系Token额度、限流阈值、扣费单价、权限范围完全隔离，开发者可根据自身业务主体选择对应通道接入，互不占用对方账户Token余额。

• 内部业务通道：面向平台自有业务系统、内部自动化数据处理服务，Token单价优惠、限流阈值更高、接口全量开放，仅用于平台自研业务场景
• 第三方开发者通道：面向外部企业、商用集成、个人研发项目，Token按量预充值计费、精细化接口权限管控、分级流量限制，适配对外商用数据调用场景

三、API核心管控能力

整套开放API以Token计量为核心管控底座，配套鉴权、限流、审计、账单一体化能力，实现数据调用可计量、可管控、可追溯，核心能力如下：

• AK/SK全局鉴权：所有接口强制携带请求头鉴权密钥，支持账号、接口、数据集三级权限隔离，限制不同密钥可访问的数据范围与操作类型
• 精细化Token计费：以文本/音频/图像样本Token消耗量作为唯一计费单位，实时扣减账户余额，支持预充值、月度账单、单条调用扣费明细查询
• 分级流量熔断管控：基于账号剩余Token、每秒调用频次、单日总消耗三重限流，额度不足自动拦截请求并返回标准报错，防止超额扣费
• 全链路调用审计日志：持久化存储每一次接口调用的入参、返回结果、消耗Token数、调用时间、操作密钥，满足合规审计与问题排查需求
• 实时用量监控预警：支持自定义Token消耗阈值提醒，临近额度上限主动推送预警，提前充值避免业务接口中断

四、通用接口调用规范

平台所有API统一执行下述基础调用标准，无单独特殊说明时全部接口强制遵循，违规请求将直接拦截并消耗无效Token。

• 传输协议：仅支持HTTPS加密请求，明文HTTP请求直接拒绝，保障AK/SK与业务数据传输安全
• 请求方法约定：数据查询、余额统计使用GET；新增、修改、删除、批量上传/导出使用POST
• 数据交换格式：请求参数与响应结果统一标准JSON，不兼容表单、XML等其他格式
• 字符编码：全局统一UTF-8编码，中文、特殊符号未转码会造成参数解析失败并产生无效Token损耗
• 接口超时阈值：普通查询接口默认30秒超时，批量大数据、多模态样本导出接口默认60秒超时，超时请求仍会按已处理样本扣减Token