> ## Documentation Index
> Fetch the complete documentation index at: https://beaver.voc.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 回复润色

> 第三方 → Shulex 的回复润色接口

# 回复润色

> 第三方 → Shulex：对一段待发送回复进行润色

当第三方已经生成或编辑了一段回复文本，希望由 Shulex AI 优化表达、语气或格式时，可调用此接口。

## 调用地址与鉴权

在 Shulex 中创建 Custom Ticket 渠道后，从渠道配置页面复制回复润色地址；请勿手动拼接 URL。

```http theme={null}
POST https://<host>/api_v2/intelli/custom-ticket/reply-rephrase/{xToken}/{channelId}
Content-Type: application/json
```

| 路径字段        | 类型     | 必填 | 说明                             |
| ----------- | ------ | -- | ------------------------------ |
| `xToken`    | string | 是  | Shulex 生成的渠道访问凭证               |
| `channelId` | number | 是  | Shulex 生成的 Custom Ticket 渠道 ID |

Shulex 会校验凭证与渠道归属同一账号，且该渠道必须为 Custom Ticket 渠道。请求体不支持覆盖 `xToken`、`channelId` 或租户 ID。

## 请求格式

```json theme={null}
{
  "text": "Sorry for the issue. We will check it.",
  "referenceText": "Customer reported that the package arrived damaged.",
  "targetLanguage": "ENGLISH",
  "contentFormat": "PLAIN"
}
```

### 请求字段

| 字段               | 类型     | 必填 | 默认值      | 说明                               |
| ---------------- | ------ | -- | -------- | -------------------------------- |
| `text`           | string | 是  | 无默认值     | 待润色文本                            |
| `referenceText`  | string | 否  | 不传时为空    | 参考上下文，例如客户最后一条消息                 |
| `targetLanguage` | string | 否  | 不传时保持原语言 | 目标语言；可写值见下方 `targetLanguage` 枚举表 |
| `contentFormat`  | string | 否  | `HTML`   | 输出格式；可写值见下方 `contentFormat` 枚举表  |

<Warning>
  `text` 不能为空。`contentFormat` 不传时按 `HTML` 处理，其他可选字段不传时由 Shulex AI 按默认策略处理。
</Warning>

### 枚举可写值

#### `targetLanguage`

| 值                     | 说明           |
| --------------------- | ------------ |
| `AUTO`                | 自动识别或按默认策略处理 |
| `ENGLISH`             | 英语           |
| `CHINESE`             | 简体中文         |
| `TRADITIONAL_CHINESE` | 繁体中文         |
| `CANTONESE`           | 粤语           |
| `JAPANESE`            | 日语           |
| `FRENCH`              | 法语           |
| `GERMAN`              | 德语           |
| `SPANISH`             | 西班牙语         |
| `ARABIC`              | 阿拉伯语         |
| `RUSSIAN`             | 俄语           |
| `PORTUGUESE`          | 葡萄牙语         |
| `ITALIAN`             | 意大利语         |
| `KOREAN`              | 韩语           |
| `DUTCH`               | 荷兰语          |
| `INDONESIAN`          | 印尼语          |
| `TURKISH`             | 土耳其语         |
| `ROMANIAN`            | 罗马尼亚语        |
| `POLISH`              | 波兰语          |
| `PHILIPPINES`         | 菲律宾语         |
| `VIETNAMESE`          | 越南语          |
| `THAI`                | 泰语           |
| `SWEDISH`             | 瑞典语          |
| `NORWEGIAN`           | 挪威语          |
| `FINNISH`             | 芬兰语          |
| `DANISH`              | 丹麦语          |
| `CZECH`               | 捷克语          |
| `SLOVAK`              | 斯洛伐克语        |
| `ESTONIAN`            | 爱沙尼亚语        |
| `LITHUANIAN`          | 立陶宛语         |
| `LATVIAN`             | 拉脱维亚语        |
| `BULGARIAN`           | 保加利亚语        |
| `HUNGARIAN`           | 匈牙利语         |
| `CROATIAN`            | 克罗地亚语        |
| `SLOVENIAN`           | 斯洛文尼亚语       |
| `BENGALI`             | 孟加拉语         |
| `HEBREW`              | 希伯来语         |
| `GREEK`               | 希腊语          |
| `HINDI`               | 印地语          |

#### `contentFormat`

| 值          | 说明          |
| ---------- | ----------- |
| `MARKDOWN` | Markdown 格式 |
| `HTML`     | HTML 格式     |
| `PLAIN`    | 纯文本格式       |

## 响应格式

成功时返回 `ResponseResult` 包装结构。`data` 中不会返回模型用量 `usages`；枚举字段统一返回字符串。

### 响应字段

| 字段                   | 类型      | 说明                                |
| -------------------- | ------- | --------------------------------- |
| `code`               | string  | 业务状态码；成功时为 `"200"`                |
| `msg`                | string  | 响应说明；成功时为 `"success"`             |
| `success`            | boolean | 是否成功                              |
| `data.content`       | string  | 润色后的回复内容                          |
| `data.language`      | string  | 输出语言，例如 `ENGLISH`、`CHINESE`       |
| `data.contentFormat` | string  | 内容格式，例如 `MARKDOWN`、`HTML`、`PLAIN` |

### 成功响应

```json theme={null}
{
  "code": "200",
  "msg": "success",
  "success": true,
  "data": {
    "content": "I'm sorry for the inconvenience. We'll look into this right away and get back to you with an update.",
    "language": "ENGLISH",
    "contentFormat": "PLAIN"
  }
}
```

<Note>
  `data.content` 为润色后的文本。接口不会返回模型用量 `usages`，也不会在响应中回传租户 ID。
</Note>

## 常见错误

| code    | 场景            | 处理建议                                            |
| ------- | ------------- | ----------------------------------------------- |
| `"400"` | `xToken` 无效   | 从渠道配置页面重新复制完整地址                                 |
| `"400"` | 渠道不存在或不属于当前账号 | 确认 `xToken` 与 `channelId` 来自同一 Custom Ticket 渠道 |
| `"400"` | `text` 为空     | 提供非空的待润色文本                                      |
| `"400"` | 目标语言或格式非法     | 检查 `targetLanguage` 与 `contentFormat` 是否为支持值    |
| `"500"` | 回复润色异常        | 保留请求时间和渠道信息并联系 Shulex 支持排查                      |

## 接入建议

* 只把待发送的回复正文放入 `text`，不要把完整工单内容混入待润色文本。
* 使用 `referenceText` 补充客户问题或摘要，帮助 AI 保持语义一致。
* 未指定 `targetLanguage` 时，由 Shulex AI 按默认策略处理输出语言。
* 不传 `contentFormat` 时按 `HTML` 处理，适合保留邮件或富文本结构。
* 对润色结果做人工确认后再发送给客户。