ADD_TEXT_STYLE 接口 - 创建文本富文本样式

📋 接口信息

接口地址: POST /api/drafts/add_text_style
功能描述: 为文本创建富文本样式，支持关键词高亮、颜色设置、字体大小调整等功能
版本: v1.0.0
更新时间: 2025年8月1日

🎯 功能特性

核心功能

关键词高亮: 为指定关键词设置特殊样式
多关键词支持: 使用 | 分隔符支持多个关键词
样式定制: 支持颜色、字体大小、加粗等样式设置
智能分割: 自动处理关键词前后的普通文本样式
JSON生成: 生成标准的文本样式JSON格式

高级特性

位置精确控制: 基于字符索引的精确样式定位
样式层叠: 支持复杂的文本样式组合
默认值处理: 提供合理的默认样式参数
容错处理: 智能处理关键词匹配和样式应用

📝 请求参数

请求体 (JSON)

{
  "text": "五个快乐到死的顶级思维",
  "keyword": "快乐|顶级思维",
  "font_size": 12,
  "keyword_color": "#eeeeee",
  "keyword_font_size": 14
}

参数详解

参数名	类型	必填	默认值	说明
`text`	string	✅	-	要处理的文本内容
`keyword`	string	✅	-	关键词，多个用 `\|` 分隔
`font_size`	number	否	15	普通文本的字体大小
`keyword_color`	string	否	"#ff7100"	关键词文本颜色（十六进制）
`keyword_font_size`	number	否	15	关键词字体大小

参数说明

text: 待处理的完整文本内容
keyword: 需要高亮的关键词，使用竖线 | 分隔多个关键词
font_size: 普通文本（非关键词）的字体大小
keyword_color: 关键词的显示颜色，支持十六进制颜色码
keyword_font_size: 关键词的字体大小，通常设置比普通文本大一些

📤 响应格式

成功响应 (200)

{
  "status": "success",
  "message": "文本样式生成成功",
  "data": {
    "text_style": {
      "spans": [
        {
          "start": 0,
          "end": 2,
          "color": "#ffffff",
          "font_size": 12,
          "bold": false
        },
        {
          "start": 2,
          "end": 4,
          "color": "#eeeeee",
          "font_size": 14,
          "bold": true
        },
        {
          "start": 4,
          "end": 6,
          "color": "#ffffff",
          "font_size": 12,
          "bold": false
        },
        {
          "start": 6,
          "end": 10,
          "color": "#eeeeee",
          "font_size": 14,
          "bold": true
        }
      ],
      "text": "五个快乐到死的顶级思维"
    }
  }
}

错误响应 (400)

{
  "status": "error",
  "message": "参数验证失败",
  "errors": [
    "text是必填项",
    "keyword是必填项"
  ]
}

错误响应 (500)

{
  "status": "error",
  "message": "文本样式生成失败: 详细错误信息"
}

🔧 使用示例

cURL 示例

基本用法

curl -X POST https://jy-api.fyshark.com/api/drafts/add_text_style \
  -H "Content-Type: application/json" \
  -d '{
    "text": "五个快乐到死的顶级思维",
    "keyword": "快乐|顶级思维",
    "font_size": 12,
    "keyword_color": "#eeeeee",
    "keyword_font_size": 14
  }'

单个关键词

curl -X POST https://jy-api.fyshark.com/api/drafts/add_text_style \
  -H "Content-Type: application/json" \
  -d '{
    "text": "欢迎使用JY API服务",
    "keyword": "JY API",
    "font_size": 16,
    "keyword_color": "#ff7100",
    "keyword_font_size": 20
  }'

多个关键词高亮

curl -X POST https://jy-api.fyshark.com/api/drafts/add_text_style \
  -H "Content-Type: application/json" \
  -d '{
    "text": "学习JavaScript和Python编程语言",
    "keyword": "JavaScript|Python|编程语言",
    "font_size": 14,
    "keyword_color": "#00ff00",
    "keyword_font_size": 16
  }'

使用默认参数

curl -X POST https://jy-api.fyshark.com/api/drafts/add_text_style \
  -H "Content-Type: application/json" \
  -d '{
    "text": "这是一个测试文本",
    "keyword": "测试"
  }'

JavaScript 示例

基础使用

const addTextStyle = async (textConfig) => {
  const response = await fetch('/api/drafts/add_text_style', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(textConfig)
  });
  
  const result = await response.json();
  
  if (result.status === 'success') {
    console.log('文本样式生成成功:', result.data.text_style);
    return result.data.text_style;
  } else {
    throw new Error(result.message);
  }
};

// 使用示例
const config = {
  text: "五个快乐到死的顶级思维",
  keyword: "快乐|顶级思维",
  font_size: 12,
  keyword_color: "#eeeeee",
  keyword_font_size: 14
};

addTextStyle(config)
  .then(textStyle => {
    console.log('生成的文本样式:', textStyle);
  })
  .catch(error => {
    console.error('生成失败:', error.message);
  });

高级用法 - TextStyleManager 类

class TextStyleManager {
  constructor(baseUrl = 'https://jy-api.fyshark.com') {
    this.baseUrl = baseUrl;
  }

  // 生成文本样式
  async generateTextStyle(config) {
    const response = await fetch(`${this.baseUrl}/api/drafts/add_text_style`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(config)
    });

    const result = await response.json();
    if (result.status !== 'success') {
      throw new Error(`样式生成失败: ${result.message}`);
    }

    return result.data.text_style;
  }

  // 创建标题样式
  async createTitleStyle(text, titleKeywords) {
    return this.generateTextStyle({
      text: text,
      keyword: titleKeywords,
      font_size: 18,
      keyword_color: "#ff7100",
      keyword_font_size: 24
    });
  }

  // 创建强调样式
  async createEmphasisStyle(text, emphasisWords) {
    return this.generateTextStyle({
      text: text,
      keyword: emphasisWords,
      font_size: 14,
      keyword_color: "#ff0000",
      keyword_font_size: 16
    });
  }

  // 创建品牌样式
  async createBrandStyle(text, brandNames) {
    return this.generateTextStyle({
      text: text,
      keyword: brandNames,
      font_size: 16,
      keyword_color: "#0066cc",
      keyword_font_size: 18
    });
  }

  // 批量处理多个文本
  async batchProcess(textConfigs) {
    const results = [];
    
    for (const config of textConfigs) {
      try {
        const style = await this.generateTextStyle(config);
        results.push({
          success: true,
          text: config.text,
          style: style
        });
      } catch (error) {
        results.push({
          success: false,
          text: config.text,
          error: error.message
        });
      }
    }
    
    return results;
  }
}

// 使用示例
const styleManager = new TextStyleManager();

// 创建标题样式
const titleStyle = await styleManager.createTitleStyle(
  "掌握AI工具提升工作效率",
  "AI工具|工作效率"
);

// 创建强调样式
const emphasisStyle = await styleManager.createEmphasisStyle(
  "注意：这个功能非常重要！",
  "注意|非常重要"
);

// 批量处理
const batchConfigs = [
  {
    text: "学习JavaScript编程",
    keyword: "JavaScript"
  },
  {
    text: "使用Python进行数据分析",
    keyword: "Python|数据分析"
  }
];

const batchResults = await styleManager.batchProcess(batchConfigs);
console.log('批量处理结果:', batchResults);

Python 示例

import requests
import json

def add_text_style(text_config, base_url="https://jy-api.fyshark.com"):
    """生成文本样式"""
    
    url = f"{base_url}/api/drafts/add_text_style"
    headers = {"Content-Type": "application/json"}
    
    response = requests.post(url, headers=headers, json=text_config)
    result = response.json()
    
    if result["status"] == "success":
        return result["data"]["text_style"]
    else:
        raise Exception(f"样式生成失败: {result['message']}")

# 基本使用
config = {
    "text": "五个快乐到死的顶级思维",
    "keyword": "快乐|顶级思维",
    "font_size": 12,
    "keyword_color": "#eeeeee",
    "keyword_font_size": 14
}

try:
    text_style = add_text_style(config)
    print("生成的文本样式:")
    print(json.dumps(text_style, indent=2, ensure_ascii=False))
except Exception as e:
    print(f"生成失败: {e}")

# 批量处理示例
def batch_generate_styles(text_configs):
    """批量生成文本样式"""
    results = []
    
    for config in text_configs:
        try:
            style = add_text_style(config)
            results.append({
                "success": True,
                "text": config["text"],
                "style": style
            })
        except Exception as e:
            results.append({
                "success": False,
                "text": config["text"],
                "error": str(e)
            })
    
    return results

# 批量处理使用
batch_configs = [
    {
        "text": "学习人工智能和机器学习",
        "keyword": "人工智能|机器学习",
        "keyword_color": "#0066cc"
    },
    {
        "text": "掌握前端开发技术",
        "keyword": "前端开发",
        "keyword_color": "#ff7100"
    }
]

batch_results = batch_generate_styles(batch_configs)
for result in batch_results:
    if result["success"]:
        print(f"✅ {result['text']} - 样式生成成功")
    else:
        print(f"❌ {result['text']} - {result['error']}")

📊 错误码说明

状态码	错误类型	说明	解决方案
400	参数错误	必填参数缺失	检查 text 和 keyword 参数
400	参数错误	参数格式错误	检查参数类型和格式
400	参数错误	颜色格式错误	使用正确的十六进制颜色格式
400	参数错误	字体大小无效	使用正数作为字体大小
500	服务器错误	文本样式生成失败	检查文本内容和关键词匹配
500	服务器错误	TextStyleGenerator 初始化失败	联系技术支持

⚠️ 注意事项

参数要求

text: 不能为空字符串
keyword: 不能为空字符串，多个关键词用 | 分隔
font_size: 必须为正数
keyword_font_size: 必须为正数
keyword_color: 必须为有效的十六进制颜色格式（如：#ff7100）

关键词匹配

大小写敏感: 关键词匹配区分大小写
精确匹配: 只匹配完全相同的文本
顺序处理: 关键词按在文本中出现的顺序处理
重复关键词: 同一关键词在文本中多次出现时，都会被高亮

样式应用

默认样式: 非关键词文本使用默认样式（白色，指定字体大小）
关键词样式: 关键词自动加粗并应用指定颜色和字体大小
样式继承: 样式不会重叠，每个文本区间有独立的样式
字符索引: 基于 UTF-8 字符索引进行样式定位

性能考虑

文本长度: 建议单次处理的文本长度不超过1000字符
关键词数量: 建议单次处理的关键词数量不超过10个
处理时间: 通常在50ms内完成处理
内存使用: 每个请求约占用1-5MB内存

🎨 应用场景

内容创作

文章标题: 突出关键词和品牌名
产品描述: 强调特性和优势
广告文案: 突出卖点和行动召唤

教育培训

课程标题: 突出学科和技能关键词
知识点: 强调重要概念和术语
练习题: 突出关键信息

营销推广

品牌宣传: 统一品牌色彩和字体
活动推广: 突出活动亮点和优惠
社交媒体: 创建吸引眼球的文本

用户界面

按钮文本: 突出关键操作
提示信息: 强调重要提醒
导航标签: 突出当前页面

🔄 工作流程

基本流程

1. 接收文本和关键词
   ↓
2. 解析关键词列表
   ↓
3. 初始化样式生成器
   ↓
4. 遍历查找关键词位置
   ↓
5. 应用样式到不同文本区间
   ↓
6. 生成完整样式JSON
   ↓
7. 返回样式结果

样式生成逻辑

文本: "五个快乐到死的顶级思维"
关键词: "快乐|顶级思维"

处理过程:
1. 普通文本 [0-2]: "五个" (白色, 12px)
2. 关键词 [2-4]: "快乐" (灰色, 14px, 加粗)
3. 普通文本 [4-6]: "到死" (白色, 12px)
4. 普通文本 [6-7]: "的" (白色, 12px)
5. 关键词 [7-11]: "顶级思维" (灰色, 14px, 加粗)

🔗 相关接口

文本处理系列

create_draft - 创建基础草稿
easy_create_material - 添加文本素材
add_captions - 批量添加字幕

样式增强系列

add_effects - 添加视觉特效
add_keyframes - 添加动画效果
add_sticker - 添加装饰元素

🚀 最佳实践

关键词选择

// ✅ 推荐：选择重要的核心词汇
{
  text: "学习人工智能提升工作效率",
  keyword: "人工智能|工作效率"
}

// ❌ 不推荐：选择过多无关紧要的词
{
  text: "学习人工智能提升工作效率", 
  keyword: "学习|人工|智能|提升|工作|效率"
}

颜色搭配

// ✅ 推荐：使用对比明显的颜色
{
  font_size: 14,
  keyword_color: "#ff7100", // 橙色关键词
  keyword_font_size: 16
}

// ✅ 推荐：品牌色彩统一
{
  keyword_color: "#0066cc", // 品牌蓝色
  keyword_font_size: 18
}

批量处理

// ✅ 推荐：统一样式的批量处理
const styleConfigs = [
  {
    text: "JavaScript编程入门",
    keyword: "JavaScript"
  },
  {
    text: "Python数据分析",
    keyword: "Python"
  }
].map(config => ({
  ...config,
  font_size: 16,
  keyword_color: "#ff7100",
  keyword_font_size: 20
}));

📖 版本历史

v1.0.0 (2025-08-01)
- 初始版本发布
- 支持基本的关键词高亮功能
- 支持多关键词处理
- 支持颜色和字体大小定制
- 完整的参数验证机制

接口开发: JY API Team
文档更新: 2025年8月1日
技术支持: GitHub Issues