Files

T

selfrelease a329d4906b init: AIGC-Hub/AVCC 方案文档 + TCS-IPTV 内容可信锁定系统 MVP

- 方案文档: AVCC 体系建设、IPTV TCS 需求(0-req)/PRD(1-prd)/任务(2-task)/二三四期任务
- tcs-iptv: Go 后端(哈希SDK/MA码生成/可信数据空间mock/业务编排/HTTP API+HMAC鉴权)
- web-console: React+AntD 监管大屏(角色工作台/全流程演示/监管片库)
- 一剧一码+集级哈希, 集级下架/恢复, 全栈测试通过

2026-06-14 16:50:31 +08:00

17 KiB

Raw Permalink Blame History

第四章 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 签名 双因素鉴权。

请求头格式：

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

签名算法示例（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

限流响应：

{
  "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 统一响应格式

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

错误响应格式：

{
  "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 提交赋码申请

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 查询赋码进度

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 证书

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）

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 预审接口（实时提交）

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 获取预审报告

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 人工审核提交（平台人工复核）

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 解析

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 有效性

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 根解析

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 平台节点注册（内部接口）

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 版权登记

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 跨平台权益记录

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 跨平台权益验证

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 查询分账记录

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 播放数据回传

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 处置记录回传

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 数据上报

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 黑名单同步

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
下一章：05-部署与运维架构.md

17 KiB Raw Permalink Blame History Unescape Escape

第四章 API 接口设计

4.1 统一接口规范

4.1.1 基础约定

4.1.2 鉴权机制

4.1.3 限流策略

4.1.4 统一响应格式

4.1.5 错误码定义

4.2 赋码服务接口

4.2.1 提交赋码申请

4.2.2 查询赋码进度

4.2.3 获取 AVCC 证书

4.2.4 批量赋码申请（MCN）

4.3 审核服务接口

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

4.3.2 获取预审报告

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

4.4 MA 编码网关接口

4.4.1 AVCC 解析

4.4.2 校验 AVCC 有效性

4.4.3 对接 MA 根解析

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

4.5 版权链与清算接口

4.5.1 版权登记

4.5.2 跨平台权益记录

4.5.3 跨平台权益验证

4.5.4 查询分账记录

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

4.6.1 播放数据回传

4.6.2 处置记录回传

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

4.7.1 数据上报

4.7.2 黑名单同步

17 KiB

Raw Permalink Blame History