# SDG 引擎 API 规范

> 绘卷平台 SDG 数据生成引擎的 API 接口文档，覆盖场景配置、任务管理与数据导出。

---

## 概述

SDG（Synthetic Data Generation）引擎提供 RESTful API 接口，支持程序化的场景配置、批量数据生成任务管理与多格式数据导出。所有接口均通过 tRPC 协议提供类型安全的调用方式。

## 核心接口

### 场景配置

| 接口 | 方法 | 描述 |
|------|------|------|
| `scene.create` | mutation | 创建新场景配置 |
| `scene.update` | mutation | 更新场景参数 |
| `scene.get` | query | 获取场景详情 |
| `scene.list` | query | 列出用户的所有场景 |
| `scene.delete` | mutation | 删除场景配置 |

### 素材管理

| 接口 | 方法 | 描述 |
|------|------|------|
| `asset.list` | query | 列出素材库中的素材 |
| `asset.getByCategory` | query | 按分类获取素材 |
| `asset.search` | query | 搜索素材 |
| `bundle.create` | mutation | 创建素材组合 |
| `bundle.addItems` | mutation | 向组合添加素材 |

### SDG 任务

| 接口 | 方法 | 描述 |
|------|------|------|
| `sdg.createTask` | mutation | 创建 SDG 生成任务 |
| `sdg.getTaskStatus` | query | 查询任务状态 |
| `sdg.listTasks` | query | 列出所有任务 |
| `sdg.cancelTask` | mutation | 取消运行中的任务 |
| `sdg.downloadResult` | query | 下载生成结果 |

### 配置历史

| 接口 | 方法 | 描述 |
|------|------|------|
| `sceneHistory.list` | query | 列出配置历史记录 |
| `sceneHistory.save` | mutation | 保存配置到历史 |
| `sceneHistory.toggleFavorite` | mutation | 切换收藏状态 |
| `sceneHistory.delete` | mutation | 删除历史记录 |

## 认证

所有接口均需通过 OAuth 认证。使用 `protectedProcedure` 的接口要求用户登录，`publicProcedure` 的接口可匿名访问。

## 详细文档

完整的 API 规范请参考绘卷平台文档：[https://huijuan.k2sim.cn/docs/sdg-engine-api.md](https://huijuan.k2sim.cn/docs/sdg-engine-api.md)