# API 文档补充：剧本解析接口新参数 **更新日期**: 2026-02-07 **接口路径**: `POST /api/v1/screenplays/{screenplay_id}/parse` --- ## 📋 变更摘要 ### v1.2.0 (2026-02-07) ✅ **新增**：支持文件剧本（`type=FILE`）自动下载解析 ✅ **新增**：`customRequirements` 用户个性化要求 ✅ **新增**：`storyboardCount` 期望生成的分镜数量 ### 重要说明 #### 剧本内容来源（自动识别） 接口现在支持两种剧本类型，**自动识别并处理**： | 剧本类型 | `type` 值 | 内容来源 | 处理方式 | |---------|----------|---------|---------| | **文本剧本** | `TEXT` (1) | `content` 字段 | 直接使用数据库中的文本内容 | | **文件剧本** | `FILE` (2) | `file_url` 字段 | **自动从 URL 下载文件内容** | **关键特性**： - ✅ 用户**无需手动下载**文件，API 自动处理 - ✅ 支持 `.md`、`.txt` 等文本格式（需 UTF-8 编码） - ✅ 文件大小限制：**10MB** - ✅ 下载超时：**30 秒** **错误场景**： - 文件不存在（404）→ `"无法从 file_url 下载剧本内容: 文件不存在（404）"` - 文件过大 → `"无法从 file_url 下载剧本内容: 文件过大（15.5MB），最大支持 10MB"` - 文件非文本 → `"无法从 file_url 下载剧本内容: 文件编码格式不支持，请确保文件为 UTF-8 格式的文本文件"` --- ## 🔌 接口定义 ### 请求 **Method**: `POST` **Path**: `/api/v1/screenplays/{screenplay_id}/parse` **Content-Type**: `application/json` #### Path Parameters | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | `screenplay_id` | UUID | 是 | 剧本 ID | #### Request Body ```json { "customRequirements": "增加人物特写镜头，注重情感表达", "storyboardCount": 10, "model": "gpt-4", "autoCreateElements": true, "autoCreateTags": true, "autoCreateStoryboards": true, "temperature": 0.7, "maxTokens": 4000 } ``` #### Request Body Schema | 字段名 | 类型 | 必填 | 默认值 | 说明 | 验证规则 | |--------|------|------|--------|------|----------| | `customRequirements` | string | 否 | `null` | 用户个性化要求（如：增加特写镜头、强调情绪变化等） | 最大长度 500 字符 | | `storyboardCount` | integer | 否 | `10` | 期望生成的分镜数量 | 范围：3-12 | | `model` | string | 否 | `"gpt-4"` | AI 模型名称 | - | | `autoCreateElements` | boolean | 否 | `true` | 是否自动创建元素（角色/场景/道具） | - | | `autoCreateTags` | boolean | 否 | `true` | 是否自动创建标签 | - | | `autoCreateStoryboards` | boolean | 否 | `true` | 是否自动创建分镜 | - | | `temperature` | number | 否 | `0.7` | 温度参数 | 范围：0.0-2.0 | | `maxTokens` | integer | 否 | `4000` | 最大 token 数 | 范围：100-8000 | --- ### 响应 #### 成功响应 (202 Accepted) ```json { "code": 200, "message": "剧本解析任务已提交，请使用 jobId 查询任务状态", "data": { "jobId": "01937a2e-1234-7abc-9def-123456789abc", "taskId": "celery-task-id-12345", "status": "pending", "estimatedCredits": 50 } } ``` #### Response Schema | 字段名 | 类型 | 说明 | |--------|------|------| | `jobId` | string (UUID) | AI 任务 ID，用于查询任务状态 | | `taskId` | string | Celery 任务 ID | | `status` | string | 任务状态 (`pending`) | | `estimatedCredits` | integer | 预计消耗的积分 | #### 错误响应 **400 Bad Request** - 剧本内容为空或文件下载失败 ```json { "code": 400, "message": "剧本内容为空，无法解析", "data": null } ``` **400 Bad Request** - 文件剧本缺少 file_url ```json { "code": 400, "message": "文件剧本缺少 file_url，无法解析", "data": null } ``` **400 Bad Request** - 文件下载失败（404） ```json { "code": 400, "message": "无法从 file_url 下载剧本内容: 文件不存在（404）", "data": null } ``` **400 Bad Request** - 文件过大 ```json { "code": 400, "message": "无法从 file_url 下载剧本内容: 文件过大（15.50MB），最大支持 10MB", "data": null } ``` **400 Bad Request** - 文件编码错误 ```json { "code": 400, "message": "无法从 file_url 下载剧本内容: 文件编码格式不支持，请确保文件为 UTF-8 格式的文本文件", "data": null } ``` **403 Forbidden** - 无权限 ```json { "code": 403, "message": "无权操作此剧本", "data": null } ``` **404 Not Found** - 剧本不存在 ```json { "code": 404, "message": "剧本不存在", "data": null } ``` **422 Unprocessable Entity** - 参数验证失败 ```json { "code": 422, "message": "Validation error", "data": { "detail": [ { "type": "less_than_equal", "loc": ["body", "storyboardCount"], "msg": "Input should be less than or equal to 12", "input": 13 } ] } } ``` **402 Payment Required** - 积分不足 ```json { "code": 402, "message": "积分不足: 需要 50 积分，当前仅有 20 积分", "data": null } ``` --- ## 📝 OpenAPI 3.1 规范 ```yaml openapi: 3.1.0 info: title: Jointo API version: 1.0.0 description: 视频制作工作台 API paths: /api/v1/screenplays/{screenplay_id}/parse: post: summary: 解析剧本 description: | 使用 AI 解析剧本，自动提取角色、场景、道具、标签和分镜。 **支持剧本类型**： - 文本剧本（type=TEXT）：使用 content 字段 - 文件剧本（type=FILE）：自动从 file_url 下载内容（最大 10MB，超时 30s） **新功能**： - 支持个性化要求（customRequirements） - 支持定制分镜数量（storyboardCount，范围 3-12） operationId: parseScreenplay tags: - Screenplays security: - bearerAuth: [] parameters: - name: screenplay_id in: path required: true description: 剧本 ID schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object properties: customRequirements: type: string nullable: true maxLength: 500 description: 用户个性化要求（如：增加特写镜头、强调情绪变化等） example: "增加人物特写镜头，注重情感表达" storyboardCount: type: integer minimum: 3 maximum: 12 default: 10 description: 期望生成的分镜数量 example: 10 model: type: string default: "gpt-4" description: AI 模型名称 example: "gpt-4" autoCreateElements: type: boolean default: true description: 是否自动创建元素（角色/场景/道具） autoCreateTags: type: boolean default: true description: 是否自动创建标签 autoCreateStoryboards: type: boolean default: true description: 是否自动创建分镜 temperature: type: number format: float minimum: 0.0 maximum: 2.0 default: 0.7 description: 温度参数 maxTokens: type: integer minimum: 100 maximum: 8000 default: 4000 description: 最大 token 数 examples: default: summary: 默认请求 value: model: "gpt-4" withCustomRequirements: summary: 带个性化要求 value: customRequirements: "增加人物特写镜头，注重情感表达" storyboardCount: 8 model: "gpt-4" minimal: summary: 最小请求 value: storyboardCount: 3 responses: '202': description: 任务已提交 content: application/json: schema: type: object properties: code: type: integer example: 200 message: type: string example: "剧本解析任务已提交，请使用 jobId 查询任务状态" data: type: object properties: jobId: type: string format: uuid description: AI 任务 ID taskId: type: string description: Celery 任务 ID status: type: string enum: [pending] description: 任务状态 estimatedCredits: type: integer description: 预计消耗的积分 '400': description: 剧本内容为空 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '402': description: 积分不足 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: 无权限 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: 剧本不存在 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: 参数验证失败 content: application/json: schema: type: object properties: code: type: integer example: 422 message: type: string example: "Validation error" data: type: object properties: detail: type: array items: type: object properties: type: type: string loc: type: array items: oneOf: - type: string - type: integer msg: type: string input: nullable: true components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT schemas: ErrorResponse: type: object properties: code: type: integer message: type: string data: nullable: true ``` --- ## 🧪 测试用例 ### cURL 示例 #### 1. 基础调用（使用新参数） ```bash curl -X POST "https://api.jointo.ai/api/v1/screenplays/{screenplay_id}/parse" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "customRequirements": "增加人物特写镜头，注重情感表达", "storyboardCount": 10, "model": "gpt-4" }' ``` #### 2. 仅指定分镜数量 ```bash curl -X POST "https://api.jointo.ai/api/v1/screenplays/{screenplay_id}/parse" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "storyboardCount": 12, "model": "gpt-4" }' ``` #### 3. 向后兼容（旧版请求） ```bash curl -X POST "https://api.jointo.ai/api/v1/screenplays/{screenplay_id}/parse" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4", "temperature": 0.7 }' ``` --- ## 💡 使用建议 ### 1. 个性化要求示例 **动作片风格**： ```json { "customRequirements": "增加动作场景的快速剪辑，多使用广角镜头展现动作场面" } ``` **文艺片风格**： ```json { "customRequirements": "注重人物情感表达，多使用特写和中景，镜头运动要平缓" } ``` **纪录片风格**： ```json { "customRequirements": "采用真实感拍摄手法，多使用跟拍和固定镜头" } ``` ### 2. 分镜数量选择 - **3-5 个分镜**：适合简短场景（1-2 分钟） - **6-10 个分镜**：适合标准场景（3-5 分钟） - **11-12 个分镜**：适合复杂场景（5+ 分钟） --- ## 🔄 版本历史 | 版本 | 日期 | 变更说明 | |------|------|----------| | v1.2.0 | 2026-02-07 | **新增**：支持文件剧本（type=FILE）自动从 file_url 下载内容；文件大小限制 10MB；支持 .md/.txt 等 UTF-8 文本格式 | | v1.1.0 | 2026-02-07 | 新增 `customRequirements` 和 `storyboardCount` 参数 | | v1.0.0 | 2026-02-05 | 初始版本 | --- **文档维护**: AI Agent **最后更新**: 2026-02-07 (v1.2.0)