jinghui/creative_studio

Fork 0

BuildTools d0e11aef1b Init commit.

2026-01-25 19:27:44 +08:00

11 KiB

Raw Permalink Blame History

Creative Studio API 文档

概述

Creative Studio 提供 RESTful API 接口，支持项目管理、Skill 管理、记忆系统、审核系统等功能。

Base URL: http://localhost:8000/api/v1

认证方式: Bearer Token (即将支持)

数据格式: JSON

Skill 管理 API

1. 列出所有 Skills

GET /api/v1/skills

查询参数:

参数	类型	必填	说明
skill_type	string	否	筛选类型 (builtin/user)
category	string	否	筛选分类

响应示例:

[
  {
    "id": "dialogue-writer-ancient",
    "name": "古风对话大师",
    "version": "2.1.0",
    "type": "builtin",
    "category": "编剧 > 对话风格",
    "behavior_guide": "你是专业的古风剧集编剧...",
    "tags": ["古风", "对话", "编剧"],
    "created_at": "2024-01-15T10:00:00Z"
  }
]

2. 获取 Skill 详情

GET /api/v1/skills/{skill_id}

路径参数:

参数	类型	说明
skill_id	string	Skill ID

响应示例:

{
  "id": "dialogue-writer-ancient",
  "name": "古风对话大师",
  "version": "2.1.0",
  "author": "Creative Studio Platform",
  "type": "builtin",
  "behavior_guide": "你是专业的古风剧集编剧...",
  "config": {
    "preset": null,
    "parameters": {},
    "weights": null
  },
  "category": "编剧 > 对话风格",
  "tags": ["古风", "对话", "编剧"]
}

3. 创建新 Skill

POST /api/v1/skills

请求体:

{
  "id": "my-custom-skill",
  "name": "我的自定义 Skill",
  "content": "# Skill: 我的自定义 Skill\n\n## 行为指导\n你是...",
  "category": "自定义",
  "tags": ["测试"]
}

响应: 返回创建的 Skill 对象

4. 测试 Skill

POST /api/v1/skills/{skill_id}/test

请求体:

{
  "test_input": "请帮我创作一段古风对话",
  "context": {
    "scene": "御花园",
    "characters": ["李云飞", "苏婉儿"]
  },
  "temperature": 0.7
}

响应示例:

{
  "skill_id": "dialogue-writer-ancient",
  "skill_name": "古风对话大师",
  "response": "【场景】御花园，傍晚\n【人物】李云飞、苏婉儿\n\n李云飞：（拱手）苏姑娘...",
  "usage": {
    "prompt_tokens": 150,
    "completion_tokens": 300,
    "total_tokens": 450
  }
}

5. 更新 Skill

PUT /api/v1/skills/{skill_id}

请求体:

{
  "name": "更新后的名称",
  "content": "更新后的内容..."
}

6. 删除 Skill

DELETE /api/v1/skills/{skill_id}

响应: 204 No Content

7. 重新加载 Skill

POST /api/v1/skills/{skill_id}/reload

用于清除缓存并重新加载 Skill。

8. 列出所有分类

GET /api/v1/skills/categories/list

响应示例:

["编剧 > 对话风格", "审核 > 一致性", "通用"]

项目管理 API

1. 列出所有项目

GET /api/v1/projects

查询参数:

参数	类型	必填	说明
status	string	否	筛选状态
agent_id	string	否	筛选 Agent 类型

响应示例:

[
  {
    "id": "proj-123",
    "name": "我的古风剧集",
    "description": "一部古装爱情剧",
    "agent_id": "series-creation-agent",
    "status": "active",
    "created_at": "2024-01-15T10:00:00Z",
    "episode_count": 10,
    "completed_episodes": 3
  }
]

2. 创建项目

POST /api/v1/projects

请求体:

{
  "name": "我的古风剧集",
  "description": "一部古装爱情剧",
  "agent_id": "series-creation-agent",
  "global_context": {
    "world_setting": "古代架空世界...",
    "character_profiles": [...],
    "scene_settings": [...],
    "overall_outline": "..."
  }
}

3. 获取项目详情

GET /api/v1/projects/{project_id}

响应示例:

{
  "id": "proj-123",
  "name": "我的古风剧集",
  "description": "一部古装爱情剧",
  "agent_id": "series-creation-agent",
  "status": "active",
  "global_context": {...},
  "memory": {...},
  "episodes": [...]
}

4. 更新项目

PUT /api/v1/projects/{project_id}

5. 删除项目

DELETE /api/v1/projects/{project_id}

6. 执行单集创作

POST /api/v1/projects/{project_id}/execute

请求体:

{
  "episode_number": 4,
  "config": {
    "duration_minutes": 45,
    "focus_areas": ["情感发展", "剧情推进"]
  }
}

响应示例:

{
  "episode_id": "ep-proj-123-4",
  "episode_number": 4,
  "status": "in_progress",
  "stages": {
    "structure": "completed",
    "outline": "in_progress",
    "dialogue": "pending",
    "review": "pending",
    "memory": "pending"
  }
}

7. 批量执行剧集创作

POST /api/v1/projects/{project_id}/execute-batch

请求体:

{
  "start_episode": 4,
  "end_episode": 6,
  "batch_config": {
    "quality_threshold": 85,
    "max_retries": 2
  }
}

8. 获取剧集列表

GET /api/v1/projects/{project_id}/episodes

9. 获取单集详情

GET /api/v1/projects/{project_id}/episodes/{episode_number}

记忆系统 API

1. 获取项目记忆

GET /api/v1/projects/{project_id}/memory

响应示例:

{
  "eventTimeline": [...],
  "pendingThreads": [...],
  "characterStates": {...},
  "foreshadowing": [...],
  "relationships": {...}
}

2. 获取事件时间线

GET /api/v1/projects/{project_id}/memory/timeline

查询参数:

参数	类型	必填	说明
character	string	否	筛选角色
episode	int	否	筛选集数
importance	string	否	筛选重要性 (low/medium/high)

3. 获取待收线问题

GET /api/v1/projects/{project_id}/memory/threads

4. 添加待收线问题

POST /api/v1/projects/{project_id}/memory/threads

请求体:

{
  "description": "需要解释为什么主角会失去记忆",
  "importance": "high",
  "reminder_episode": 5
}

5. 更新待收线问题

PUT /api/v1/projects/{project_id}/memory/threads/{thread_id}

6. 标记问题已解决

POST /api/v1/projects/{project_id}/memory/resolve-thread

请求体:

{
  "thread_id": "thread-123",
  "resolution_episode": 5,
  "resolution_description": "在第五集中揭示..."
}

7. 获取人物状态

GET /api/v1/projects/{project_id}/memory/characters

审核系统 API

1. 获取审核配置

GET /api/v1/projects/{project_id}/review-config

响应示例:

{
  "enabled_review_skills": ["consistency_checker", "dialogue_quality_checker"],
  "overall_strictness": "medium",
  "dimension_settings": {...},
  "custom_rules": [...]
}

2. 更新审核配置

PUT /api/v1/projects/{project_id}/review-config

请求体:

{
  "enabled_review_skills": ["consistency_checker"],
  "overall_strictness": "strict",
  "dimension_settings": {
    "character_consistency": {
      "enabled": true,
      "strictness": 0.8,
      "weight": 0.5
    }
  }
}

3. 获取审核配置预设

GET /api/v1/projects/{project_id}/review-presets

4. 执行剧集审核

POST /api/v1/projects/{project_id}/episodes/{episode_number}/review

响应示例:

{
  "episode_id": "ep-proj-123-4",
  "overall_score": 85.5,
  "passed": true,
  "dimension_scores": {
    "character_consistency": 88,
    "plot_coherence": 82,
    "dialogue_quality": 90
  },
  "issues": [
    {
      "id": "issue-1",
      "type": "character_inconsistency",
      "dimension": "character_consistency",
      "severity": "medium",
      "location": {
        "episode": 4,
        "scene": 2,
        "line": 15
      },
      "description": "角色行为与设定不符",
      "suggestion": "建议修改为...",
      "auto_fix_available": true
    }
  ],
  "new_foreshadowing": [...],
  "resolved_threads": [...]
}

5. 获取可用的审核维度

GET /api/v1/review/dimensions

6. 添加自定义规则

POST /api/v1/review/custom-rules

请求体:

{
  "project_id": "proj-123",
  "rule": {
    "name": "对话自然性检查",
    "description": "检查对话是否过于生硬",
    "trigger_condition": "对话包含超过3个连续的形容词",
    "severity": "medium"
  }
}

7. 删除自定义规则

DELETE /api/v1/review/custom-rules/{rule_id}

错误处理

所有 API 在出错时返回以下格式：

{
  "detail": "错误描述信息"
}

常见 HTTP 状态码:

状态码	说明
200	成功
201	创建成功
204	成功（无内容）
400	请求参数错误
404	资源不存在
422	数据验证失败
500	服务器内部错误

使用示例

Python 示例

import requests

BASE_URL = "http://localhost:8000/api/v1"

# 列出所有 Skills
response = requests.get(f"{BASE_URL}/skills")
skills = response.json()
print(skills)

# 测试 Skill
response = requests.post(
    f"{BASE_URL}/skills/dialogue-writer-ancient/test",
    json={
        "test_input": "请帮我创作一段古风对话",
        "temperature": 0.7
    }
)
result = response.json()
print(result["response"])

# 创建项目
response = requests.post(
    f"{BASE_URL}/projects",
    json={
        "name": "我的古风剧集",
        "agent_id": "series-creation-agent",
        "global_context": {...}
    }
)
project = response.json()
print(project)

JavaScript 示例

const BASE_URL = "http://localhost:8000/api/v1";

// 列出所有 Skills
const response = await fetch(`${BASE_URL}/skills`);
const skills = await response.json();
console.log(skills);

// 测试 Skill
const result = await fetch(`${BASE_URL}/skills/dialogue-writer-ancient/test`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    test_input: "请帮我创作一段古风对话",
    temperature: 0.7
  })
});
const data = await result.json();
console.log(data.response);

// 创建项目
const project = await fetch(`${BASE_URL}/projects`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: "我的古风剧集",
    agent_id: "series-creation-agent",
    global_context: {...}
  })
});
const projectData = await project.json();
console.log(projectData);

附录

Skill 类型说明

builtin: 平台内置的 Skill，用户不可修改
user: 用户自定义的 Skill，可以编辑和删除

项目状态说明

draft: 草稿状态
active: 活跃项目
completed: 已完成
archived: 已归档

剧集状态说明

pending: 待创作
in_progress: 创作中
completed: 已完成
needs-review: 需要审核
failed: 创作失败

审核问题严重程度说明

low: 低优先级问题
medium: 中等优先级问题
high: 高优先级问题

11 KiB Raw Permalink Blame History Unescape Escape

Creative Studio API 文档

概述

目录

Skill 管理 API

1. 列出所有 Skills

2. 获取 Skill 详情

3. 创建新 Skill

4. 测试 Skill

5. 更新 Skill

6. 删除 Skill

7. 重新加载 Skill

8. 列出所有分类

项目管理 API

1. 列出所有项目

2. 创建项目

3. 获取项目详情

4. 更新项目

5. 删除项目

6. 执行单集创作

7. 批量执行剧集创作

8. 获取剧集列表

9. 获取单集详情

记忆系统 API

1. 获取项目记忆

2. 获取事件时间线

3. 获取待收线问题

4. 添加待收线问题

5. 更新待收线问题

6. 标记问题已解决

7. 获取人物状态

审核系统 API

1. 获取审核配置

2. 更新审核配置

3. 获取审核配置预设

4. 执行剧集审核

5. 获取可用的审核维度

6. 添加自定义规则

7. 删除自定义规则

错误处理

使用示例

Python 示例

JavaScript 示例

附录

Skill 类型说明

项目状态说明

剧集状态说明

审核问题严重程度说明

11 KiB

Raw Permalink Blame History