# 第四章 API 接口设计

> 版本：V1.0  
> 基于文档：《AIGC-Hub智视码(AVCC)体系建设方案 V2.0》

---

## 4.1 统一接口规范

### 4.1.1 基础约定

| 项 | 规范 |
|----|------|
| 协议 | HTTPS，TLS 1.3 |
| 数据格式 | JSON (Content-Type: application/json) |
| 编码 | UTF-8 |
| 版本控制 | URL 路径中包含版本号，如 `/api/v1/...` |
| 时间格式 | RFC 3339 (ISO 8601)，如 `2026-06-02T14:30:00+08:00` |
| 分页 | `limit` + `offset`，响应含 `total`, `has_more` |
| 空值 | `null`，不省略字段 |

### 4.1.2 鉴权机制

采用 **API Key + HMAC-SHA256 签名** 双因素鉴权。

**请求头格式：**

```http
Authorization: AIGHUB {api_key}:{signature}
X-AIGHUB-Timestamp: 1717312200
X-AIGHUB-Nonce: {uuid}
```

**签名算法示例（Go）：**

```go
import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/base64"
    "fmt"
)

func GenerateSignature(method, uri, bodyHash, timestamp, nonce, apiSecret string) string {
    stringToSign := fmt.Sprintf("%s\n%s\n%s\n%s\n%s", method, uri, bodyHash, timestamp, nonce)
    h := hmac.New(sha256.New, []byte(apiSecret))
    h.Write([]byte(stringToSign))
    return base64.StdEncoding.EncodeToString(h.Sum(nil))
}
```

### 4.1.3 限流策略

| 平台类型 | 日配额 | QPS 限制 | 突发缓冲 |
|----------|--------|----------|----------|
| 长视频平台 | 100万 | 500 | 100 |
| 短视频平台 | 500万 | 2000 | 500 |
| AI 工具厂商 | 50万 | 200 | 50 |
| MCN 机构 | 10万 | 50 | 20 |
| 跨境平台 | 20万 | 100 | 30 |

**限流响应：**

```json
{
  "error_code": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded",
  "retry_after": 60,
  "quota_reset_at": "2026-06-03T00:00:00+08:00"
}
```

### 4.1.4 统一响应格式

```json
{
  "code": "SUCCESS",
  "data": { ... },
  "request_id": "req_20260602_001",
  "timestamp": "2026-06-02T14:30:00+08:00"
}
```

**错误响应格式：**

```json
{
  "code": "ERROR_CODE",
  "message": "人类可读的错误描述",
  "detail": { ... },
  "request_id": "req_20260602_001"
}
```

### 4.1.5 错误码定义

| 错误码 | HTTP 状态码 | 说明 |
|--------|-------------|------|
| `SUCCESS` | 200 | 成功 |
| `CREATED` | 201 | 创建成功 |
| `ACCEPTED` | 202 | 异步任务已接收 |
| `INVALID_REQUEST` | 400 | 请求参数错误 |
| `UNAUTHORIZED` | 401 | 鉴权失败 |
| `FORBIDDEN` | 403 | 权限不足 |
| `NOT_FOUND` | 404 | 资源不存在 |
| `RATE_LIMIT_EXCEEDED` | 429 | 限流触发 |
| `INTERNAL_ERROR` | 500 | 内部错误 |
| `SERVICE_UNAVAILABLE` | 503 | 服务暂不可用 |
| `AVCC_INVALID` | 400 | AVCC 编码格式无效 |
| `AVCC_REVOKED` | 400 | AVCC 已被注销 |
| `LICENSE_EXPIRED` | 400 | 网标许可证已过期 |
| `BLACKLISTED` | 403 | 目标在黑名单中 |

---

## 4.2 赋码服务接口

### 4.2.1 提交赋码申请

```http
POST /api/v1/code/apply
Authorization: AIGHUB {api_key}:{signature}
Content-Type: multipart/form-data

Request (multipart):
--boundary
Content-Disposition: form-data; name="metadata"
Content-Type: application/json

{
  "title": "AI漫剧标题",
  "platform_node": "MA.156.10005.8361",
  "object_category": "10.1300200.AIGC",
  "content_type": "ai_drama",
  "duration_sec": 1800,
  "ai_tool_info": {
    "model_name": "Stable-Diffusion-XL",
    "model_version": "v1.0",
    "sdk_version": "AIGC-Hub-SDK/1.0.0",
    "manual_edit_ratio": 0.15
  },
  "copyright_materials": [
    {"type": "training_data_license", "file_hash": "sha256:abc123...", "description": "训练数据授权书"},
    {"type": "manual_edit_note", "file_hash": "sha256:def456...", "description": "人工修改说明"},
    {"type": "ip_license", "file_hash": "sha256:ghi789...", "description": "原著改编授权书"}
  ],
  "license_application": {
    "license_type": "network_micro_drama",
    "applying_province": "110000",
    "is_key_content": true
  }
}

--boundary
Content-Disposition: form-data; name="content"; filename="work.mp4"
Content-Type: video/mp4

[binary content]

--boundary
Content-Disposition: form-data; name="c2pa_manifest"; filename="manifest.json"
Content-Type: application/json

[binary content]
--boundary--

Response (202 Accepted):
{
  "code": "ACCEPTED",
  "data": {
    "request_id": "req_20260602_001",
    "status": "pre_checking",
    "estimated_time": "5-30工作日",
    "check_list": {
      "duplicate": "pending",
      "blacklist": "pending",
      "material_complete": "pending"
    },
    "tracking_url": "https://aigc-hub.cn/workbench/code/status/req_20260602_001"
  },
  "request_id": "req_20260602_001"
}
```

### 4.2.2 查询赋码进度

```http
GET /api/v1/code/status/{request_id}

Response:
{
  "code": "SUCCESS",
  "data": {
    "request_id": "req_20260602_001",
    "status": "ai_reviewing",
    "progress": 45,
    "avcc": null,
    "review_report_id": "rpt_20260602_001",
    "check_list": {
      "duplicate": "passed",
      "blacklist": "passed",
      "material_complete": "passed"
    },
    "current_stage": "AI 画面审核中 (12/30帧)",
    "estimated_completion": "2026-06-05T10:00:00+08:00"
  }
}
```

### 4.2.3 获取 AVCC 证书

```http
GET /api/v1/code/certificate/{avcc_code}

Response:
{
  "code": "SUCCESS",
  "data": {
    "avcc": "MA.156.10005.8361/10.1300200.AIGC/(京)网微剧审字(2026)第001号-P-AI-HASH(a1b2c3)-CRD(0x7f3e9a)",
    "qr_code_url": "https://aigc-hub.cn/q/MA.156.10005.8361...",
    "certificate_pdf_url": "https://aigc-hub.cn/cert/...",
    "certificate_png_url": "https://aigc-hub.cn/cert/...png",
    "chain_tx_hash": "0xabc123...",
    "valid_until": "2028-05-31T23:59:59+08:00",
    "circulation_rights": {
      "scope": "全网全平台首页推荐",
      "restrictions": [],
      "expires_at": "2028-05-31T23:59:59+08:00"
    }
  }
}
```

### 4.2.4 批量赋码申请（MCN）

```http
POST /api/v1/code/apply/batch
Content-Type: multipart/form-data

Request:
{
  "batch_name": "2026年6月第二批",
  "platform_node": "MA.156.10005.8361",
  "works": [
    {
      "index": 1,
      "title": "作品1",
      "object_category": "10.1300200.AIGC",
      "metadata": { ... }
    },
    {
      "index": 2,
      "title": "作品2",
      "object_category": "10.1300200.AIGC",
      "metadata": { ... }
    }
  ]
}

+ file: batch.zip (包含所有作品内容与 C2PA 文件)

Response (202 Accepted):
{
  "code": "ACCEPTED",
  "data": {
    "batch_id": "batch_20260602_001",
    "total": 50,
    "accepted": 50,
    "request_ids": ["req_20260602_002", "req_20260602_003", ...]
  }
}
```

---

## 4.3 审核服务接口

### 4.3.1 AI 预审接口（实时提交）

```http
POST /api/v1/review/ai-screen

Request:
{
  "content_url": "https://storage.aigc-hub.cn/works/xxx.mp4",
  "content_hash": "sha256:abc123...",
  "content_type": "ai_drama",
  "duration_sec": 1800,
  "callback_url": "https://platform.example.com/cb/review",
  "priority": 5,
  "requested_level": "G"
}

Response (202 Accepted):
{
  "code": "ACCEPTED",
  "data": {
    "task_id": "task_20260602_001",
    "status": "queued",
    "queue_position": 15,
    "estimated_seconds": 120
  }
}
```

### 4.3.2 获取预审报告

```http
GET /api/v1/review/report/{task_id}

Response:
{
  "code": "SUCCESS",
  "data": {
    "task_id": "task_20260602_001",
    "status": "completed",
    "overall_score": 78.5,
    "suggested_level": "G",
    "final_level": null,
    "dimension_scores": {
      "vision": 82.0,
      "dialogue": 75.0,
      "audio": 88.0,
      "authenticity": 90.0,
      "copyright": 95.0
    },
    "violations": [
      {
        "type": "dialogue",
        "line": 23,
        "timestamp": "00:05:30",
        "severity": "medium",
        "keyword": "敏感词示例",
        "context": "台词上下文片段",
        "suggestion": "建议替换为 xxx"
      },
      {
        "type": "vision",
        "timestamp": "00:02:15",
        "frame": 3450,
        "severity": "low",
        "category": "血腥画面",
        "confidence": 0.72,
        "bbox": [120, 200, 300, 400],
        "suggestion": "建议打码或删减 0:02:10-0:02:20"
      }
    ],
    "model_details": {
      "vision_model": "review-vision-v2.1",
      "nlp_model": "review-nlp-v2.0",
      "audio_model": "review-audio-v1.5",
      "authenticity_model": "review-aigc-v3.0"
    },
    "report_url": "https://aigc-hub.cn/reports/task_20260602_001.pdf",
    "ai_model_version": "review-v2.1.0-20260601",
    "processing_time": {
      "queue_wait_ms": 1200,
      "preprocess_ms": 3000,
      "inference_ms": 38000,
      "fusion_ms": 500,
      "total_ms": 45230
    }
  }
}
```

### 4.3.3 人工审核提交（平台人工复核）

```http
POST /api/v1/review/human-submit

Request:
{
  "task_id": "task_20260602_001",
  "reviewer_id": "reviewer_001",
  "final_level": "G",
  "decision": "approved",
  "comment": "AI 预审中标记的敏感词经人工复核为误报，已确认台词语境合规。",
  "violation_corrections": [
    {"index": 0, "action": "overridden", "reason": "语境合规"}
  ],
  "signature_hash": "sha256:..."
}

Response:
{
  "code": "SUCCESS",
  "data": {
    "review_id": "rpt_20260602_001",
    "status": "approved",
    "avcc": "MA.156.10005.8361/10.1300200.AIGC/(沪)网微剧审字(2026)第0158号-G-AI-HASH(b2c3d4)-CRD(0x8g4f0b)",
    "chain_tx_hash": "0xhuman123..."
  }
}
```

---

## 4.4 MA 编码网关接口

### 4.4.1 AVCC 解析

```http
POST /api/v1/avcc/parse

Request:
{
  "avcc": "MA.156.10005.8361/10.1300200.AIGC/(京)网微剧审字(2026)第001号-P-AI-HASH(a1b2c3)-CRD(0x7f3e9a)",
  "include_chain_records": true
}

Response:
{
  "code": "SUCCESS",
  "data": {
    "valid": true,
    "ma_verified": true,
    "parsed": {
      "ma_root": "MA",
      "country_code": "156",
      "industry_node": "10005",
      "platform_node": "8361",
      "object_category": "10.1300200.AIGC",
      "license_no": "(京)网微剧审字(2026)第001号",
      "review_level": "P",
      "version": 1,
      "ai_hash": "a1b2c3",
      "copyright_crd": "0x7f3e9a"
    },
    "circulation_rights": {
      "scope": "全网全平台首页推荐",
      "restrictions": [],
      "prohibited_actions": [],
      "expires_at": "2028-05-31T23:59:59+08:00"
    },
    "platform_info": {
      "platform_node": "8361",
      "platform_name": "示例长视频平台",
      "platform_type": "long_video",
      "status": "active"
    },
    "chain_records": [
      {
        "type": "copyright_main",
        "tx_hash": "0xabc...",
        "block_height": 1234567,
        "timestamp": "2026-05-20T10:00:00+08:00",
        "confirmation_count": 12
      }
    ],
    "blacklist_check": "passed"
  }
}
```

### 4.4.2 校验 AVCC 有效性

```http
POST /api/v1/avcc/validate

Request:
{
  "avcc": "MA.156.10005.8361/10.1300200.AIGC/...",
  "strict": true
}

Response:
{
  "code": "SUCCESS",
  "data": {
    "valid": true,
    "ma_root_valid": true,
    "license_valid": true,
    "chain_valid": true,
    "circulation_active": true,
    "blacklist_check": "passed",
    "expiration_status": "active",
    "warnings": []
  }
}
```

### 4.4.3 对接 MA 根解析

```http
POST /api/v1/avcc/resolve

Request:
{
  "avcc": "MA.156.10005.8361/10.1300200.AIGC/...",
  "resolution_depth": "full"
}

Response:
{
  "code": "SUCCESS",
  "data": {
    "avcc": "MA.156.10005.8361/10.1300200.AIGC/...",
    "ma_resolution": {
      "root_node": "MA (ZIIOT)",
      "country_node": "MA.156 (中国)",
      "industry_node": "MA.156.10005 (AIGC视听内容行业节点 - 广电云)",
      "platform_node": "MA.156.10005.8361 (示例平台)",
      "resolution_path": ["MA", "156", "10005", "8361"],
      "trust_level": "verified",
      "last_verified": "2026-06-02T14:30:00+08:00"
    },
    "global_status": "active",
    "cross_platform_rights": {
      "domestic": ["douyin", "bilibili", "kuaishou", "xiaohongshu"],
      "international": ["pending"]
    }
  }
}
```

### 4.4.4 平台节点注册（内部接口）

```http
POST /api/v1/node/register
Authorization: AIGHUB {internal_key}:{signature}

Request:
{
  "platform_name": "示例短视频平台",
  "platform_type": "short_video",
  "enterprise_name": "示例科技有限公司",
  "enterprise_credit_code": "91110108MA00xxxx",
  "contact_name": "张三",
  "contact_phone": "13800138000",
  "contact_email": "admin@example.com",
  "callback_url": "https://api.example.com/aigc-hub/cb",
  "quota_request": {
    "daily_calls": 5000000,
    "peak_qps": 2000
  }
}

Response:
{
  "code": "SUCCESS",
  "data": {
    "platform_id": 42,
    "ma_node_code": "MA.156.10005.8362",
    "api_key": "ak_live_xxxxxx",
    "api_secret": "as_live_xxxxxx",
    "status": "pending_activation",
    "activation_url": "https://aigc-hub.cn/activate/xxx"
  }
}
```

---

## 4.5 版权链与清算接口

### 4.5.1 版权登记

```http
POST /api/v1/chain/copyright/register

Request:
{
  "avcc": "MA.156.10005.8361/10.1300200.AIGC/...",
  "content_hash": "sha256:...",
  "license_doc_hashes": ["sha256:...", "sha256:..."],
  "right_holders": [
    {"type": "creator", "address": "0xCreator...", "share": 4000},
    {"type": "model", "address": "0xModel...", "share": 1500},
    {"type": "ip", "address": "0xIP...", "share": 1000},
    {"type": "platform", "address": "0xPlatform...", "share": 3000}
  ],
  "smart_contract_params": {
    "auto_settle": true,
    "settle_cycle": "monthly",
    "min_settle_amount": 10000
  }
}

Response:
{
  "code": "SUCCESS",
  "data": {
    "tx_hash": "0xchain123...",
    "block_height": 1234567,
    "crd_address": "0x7f3e9a...",
    "status": "confirmed",
    "confirm_time": "2026-06-02T14:30:00+08:00",
    "confirmation_count": 6
  }
}
```

### 4.5.2 跨平台权益记录

```http
POST /api/v1/chain/user-rights/record

Request:
{
  "avcc": "MA.156.10005.8361/10.1300200.AIGC/...",
  "user_hash": "sha256:user001",
  "purchase_platform": "MA.156.10005.8361",
  "purchase_time": "2026-06-01T10:00:00+08:00",
  "expiry_time": "2027-06-01T10:00:00+08:00",
  "price_paid": 15.00,
  "currency": "CNY",
  "rights_type": "play",
  "order_id": "order_20260601_001"
}

Response:
{
  "code": "SUCCESS",
  "data": {
    "tx_hash": "0xrights456...",
    "status": "confirmed",
    "rights_id": "ur_20260601_001"
  }
}
```

### 4.5.3 跨平台权益验证

```http
POST /api/v1/chain/user-rights/verify

Request:
{
  "avcc": "MA.156.10005.8361/10.1300200.AIGC/...",
  "user_hash": "sha256:user001",
  "current_platform": "MA.156.10005.8362",
  "rights_type": "play"
}

Response:
{
  "code": "SUCCESS",
  "data": {
    "valid": true,
    "purchase_platform": "MA.156.10005.8361",
    "purchase_time": "2026-06-01T10:00:00+08:00",
    "expiry_time": "2027-06-01T10:00:00+08:00",
    "rights_type": "play",
    "remaining_plays": null,
    "transfer_count": 0
  }
}
```

### 4.5.4 查询分账记录

```http
GET /api/v1/chain/settlement/query?avcc={avcc_code}&platform_id={pid}&period_start=2026-05-01&period_end=2026-05-31

Response:
{
  "code": "SUCCESS",
  "data": {
    "total_revenue": 125000.00,
    "settlements": [
      {
        "period": "2026-05",
        "platform_id": "8361",
        "platform_name": "抖音",
        "total_revenue": 80000.00,
        "creator_share": 32000.00,
        "platform_share": 24000.00,
        "model_share": 12000.00,
        "ip_share": 8000.00,
        "hub_fee": 4800.00,
        "status": "settled",
        "tx_hash": "0xsettle001...",
        "settled_at": "2026-06-05T10:00:00+08:00"
      }
    ],
    "summary": {
      "total_settled": 1,
      "total_pending": 0,
      "total_disputed": 0,
      "total_amount": 125000.00
    }
  }
}
```

---

## 4.6 数据回传接口（平台 → 广电云）

### 4.6.1 播放数据回传

```http
POST /api/v1/data/playback

Request:
{
  "platform_id": "8361",
  "batch": [
    {
      "avcc": "MA.156.10005.8361/10.1300200.AIGC/...",
      "event_type": "play",
      "user_hash": "sha256:xxx",
      "event_time": "2026-06-02T14:30:00+08:00",
      "duration_sec": 1800,
      "device_type": "mobile",
      "province": "110000"
    }
  ]
}

Response:
{
  "code": "SUCCESS",
  "data": {
    "accepted": 1000,
    "rejected": 0,
    "batch_id": "pb_20260602_001"
  }
}
```

### 4.6.2 处置记录回传

```http
POST /api/v1/data/disposition

Request:
{
  "platform_id": "8361",
  "avcc": "MA.156.10005.8361/10.1300200.AIGC/...",
  "action": "removed",
  "reason": "用户投诉侵权",
  "disposition_time": "2026-06-02T14:30:00+08:00",
  "operator": "system"
}
```

---

## 4.7 监管接口（广电云 → 广电总局）

### 4.7.1 数据上报

```http
POST /api/v1/regulatory/report
Authorization: AIGHUB {regulatory_key}:{signature}

Request:
{
  "report_type": "daily_summary",
  "date": "2026-06-02",
  "data": {
    "total_registered": 1523,
    "total_reviewed": 1200,
    "level_distribution": {"P": 50, "G": 450, "O": 700},
    "platform_activity": [
      {"platform": "抖音", "new_works": 500, "removed": 12},
      {"platform": "B站", "new_works": 200, "removed": 3}
    ],
    "blacklist_updates": 2,
    "compliance_alerts": 5
  }
}
```

### 4.7.2 黑名单同步

```http
POST /api/v1/regulatory/blacklist/sync

Response:
{
  "code": "SUCCESS",
  "data": {
    "updated_at": "2026-06-02T14:30:00+08:00",
    "total_entries": 156,
    "new_entries": 3,
    "categories": {
      "creator": 45,
      "platform": 2,
      "model": 23,
      "dataset": 12,
      "content": 74
    }
  }
}
```

---

*上一章：[03-数据库与数据模型.md](03-数据库与数据模型.md)*  
*下一章：[05-部署与运维架构.md](05-部署与运维架构.md)*