Text Variation

1. 概述

TextVariation API 用于在保留原文整体语境的前提下生成多个文本变体。根据客户启用的配置，服务可以使用人工智能、同义词及其他由 Witime 管理的处理策略。

本文档说明公开端点、请求参数及集成示例。文中的所有值均为虚构示例。

2. API 端点

POST <BASE_URL>/witime/chatbot/textvariation.aspx?chave=<ACCESS_KEY>

生产环境地址示例：

https://sms.witi.me/witime/chatbot/textvariation.aspx?chave=<ACCESS_KEY>

最终 URL、访问密钥、企业标识和配置名称由 Witime 提供。

请求头

请求头	值
`Content-Type`	`application/json; charset=utf-8`
`Accept`	`application/json`

身份验证

身份验证使用查询参数 chave。

除本地开发环境外，请始终使用 HTTPS。
不要将访问密钥直接写入源代码。
应使用环境变量或密钥保管库保存密钥。
不要在工单、截图或日志中共享包含完整密钥的 URL。
响应中 Resultado.Chave 是请求关联标识，不是身份验证密钥。

3. 请求正文

{
  "Configuracao": "gpt-sinonimos-rcs",
  "Texto": "优惠现已开放！请查看相关条件并了解详情：https://example.com/offer",
  "NumeroVariacoes": 3,
  "MaxTextLength": 155,
  "RemoveAcentos": false,
  "RemoveUnicode": false,
  "IdEmpresa": 12345
}

12345、example.com 和消息内容仅用于演示。

字段说明

字段	类型	是否必填	说明
`Configuracao`	string	是	Witime 为客户启用的准确配置名称，例如 `gpt-sinonimos-rcs`。
`Texto`	string	是	需要生成变体的原始文本，不可为空。
`NumeroVariacoes`	integer	是	请求的最终文本变体数量。应使用合同限制范围内的正整数。
`MaxTextLength`	integer	建议填写	每个文本的期望最大长度。若值小于 `1`，服务将使用 `160`。
`RemoveAcentos`	boolean	否	为 `true` 时移除变音符号。默认值：`true`。
`RemoveUnicode`	boolean	否	为 `true` 时移除不支持的 Unicode 字符，并同时强制移除变音符号。默认值：`true`。如需保留表情符号或中文字符，请使用 `false`。
`IdEmpresa`	integer	是	Witime 提供的企业标识。

处理说明

服务会在生成变体时保护链接，并在输出前恢复链接。
输出应包含完整的原始链接；客户端仍应在发送消息前自行验证。
服务可能从缓存中复用之前生成的变体。
无效、重复或不符合规则的候选文本可能被丢弃。
使用生成内容前，客户端必须复核价格、日期、商业条件、法律声明及退订说明等重要信息。

4. cURL 示例

请将敏感值保存在命令之外，并替换示例值：

export WITIME_BASE_URL="https://sms.witi.me"
export WITIME_API_KEY="your-key-provided-by-witime"

curl --request POST \
  "${WITIME_BASE_URL}/witime/chatbot/textvariation.aspx?chave=${WITIME_API_KEY}" \
  --header "Content-Type: application/json; charset=utf-8" \
  --header "Accept: application/json" \
  --data '{
	"Configuracao": "gpt-sinonimos-rcs",
	"Texto": "优惠现已开放！请查看相关条件并了解详情：https://example.com/offer",
	"NumeroVariacoes": 3,
	"MaxTextLength": 155,
	"RemoveAcentos": false,
	"RemoveUnicode": false,
	"IdEmpresa": 12345
  }'

5. PowerShell 示例

$baseUrl = $env:WITIME_BASE_URL
$apiKey = [Uri]::EscapeDataString($env:WITIME_API_KEY)
$uri = "$baseUrl/witime/chatbot/textvariation.aspx?chave=$apiKey"

$body = @{
	Configuracao = "gpt-sinonimos-rcs"
	Texto = "优惠现已开放！请查看相关条件并了解详情：https://example.com/offer"
	NumeroVariacoes = 3
	MaxTextLength = 155
	RemoveAcentos = $false
	RemoveUnicode = $false
	IdEmpresa = 12345
} | ConvertTo-Json

$response = Invoke-RestMethod `
	-Method Post `
	-Uri $uri `
	-ContentType "application/json; charset=utf-8" `
	-Headers @{ Accept = "application/json" } `
	-Body $body

if ($response.Resultado.CodigoResultado -ne 0) {
	throw "TextVariation 请求失败：$($response.Resultado.Mensagem)"
}

$response.Variacoes | ForEach-Object { $_.Texto }

6. 成功响应

{
  "Variacoes": [
	{
	  "Texto": "优惠现已开放！查看条件并了解详情：https://example.com/offer",
	  "Toxidades": 0
	},
	{
	  "Texto": "查看优惠及相关条件：https://example.com/offer",
	  "Toxidades": 0
	},
	{
	  "Texto": "了解优惠详情和适用条件：https://example.com/offer",
	  "Toxidades": 0
	}
  ],
  "Resultado": {
	"CodigoResultado": 0,
	"Mensagem": "3 textos gerados com sucesso",
	"Chave": "00000000-0000-0000-0000-000000000000",
	"Cobrado": true,
	"ValorCobrado": 3.0,
	"ElapsedTimeMS": 2500
  }
}

以上响应仅为示例。每次请求返回的文本、数量、标识和处理时间都可能不同。

响应字段

字段	类型	说明
`Variacoes`	array	返回的文本变体列表。
`Variacoes[].Texto`	string	最终文本变体。
`Variacoes[].Score`	string 或 null	内容分类结果（如果可用），该字段可能不返回。
`Variacoes[].Toxidades`	integer	与文本变体关联的毒性指标。`Toxidades` 是接口规定的准确字段名。
`Resultado.CodigoResultado`	integer	`0` 表示成功；其他值表示业务或处理错误。
`Resultado.Mensagem`	string	可读的结果说明，当前可能以葡萄牙语返回。
`Resultado.Chave`	UUID	响应关联标识，不是访问密钥。
`Resultado.Cobrado`	boolean	表示是否已记录消费。
`Resultado.ValorCobrado`	decimal	服务记录的消费值。具体单位以商业合同为准，该值可能与 `Variacoes` 的数量不同。
`Resultado.ElapsedTimeMS`	integer	服务端处理耗时，单位为毫秒。

必须检查 Resultado.CodigoResultado 来判断请求是否成功，不应只依赖 HTTP 状态码或 Mensagem 文本。

7. 已知结果代码

代码	含义
`0`	处理成功完成。
`1`	缺少访问密钥，或配置不存在/无效；具体以返回消息为准。
`2`	请求正文为空。
`3`	JSON 无效。
`4`	文本经过验证后为空。
`5`	余额不足，无法生成文本变体。

访问密钥验证和内部组件也可能返回其他代码。请求技术支持时可记录 CodigoResultado、Mensagem 和 Chave，但不要记录访问密钥或敏感内容。

错误响应示例

{
  "Variacoes": [],
  "Resultado": {
	"CodigoResultado": 5,
	"Mensagem": "Saldo insuficiente para gerar variações de texto.",
	"Chave": "00000000-0000-0000-0000-000000000000",
	"Cobrado": false,
	"ValorCobrado": 0.0,
	"ElapsedTimeMS": 20
  }
}

8. 集成建议

配置适合 AI 处理的 HTTP 超时时间；请求可能需要数秒。
以实际返回的列表长度作为有效结果数量。
不要无条件自动重试：即使客户端未收到响应，请求仍可能已记录消费。目前没有文档保证幂等性。
对瞬时故障仅进行少量指数退避重试，并在可用时保留关联标识 Chave。
对每个变体验证长度、链接、退订说明、必填信息及业务规则。
未获得合法依据、合同授权和适当保护措施时，不要发送个人或机密数据。
必须保留 JSON 字段的准确拼写，包括 Configuracao、NumeroVariacoes、IdEmpresa 和 Toxidades。

9. 验收检查表

已通过安全渠道获取生产环境 URL。
访问密钥已保存在密钥保管库或环境变量中。
已向 Witime 确认 IdEmpresa 和 Configuracao。
已配置超时和错误处理。
每次响应均检查 CodigoResultado。
已将输出链接与原文链接进行比较。
客户端已验证字符长度限制。
发送前已审核内容和退订说明。
日志不包含凭据、个人数据或完整消息正文。

10. 技术支持所需信息

请求技术支持时，仅提供：

请求日期和时间，包括时区；
环境名称；
Resultado.CodigoResultado；
Resultado.Mensagem；
Resultado.Chave；
经授权后提供 IdEmpresa；
尽可能不包含完整原文的技术参数。

切勿发送完整访问密钥。同时应遮盖个人数据、私有链接和机密内容。

1. 概述​

2. API 端点​

请求头​

身份验证​

3. 请求正文​

字段说明​

处理说明​

4. cURL 示例​

5. PowerShell 示例​

6. 成功响应​

响应字段​

7. 已知结果代码​

错误响应示例​

8. 集成建议​

9. 验收检查表​

10. 技术支持所需信息​