Skip to Content
DocsAPI 规格

BitFlow 专业 AI 数据平台 RESTful API 规范

1. 概述

本文档定义了 BitFlow 专业 AI 数据平台的 RESTful API 规范，支持多平台 Git 集成、数据资产管理、AI 训练引擎等核心功能。

1.1 基本信息

  • API 版本: v1
  • 基础 URL: https://api.bitroc.ai/v1
  • 认证方式: JWT Bearer Token
  • 响应格式: JSON
  • 字符编码: UTF-8

1.2 通用响应格式

成功响应 (HTTP 200/201/204):

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-ID: req_1234567890abcdef
Date: Mon, 01 Jan 2024 00:00:00 GMT
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1704067200
{
  // 直接返回业务数据，无需data包装层
}

错误响应 (HTTP 4xx/5xx):

HTTP/1.1 400 Bad Request
Content-Type: application/json
X-Request-ID: req_1234567890abcdef
Date: Mon, 01 Jan 2024 00:00:00 GMT
{
  "message": "Invalid request parameters",
  "errors": [
    {
      "field": "data_mounts",
      "code": "missing_field",
      "message": "Required field is missing"
    }
  ]
}

1.3 标准响应头

响应头说明示例
X-Request-ID唯一请求标识符，用于追踪和调试req_1234567890abcdef
Date响应时间戳 (HTTP 标准头)Mon, 01 Jan 2024 00:00:00 GMT
X-RateLimit-Limit速率限制总数1000
X-RateLimit-Remaining剩余请求次数999
X-RateLimit-Reset限制重置时间 (Unix 时间戳)1704067200
X-API-VersionAPI 版本v1
X-Content-Type-Options安全头，防止 MIME 类型嗅探nosniff

1.4 HTTP 状态码规范

状态码说明使用场景
200OK请求成功，返回数据
201Created资源创建成功
204No Content请求成功，无返回数据
400Bad Request请求参数错误
401Unauthorized未认证或认证失败
403Forbidden无权限访问
404Not Found资源不存在
409Conflict资源冲突
429Too Many Requests请求频率超限
500Internal Server Error服务器内部错误
503Service Unavailable服务暂时不可用

1.5 状态码使用原则

遵循 RESTful 标准，充分利用 HTTP 状态码语义:

  • 2xx (成功): 请求被成功处理

    • 200 OK: 成功获取数据
    • 201 Created: 成功创建资源（如创建训练任务、订阅等）
    • 204 No Content: 成功处理但无返回内容（如删除操作）

  • 4xx (客户端错误): 客户端请求有误

    • 400 Bad Request: 请求参数格式错误或缺失必需参数
    • 401 Unauthorized: 未提供认证信息或认证失败
    • 403 Forbidden: 已认证但无权限访问资源（如数据订阅不足）
    • 404 Not Found: 请求的资源不存在
    • 409 Conflict: 请求与当前资源状态冲突
    • 429 Too Many Requests: 请求频率超出限制

  • 5xx (服务器错误): 服务器内部错误

    • 500 Internal Server Error: 服务器内部错误
    • 503 Service Unavailable: 服务暂时不可用

业务错误直接在响应体中提供详细信息，不使用额外包装层。

错误响应设计原则：

  • 遵循 GitHub API 等主流 API 的实践
  • 使用message字段提供主要错误信息
  • 对于验证错误，使用errors数组提供详细的字段级错误信息
  • 其他相关信息直接在根级别提供
  • 不使用error包装层或type字段

重要说明：

  • X-Request-ID 和时间戳信息通过 HTTP 响应头传递，不在响应体中重复
  • 遵循 HTTP 标准，充分利用状态码语义
  • 成功响应直接返回业务数据，无需data包装层
  • 错误响应直接返回错误信息，无需额外包装层
  • 响应体保持简洁，结构清晰

2. 认证和用户管理 API

2.1 用户认证

多平台 OAuth 登录

POST /auth/oauth/{platform}/login

路径参数:

  • platform: 平台类型 (github, gitlab, gitee)

请求体:

{
  "code": "oauth_authorization_code",
  "state": "random_state_string",
  "redirect_uri": "https://platform.bitflow.ai/callback"
}

响应 (HTTP 200):

{
  "access_token": "jwt_token_string",
  "refresh_token": "refresh_token_string",
  "expires_in": 86400,
  "user": {
    "id": "user_123",
    "username": "john_doe",
    "email": "john@example.com",
    "avatar_url": "https://avatar.url",
    "platform_accounts": [
      {
        "platform": "github",
        "platform_user_id": "12345",
        "username": "john_doe",
        "connected_at": "2024-01-01T00:00:00Z"
      }
    ]
  }
}

新用户注册说明: 当用户首次通过 OAuth 登录时，系统会自动：

  1. 创建用户账户
  2. 创建用户的默认个人工作空间
  3. 设置用户为该工作空间的所有者

默认工作空间特征：

  • 名称: {username}'s Personal Workspace
  • Slug: {username} (如果重复则添加数字后缀)
  • 可见性: private
  • 计划: free

刷新访问令牌

POST /auth/refresh

请求体:

{
  "refresh_token": "refresh_token_string"
}

用户信息

GET /auth/me

响应 (HTTP 200):

{
  "id": "user_123",
  "username": "john_doe",
  "email": "john@example.com",
  "subscription": {
    "plan": "professional",
    "data_quotas": {
      "wsi_monthly_limit": 50000,
      "wsi_used": 12000,
      "mcap_monthly_limit": 500,
      "mcap_used": 120
    },
    "expires_at": "2024-12-31T23:59:59Z"
  }
}

3. 数据资产管理 API

3.1 数据集管理

获取数据集列表

GET /datasets

查询参数:

  • category: 数据类型 (wsi, mcap, general)
  • access_level: 访问级别 (public, premium, enterprise)
  • visibility: 可见性 (private, public, workspace) - 管理员功能
  • workspace_id: 工作空间 ID
  • search: 搜索关键词 (匹配名称、描述、标签)
  • page: 页码 (默认 1)
  • limit: 每页数量 (默认 20, 最大 100)

请求示例:

GET /datasets?category=wsi&access_level=premium&search=pathology&page=1&limit=10

响应 (HTTP 200):

{
  "datasets": [
    {
      "id": "dataset_abc123",
      "name": "WSI病理基础数据集",
      "description": "包含1万张标注的病理切片数据",
      "category": "wsi",
      "access_level": "premium",
      "visibility": "public",
      "size": 53687091200,
      "samples_count": 10000,
      "download_count": 1250,
      "quality_score": 9.5,
      "preview_available": true,
      "license_type": "CC-BY-4.0",
      "tags": ["pathology", "cancer", "diagnosis", "H&E"],
      "full_name": "bitflow/wsi-pathology-basic",
      "owner": {
        "id": "user_123",
        "username": "bitflow",
        "avatar_url": "https://avatar.example.com/bitflow.jpg"
      },
      "workspace": {
        "id": "workspace_456",
        "name": "BitFlow 官方数据",
        "slug": "bitflow"
      },
      "pricing": {
        "basic": 9999,
        "professional": 39999,
        "enterprise": 199999
      },
      "can_access": true,
      "can_manage": false,
      "subscription_required": true,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-15T00:00:00Z"
    },
    {
      "id": "dataset_def456",
      "name": "MCAP自动驾驶数据集",
      "description": "包含激光雷达、相机、GPS等传感器数据的MCAP格式数据集",
      "category": "mcap",
      "access_level": "enterprise",
      "visibility": "workspace",
      "size": 107374182400,
      "samples_count": 5000,
      "download_count": 89,
      "quality_score": 9.8,
      "preview_available": false,
      "license_type": "Proprietary",
      "tags": ["autonomous-driving", "lidar", "camera", "mcap"],
      "full_name": "autonomous-lab/mcap-driving-v2",
      "owner": {
        "id": "user_789",
        "username": "autonomous_lab",
        "avatar_url": "https://avatar.example.com/autonomous_lab.jpg"
      },
      "workspace": {
        "id": "workspace_789",
        "name": "自动驾驶实验室",
        "slug": "autonomous-lab"
      },
      "pricing": {
        "enterprise": 599999
      },
      "can_access": false,
      "can_manage": false,
      "subscription_required": true,
      "created_at": "2024-01-10T08:30:00Z",
      "updated_at": "2024-01-20T14:22:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 156,
    "pages": 16
  }
}

权限说明:

  • 匿名用户: 只能看到 visibility=public 的数据集
  • 登录用户: 可以看到公开数据集 + 自己的数据集 + 所在工作空间的数据集
  • can_access: 表示用户是否有权限使用此数据集（考虑订阅状态）
  • can_manage: 表示用户是否可以编辑/删除此数据集

过滤示例:

# 查看WSI类型的数据集
GET /datasets?category=wsi
 
# 查看免费公开的数据集
GET /datasets?access_level=public
 
# 在特定工作空间中搜索
GET /datasets?workspace_id=workspace_456&search=cancer
 
# 查看用户有权限访问的高级数据集
GET /datasets?access_level=premium,enterprise

获取数据集详情

GET /datasets/{dataset_id}

响应 (HTTP 200):

{
  "id": "bitflow/wsi-pathology-basic",
  "name": "WSI病理基础数据集",
  "description": "详细描述...",
  "category": "wsi",
  "access_level": "premium",
  "metadata": {
    "file_formats": ["TIFF", "SVS", "NDPI"],
    "annotation_types": ["region", "cell_detection"],
    "magnifications": ["10x", "20x", "40x"],
    "diseases": ["lung_cancer", "breast_cancer", "colon_cancer"]
  },
  "data_schema": {
    "structure": "pyramid_tiles",
    "annotation_format": "geojson",
    "quality_control": "three_tier_review"
  },
  "usage_stats": {
    "total_downloads": 1250,
    "active_users": 89,
    "avg_rating": 4.8
  },
  "samples": [
    {
      "id": "sample_001",
      "preview_url": "https://preview.bitflow.ai/wsi/sample_001",
      "metadata": {
        "disease": "lung_cancer",
        "magnification": "40x",
        "size": "2048x2048"
      }
    }
  ]
}

数据集预览

GET /datasets/{dataset_id}/preview

查询参数:

  • sample_id: 样本 ID (可选)
  • limit: 预览样本数量 (默认 5)

检查数据集访问权限

GET /datasets/{dataset_id}/access

响应 (HTTP 200):

{
  "has_access": true,
  "access_level": "premium",
  "remaining_quota": 38000,
  "expires_at": "2024-12-31T23:59:59Z",
  "restrictions": {
    "max_concurrent_access": 5,
    "allowed_regions": ["cn-north", "cn-south"]
  }
}

3.2 数据集上传和创建

创建数据集

POST /datasets

请求体:

{
  "name": "我的WSI病理数据集",
  "description": "包含肺癌、乳腺癌病理切片的高质量数据集",
  "category": "wsi",
  "access_level": "premium",
  "license_type": "CC-BY-4.0",
  "tags": ["pathology", "cancer", "lung", "breast"],
  "workspace_id": "workspace_abc123",
  "visibility": "workspace"
}

字段说明:

  • name: 数据集名称 (必需)
  • description: 详细描述 (可选)
  • category: 数据类型 (必需: wsi, mcap, general)
  • access_level: 访问级别 (必需: public, premium, enterprise)
  • license_type: 许可证类型 (可选)
  • tags: 标签数组 (可选)
  • workspace_id: 工作空间 ID (可选，默认使用用户的个人工作空间)
  • visibility: 可见性 (可选，默认: private)

默认工作空间行为:

  • 如果未指定 workspace_id，数据集将自动创建在用户的默认个人工作空间中
  • 如果指定了 workspace_id，系统会验证用户是否有权限在该工作空间中创建数据集
  • 数据集的 slug 会根据名称自动生成，并确保在工作空间内唯一

响应 (HTTP 201):

{
  "id": "dataset_xyz789",
  "name": "我的WSI病理数据集",
  "full_name": "john_doe/my-wsi-pathology",
  "slug": "my-wsi-pathology",
  "category": "wsi",
  "workspace": {
    "id": "workspace_abc123",
    "name": "john_doe's Personal Workspace",
    "slug": "john_doe"
  },
  "created_at": "2024-01-15T10:00:00Z"
}

初始化批量文件上传

POST /datasets/{dataset_id}/upload-session

请求体:

{
  "files": [
    {
      "name": "slide_001.tiff",
      "size": 1073741824,
      "content_type": "image/tiff",
      "category": "image",
      "metadata": {
        "magnification": "40x",
        "disease": "lung_cancer",
        "staining": "H&E"
      }
    },
    {
      "name": "slide_001_annotations.geojson",
      "size": 2048,
      "content_type": "application/geo+json",
      "category": "annotation",
      "relates_to": "slide_001.tiff",
      "annotation_type": "region"
    }
  ],
  "total_size": 1073743872,
  "chunk_size": 10485760
}

响应 (HTTP 201):

{
  "session_id": "upload_session_abc123",
  "dataset_id": "dataset_xyz789",
  "status": "initialized",
  "expires_at": "2024-01-15T12:00:00Z",
  "upload_urls": [
    {
      "file_id": "file_001",
      "name": "slide_001.tiff",
      "upload_method": "multipart",
      "multipart_upload_id": "multipart_abc123",
      "chunk_urls": [
        {
          "part_number": 1,
          "upload_url": "https://storage.bitflow.ai/multipart/part1",
          "expires_at": "2024-01-15T11:00:00Z"
        }
      ]
    },
    {
      "file_id": "file_002",
      "name": "slide_001_annotations.geojson",
      "upload_method": "single",
      "upload_url": "https://storage.bitflow.ai/uploads/file_002",
      "expires_at": "2024-01-15T11:00:00Z"
    }
  ]
}

确认文件上传完成

POST /datasets/{dataset_id}/upload-session/{session_id}/files/{file_id}/complete

请求体:

{
  "etags": [
    {
      "part_number": 1,
      "etag": "abc123def456"
    }
  ],
  "checksum": "sha256:abcdef1234567890..."
}

完成上传会话

POST /datasets/{dataset_id}/upload-session/{session_id}/complete

请求体:

{
  "validation_options": {
    "enable_format_validation": true,
    "enable_annotation_validation": true,
    "enable_quality_check": true
  }
}

响应 (HTTP 200):

{
  "dataset_id": "dataset_xyz789",
  "status": "processing",
  "processing_job_id": "job_validation_123",
  "estimated_completion": "2024-01-15T10:30:00Z",
  "uploaded_files": {
    "total": 2,
    "images": 1,
    "annotations": 1,
    "total_size": 1073743872
  }
}

获取上传会话状态

GET /datasets/{dataset_id}/upload-session/{session_id}

响应 (HTTP 200):

{
  "session_id": "upload_session_abc123",
  "dataset_id": "dataset_xyz789",
  "status": "processing",
  "progress": {
    "uploaded_files": 2,
    "total_files": 2,
    "processed_files": 1,
    "validation_status": "in_progress",
    "percentage": 75
  },
  "files": [
    {
      "file_id": "file_001",
      "name": "slide_001.tiff",
      "status": "validated",
      "size": 1073741824,
      "validation_result": {
        "format_valid": true,
        "quality_score": 9.2,
        "issues": []
      }
    },
    {
      "file_id": "file_002",
      "name": "slide_001_annotations.geojson",
      "status": "validating",
      "size": 2048,
      "relates_to": "file_001"
    }
  ],
  "created_at": "2024-01-15T10:00:00Z",
  "expires_at": "2024-01-15T12:00:00Z"
}

3.3 Annotation 管理

添加数据标注

POST /datasets/{dataset_id}/annotations

请求体:

{
  "target_file_id": "file_001",
  "annotation_type": "region",
  "format": "geojson",
  "data": {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "properties": {
          "label": "tumor",
          "confidence": 0.95,
          "annotator": "pathologist_001",
          "created_at": "2024-01-15T10:00:00Z"
        },
        "geometry": {
          "type": "Polygon",
          "coordinates": [
            [
              [0, 0],
              [100, 0],
              [100, 100],
              [0, 100],
              [0, 0]
            ]
          ]
        }
      }
    ]
  },
  "metadata": {
    "annotator_id": "user_123",
    "annotation_tool": "QuPath",
    "magnification": "40x",
    "quality_level": "expert"
  }
}

响应 (HTTP 201):

{
  "annotation_id": "annotation_abc123",
  "dataset_id": "dataset_xyz789",
  "target_file_id": "file_001",
  "annotation_type": "region",
  "format": "geojson",
  "status": "active",
  "version": 1,
  "statistics": {
    "feature_count": 1,
    "label_distribution": {
      "tumor": 1
    }
  },
  "created_at": "2024-01-15T10:00:00Z"
}

获取数据标注

GET /datasets/{dataset_id}/annotations

查询参数:

  • file_id: 文件 ID (可选)
  • annotation_type: 标注类型 (region, cell_detection, classification)
  • format: 格式 (geojson, coco, yolo)
  • version: 版本号 (默认最新)

更新数据标注

PUT /datasets/{dataset_id}/annotations/{annotation_id}

导出标注数据

GET /datasets/{dataset_id}/annotations/export

查询参数:

  • format: 导出格式 (geojson, coco, yolo, csv)
  • annotation_types: 标注类型列表
  • include_metadata: 是否包含元数据

响应 (HTTP 200):

{
  "export_id": "export_abc123",
  "download_url": "https://storage.bitflow.ai/exports/annotations_export.zip",
  "format": "geojson",
  "expires_at": "2024-01-22T10:00:00Z",
  "file_size": 1024000,
  "statistics": {
    "total_annotations": 150,
    "files_count": 10,
    "annotation_types": {
      "region": 100,
      "cell_detection": 50
    }
  }
}

3.4 数据验证和质量控制

验证数据集

POST /datasets/{dataset_id}/validate

请求体:

{
  "validation_config": {
    "check_file_integrity": true,
    "check_annotation_consistency": true,
    "check_format_compliance": true,
    "quality_thresholds": {
      "min_image_quality": 7.0,
      "min_annotation_coverage": 0.8
    }
  }
}

响应 (HTTP 202):

{
  "validation_job_id": "validation_job_123",
  "status": "pending",
  "estimated_duration": 300,
  "created_at": "2024-01-15T10:00:00Z"
}

获取验证结果

GET /datasets/{dataset_id}/validation/{job_id}

响应 (HTTP 200):

{
  "job_id": "validation_job_123",
  "dataset_id": "dataset_xyz789",
  "status": "completed",
  "overall_score": 8.5,
  "results": {
    "file_integrity": {
      "status": "passed",
      "checked_files": 10,
      "corrupted_files": 0
    },
    "annotation_consistency": {
      "status": "passed",
      "total_annotations": 150,
      "inconsistent_annotations": 2,
      "issues": [
        {
          "file_id": "file_003",
          "issue": "Missing required label",
          "severity": "warning"
        }
      ]
    },
    "format_compliance": {
      "status": "passed",
      "compliant_files": 10,
      "format_issues": []
    },
    "quality_metrics": {
      "average_image_quality": 8.7,
      "annotation_coverage": 0.95,
      "label_distribution": {
        "tumor": 0.6,
        "normal": 0.4
      }
    }
  },
  "recommendations": [
    "Consider reviewing annotations in file_003",
    "Label distribution is well balanced"
  ],
  "completed_at": "2024-01-15T10:05:00Z"
}

3.5 数据集版本管理

创建数据集版本

POST /datasets/{dataset_id}/versions

请求体:

{
  "version": "v1.1.0",
  "description": "添加了新的病理切片和改进的标注",
  "changes": [
    "新增50张肺癌切片",
    "修正了部分标注错误",
    "添加了细胞级别的检测标注"
  ],
  "files_to_add": ["file_011", "file_012"],
  "files_to_remove": ["file_002"],
  "annotation_updates": {
    "file_001": "annotation_v2_abc"
  }
}

获取版本列表

GET /datasets/{dataset_id}/versions

切换到指定版本

POST /datasets/{dataset_id}/versions/{version}/checkout

3.6 数据订阅管理

获取订阅计划

GET /subscriptions/plans

响应 (HTTP 200):

{
  "plans": [
    {
      "id": "wsi_basic",
      "name": "WSI基础版",
      "category": "wsi",
      "price": 9999,
      "currency": "CNY",
      "billing_cycle": "monthly",
      "features": {
        "monthly_quota": 10000,
        "dataset_access": ["bitflow/wsi-pathology-basic"],
        "support_level": "email",
        "api_calls_limit": 10000
      },
      "trial_available": true,
      "trial_duration": 7
    }
  ]
}

创建订阅

POST /subscriptions

请求体:

{
  "plan_id": "wsi_professional",
  "billing_cycle": "monthly",
  "payment_method": "alipay",
  "coupon_code": "WELCOME2024"
}

响应 (HTTP 201):

{
  "subscription_id": "sub_abc123",
  "plan": {
    "id": "wsi_professional",
    "name": "WSI专业版",
    "price": 39999
  },
  "status": "active",
  "current_period_start": "2024-01-01T00:00:00Z",
  "current_period_end": "2024-01-31T23:59:59Z",
  "created_at": "2024-01-01T00:00:00Z"
}

获取用户订阅状态

GET /subscriptions/current

使用量统计

GET /subscriptions/usage

查询参数:

  • start_date: 开始日期 (YYYY-MM-DD)
  • end_date: 结束日期 (YYYY-MM-DD)
  • granularity: 统计粒度 (daily, weekly, monthly)

响应 (HTTP 200):

{
  "current_period": {
    "start_date": "2024-01-01",
    "end_date": "2024-01-31",
    "wsi_usage": {
      "used": 12000,
      "limit": 50000,
      "percentage": 24
    },
    "mcap_usage": {
      "used": 120,
      "limit": 500,
      "percentage": 24
    }
  },
  "usage_history": [
    {
      "date": "2024-01-15",
      "wsi_usage": 800,
      "mcap_usage": 5,
      "training_jobs": 12
    }
  ]
}

4. Git 平台集成 API

4.1 平台连接管理

连接 Git 平台账户

POST /git-platforms/{platform}/connect

路径参数:

  • platform: 平台类型 (github, gitlab, gitee)

请求体:

{
  "authorization_code": "oauth_code",
  "permissions": ["repo", "webhook"]
}

获取已连接的 Git 平台

GET /git-platforms

响应 (HTTP 200):

{
  "platforms": [
    {
      "platform": "github",
      "username": "john_doe",
      "connected_at": "2024-01-01T00:00:00Z",
      "permissions": ["repo", "webhook"],
      "status": "active",
      "repositories_count": 25
    }
  ]
}

断开 Git 平台连接

DELETE /git-platforms/{platform}

响应 (HTTP 204 No Content):

  • 成功断开连接，无响应体

4.2 仓库管理

获取可用仓库列表

GET /repositories

查询参数:

  • platform: 平台类型 (github, gitlab, gitee)
  • type: 仓库类型 (public, private, all)
  • connected: 是否已连接 (true, false, all)
  • page: 页码
  • limit: 每页数量

响应 (HTTP 200):

{
  "repositories": [
    {
      "id": "repo_123",
      "platform": "github",
      "full_name": "john_doe/my-ai-project",
      "name": "my-ai-project",
      "description": "My AI training project",
      "private": false,
      "url": "https://github.com/john_doe/my-ai-project",
      "default_branch": "main",
      "connected": true,
      "connected_at": "2024-01-01T00:00:00Z",
      "last_training": {
        "commit": "abc123",
        "status": "completed",
        "created_at": "2024-01-15T10:30:00Z"
      },
      "bitflow_config": {
        "exists": true,
        "valid": true,
        "data_mounts": ["bitflow/wsi-pathology-basic"]
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 25,
    "pages": 2
  }
}

连接仓库到 BitFlow 平台

POST /repositories/{repo_id}/connect

请求体:

{
  "auto_training": true,
  "webhook_events": ["push", "pull_request"],
  "branch_filter": ["main", "develop"]
}

断开仓库连接

DELETE /repositories/{repo_id}/connect

验证 bitflow.yml 配置

POST /repositories/{repo_id}/validate-config

请求体:

{
  "config_content": "data_mounts:\n  - source: bitflow/wsi-pathology-basic\n    target: /data/wsi"
}

响应 (HTTP 200):

{
  "valid": true,
  "data_mounts": [
    {
      "source": "bitflow/wsi-pathology-basic",
      "target": "/data/wsi",
      "accessible": true,
      "quota_sufficient": true
    }
  ],
  "warnings": [],
  "errors": []
}

4.3 Webhook 管理

Webhook 事件处理 (内部 API)

POST /webhooks/{platform}/events

请求头:

  • X-Hub-Signature: webhook 签名验证
  • X-GitHub-Event: 事件类型 (GitHub)
  • X-Gitlab-Event: 事件类型 (GitLab)

5. AI 训练引擎 API

5.1 训练任务管理

获取训练任务列表

GET /training-jobs

查询参数:

  • repository_id: 仓库 ID
  • status: 任务状态 (pending, running, completed, failed)
  • start_date: 开始日期
  • end_date: 结束日期
  • page: 页码
  • limit: 每页数量

响应 (HTTP 200):

{
  "jobs": [
    {
      "id": "job_abc123",
      "repository": {
        "platform": "github",
        "full_name": "john_doe/my-ai-project",
        "branch": "main",
        "commit": "abc123def456"
      },
      "status": "running",
      "created_at": "2024-01-15T10:00:00Z",
      "started_at": "2024-01-15T10:02:00Z",
      "completed_at": null,
      "duration": 1800,
      "config": {
        "data_mounts": [
          {
            "source": "bitflow/wsi-pathology-basic",
            "target": "/data/wsi"
          }
        ],
        "gpu_type": "A100",
        "timeout": "2h"
      },
      "progress": {
        "stage": "training",
        "percentage": 45,
        "current_step": "epoch_5_of_10",
        "estimated_remaining": 1200
      },
      "resource_usage": {
        "cpu_usage": 80,
        "memory_usage": 12.5,
        "gpu_usage": 95,
        "data_transfer": 2.3
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "pages": 8
  }
}

获取训练任务详情

GET /training-jobs/{job_id}

手动触发训练任务

POST /training-jobs

请求体:

{
  "repository_id": "repo_123",
  "branch": "main",
  "commit": "abc123def456",
  "config_override": {
    "gpu_type": "V100",
    "timeout": "4h"
  }
}

响应 (HTTP 201):

{
  "id": "job_xyz789",
  "status": "pending",
  "repository": {
    "platform": "github",
    "full_name": "john_doe/my-ai-project",
    "branch": "main",
    "commit": "abc123def456"
  },
  "config": {
    "data_mounts": [
      {
        "source": "bitflow/wsi-pathology-basic",
        "target": "/data/wsi"
      }
    ],
    "gpu_type": "V100",
    "timeout": "4h"
  },
  "created_at": "2024-01-15T10:00:00Z",
  "estimated_start_time": "2024-01-15T10:05:00Z"
}

停止训练任务

POST /training-jobs/{job_id}/stop

重新运行训练任务

POST /training-jobs/{job_id}/restart

5.2 训练日志和监控

获取训练日志

GET /training-jobs/{job_id}/logs

查询参数:

  • tail: 获取最后 N 行日志
  • follow: 是否实时跟踪 (WebSocket)
  • since: 获取指定时间后的日志

响应 (HTTP 200):

{
  "logs": [
    {
      "timestamp": "2024-01-15T10:15:30Z",
      "level": "INFO",
      "message": "Loading dataset from /data/wsi...",
      "source": "training_script"
    }
  ],
  "has_more": true,
  "next_cursor": "cursor_xyz"
}

获取训练指标

GET /training-jobs/{job_id}/metrics

查询参数:

  • metric_names: 指标名称列表 (accuracy,loss,learning_rate)
  • start_time: 开始时间
  • end_time: 结束时间
  • resolution: 数据分辨率 (1m, 5m, 1h)

响应 (HTTP 200):

{
  "metrics": {
    "accuracy": [
      { "timestamp": "2024-01-15T10:15:00Z", "value": 0.85 },
      { "timestamp": "2024-01-15T10:20:00Z", "value": 0.87 }
    ],
    "loss": [
      { "timestamp": "2024-01-15T10:15:00Z", "value": 0.32 },
      { "timestamp": "2024-01-15T10:20:00Z", "value": 0.28 }
    ]
  }
}

5.3 训练结果管理

获取训练结果

GET /training-jobs/{job_id}/results

响应 (HTTP 200):

{
  "artifacts": [
    {
      "name": "model.pth",
      "type": "model",
      "size": 1024000,
      "download_url": "https://storage.bitflow.ai/artifacts/job_123/model.pth",
      "expires_at": "2024-01-22T10:00:00Z"
    },
    {
      "name": "training_report.pdf",
      "type": "report",
      "size": 204800,
      "download_url": "https://storage.bitflow.ai/artifacts/job_123/report.pdf"
    }
  ],
  "summary": {
    "final_accuracy": 0.92,
    "best_epoch": 8,
    "total_epochs": 10,
    "training_time": 3600,
    "data_usage": {
      "wsi_samples_used": 8500,
      "total_data_size": "15GB"
    }
  }
}

推送结果到 Git 仓库

POST /training-jobs/{job_id}/push-results

请求体:

{
  "target_branch": "training-results",
  "artifacts": ["model.pth", "training_report.pdf"],
  "commit_message": "Add training results from job {job_id}"
}

6. 系统监控和管理 API

6.1 系统状态

系统健康检查

GET /health

响应 (HTTP 200):

{
  "status": "healthy",
  "services": {
    "database": "healthy",
    "redis": "healthy",
    "storage": "healthy",
    "training_engine": "healthy"
  },
  "version": "v1.0.0"
}

获取系统统计

GET /admin/stats

权限要求: 管理员

响应 (HTTP 200):

{
  "users": {
    "total": 1250,
    "active_monthly": 890,
    "new_this_month": 156
  },
  "datasets": {
    "total": 45,
    "total_size": "500TB",
    "downloads_this_month": 12500
  },
  "training_jobs": {
    "total": 15600,
    "running": 25,
    "completed_this_month": 2890,
    "success_rate": 94.5
  },
  "revenue": {
    "monthly": 2500000,
    "annual": 28000000,
    "growth_rate": 25.5
  }
}

6.2 用户管理 (管理员)

获取用户列表

GET /admin/users

获取用户详情

GET /admin/users/{user_id}

更新用户订阅

PUT /admin/users/{user_id}/subscription

冻结/解冻用户

POST /admin/users/{user_id}/freeze
POST /admin/users/{user_id}/unfreeze

6.3 数据集管理 (管理员)

创建数据集

POST /admin/datasets

更新数据集

PUT /admin/datasets/{dataset_id}

删除数据集

DELETE /admin/datasets/{dataset_id}

数据集使用统计

GET /admin/datasets/{dataset_id}/analytics

7. WebSocket API

7.1 实时通知

连接 WebSocket

WSS /ws/notifications?token={jwt_token}

消息格式

{
  "type": "training_status",
  "data": {
    "job_id": "job_abc123",
    "status": "completed",
    "progress": 100,
    "message": "Training completed successfully"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

支持的消息类型

  • training_status: 训练状态更新
  • quota_warning: 配额预警
  • system_notification: 系统通知
  • data_update: 数据集更新通知

7.2 实时日志流

连接训练日志流

WSS /ws/training-jobs/{job_id}/logs?token={jwt_token}

8. 文件上传和存储 API

8.1 文件上传

获取上传 URL (预签名)

POST /uploads/presigned-url

请求体:

{
  "filename": "dataset.zip",
  "content_type": "application/zip",
  "size": 1073741824,
  "purpose": "dataset_upload"
}

响应 (HTTP 200):

{
  "upload_url": "https://storage.bitflow.ai/uploads/abc123",
  "upload_id": "upload_abc123",
  "expires_at": "2024-01-15T11:00:00Z",
  "method": "PUT",
  "headers": {
    "Content-Type": "application/zip"
  }
}

确认上传完成

POST /uploads/{upload_id}/complete

8.2 文件下载

获取下载 URL (预签名)

GET /downloads/{file_id}/url

响应 (HTTP 200):

{
  "download_url": "https://storage.bitflow.ai/downloads/abc123",
  "expires_at": "2024-01-15T11:00:00Z"
}

9. 计费和支付 API

9.1 计费记录

获取账单列表

GET /billing/invoices

获取账单详情

GET /billing/invoices/{invoice_id}

下载账单 PDF

GET /billing/invoices/{invoice_id}/pdf

9.2 支付管理

创建支付订单

POST /payments/orders

查询支付状态

GET /payments/orders/{order_id}

支付回调 (Webhook)

POST /payments/webhooks/{provider}

10. 数据安全和审计 API

10.1 访问日志

获取数据访问日志

GET /audit/data-access

查询参数:

  • dataset_id: 数据集 ID
  • user_id: 用户 ID
  • start_date: 开始日期
  • end_date: 结束日期
  • action: 操作类型 (read, download, preview)

10.2 安全事件

获取安全事件

GET /security/events

报告安全事件

POST /security/events

11. API 限流和配额

11.1 限流规则

接口类别限流规则说明
认证相关10 次/分钟防止暴力破解
数据预览100 次/小时控制预览请求
训练任务50 次/小时控制任务创建频率
文件上传10GB/小时控制上传带宽
普通接口1000 次/小时通用限流

11.2 配额检查

检查 API 配额

GET /quotas/api

检查数据配额

GET /quotas/data

12. 错误处理示例

12.1 数据访问权限不足 (HTTP 403)

{
  "message": "Insufficient data access permission",
  "dataset_id": "bitflow/wsi-pathology-pro",
  "required_plan": "professional",
  "current_plan": "basic",
  "upgrade_url": "/subscriptions/upgrade"
}

12.2 配额超限 (HTTP 429)

{
  "message": "Monthly data quota exceeded",
  "quota_type": "wsi_monthly",
  "used": 50000,
  "limit": 50000,
  "reset_date": "2024-02-01T00:00:00Z"
}

12.3 训练任务配置错误 (HTTP 400)

{
  "message": "Training job configuration invalid",
  "errors": [
    {
      "field": "data_mounts[0].source",
      "code": "invalid_value",
      "message": "Dataset 'bitflow/invalid-dataset' does not exist",
      "suggested_datasets": [
        "bitflow/wsi-pathology-basic",
        "bitflow/wsi-pathology-pro"
      ]
    }
  ]
}

12.4 认证失败 (HTTP 401)

{
  "message": "Invalid or expired access token",
  "reason": "token_expired",
  "expired_at": "2024-01-01T12:00:00Z",
  "refresh_url": "/auth/refresh"
}

12.5 资源不存在 (HTTP 404)

{
  "message": "Dataset not found",
  "resource_type": "dataset",
  "resource_id": "bitflow/non-existent-dataset"
}

13. API 版本和兼容性

13.1 版本策略

  • 主版本号变更: 不兼容的 API 变更
  • 次版本号变更: 向后兼容的功能添加
  • 修订版本号变更: 向后兼容的问题修复

13.2 废弃通知

API 废弃将提前 3 个月通知，通过以下方式：

  • 响应头 X-API-Deprecated: true
  • 响应头 X-API-Sunset: 2024-06-01
  • 邮件通知活跃用户

13.3 向后兼容

  • 新增字段不会破坏向后兼容性
  • 现有字段的行为不会改变
  • URL 路径结构保持稳定
最后更新
远程 k3d 部署API 响应模式