14 KiB

Raw Permalink Blame History

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

{
  "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)

{
  "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 - 剧本内容为空或文件下载失败

{
  "code": 400,
  "message": "剧本内容为空，无法解析",
  "data": null
}

400 Bad Request - 文件剧本缺少 file_url

{
  "code": 400,
  "message": "文件剧本缺少 file_url，无法解析",
  "data": null
}

400 Bad Request - 文件下载失败（404）

{
  "code": 400,
  "message": "无法从 file_url 下载剧本内容: 文件不存在（404）",
  "data": null
}

400 Bad Request - 文件过大

{
  "code": 400,
  "message": "无法从 file_url 下载剧本内容: 文件过大（15.50MB），最大支持 10MB",
  "data": null
}

400 Bad Request - 文件编码错误

{
  "code": 400,
  "message": "无法从 file_url 下载剧本内容: 文件编码格式不支持，请确保文件为 UTF-8 格式的文本文件",
  "data": null
}

403 Forbidden - 无权限

{
  "code": 403,
  "message": "无权操作此剧本",
  "data": null
}

404 Not Found - 剧本不存在

{
  "code": 404,
  "message": "剧本不存在",
  "data": null
}

422 Unprocessable Entity - 参数验证失败

{
  "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 - 积分不足

{
  "code": 402,
  "message": "积分不足: 需要 50 积分，当前仅有 20 积分",
  "data": null
}

📝 OpenAPI 3.1 规范

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. 基础调用（使用新参数）

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. 仅指定分镜数量

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. 向后兼容（旧版请求）

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. 个性化要求示例

动作片风格：

{
  "customRequirements": "增加动作场景的快速剪辑，多使用广角镜头展现动作场面"
}

文艺片风格：

{
  "customRequirements": "注重人物情感表达，多使用特写和中景，镜头运动要平缓"
}

纪录片风格：

{
  "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)

14 KiB Raw Permalink Blame History