Melhora um texto com IA
POST/api/ai/improve-text
- Auth
- Exige token
- Quem pode:
- owner
- admin
- moderator
- finance
- Chave de API:
- Não aceita chave de API
- X-CommunityId
X-CommunityIdEnvie o X-CommunityId da comunidade em que a operação acontece.
"Melhorar com IA". Devolve o texto reescrito, mais claro e corrigido, no **mesmo formato** (`html` continua HTML válido para o editor, já sanitizado; `markdown` e `plain` voltam no mesmo formato) e no **mesmo idioma** do original, sem inventar fato, data, preço ou nome. Nada é salvo: o app mostra o antes e o depois e só troca o campo se a pessoa aceitar.
Qualquer papel da comunidade do `X-CommunityId` (member, moderador, financeiro, admin, owner). Freio contra abuso: até 30 pedidos por minuto e 500 por dia por pessoa (somando todas as comunidades dela); acima disso, 429 com `Retry-After` e `errors`. Cota da comunidade, para todos (equipe incluída): os usos de IA para texto no mês do calendário (no fuso da comunidade; este endpoint em qualquer campo, aulas incluídas, mais as descrições de Drop) não passam do direito `ai.textUsesPerMonth` do plano (padrão 6000, o do Scale), senão 429 sem `Retry-After`, com a mensagem do limite mensal. Checado e reservado de forma atômica antes de chamar a IA. Conta toda chamada que chegou à IA, mesmo a que voltou 503 (recusa, resposta vazia, tempo esgotado); só devolve o uso a que nem chegou a ela (falha de conexão, chave ausente, IA ocupada). O consumo do mês aparece em `GET /api/entitlements/community` (`ai.textUses`). Cada chamada é registrada (comunidade, pessoa, tipo do campo, sucesso), **nunca o texto nem a instrução**. Até 20.000 caracteres em `text` (400 com `errors` acima disso ou com o texto vazio) e até 500 em `instruction`. Se a IA não responder (tempo esgotado, erro), 503 com `errors` e o texto original fica como estava.
Headers
| Nome | Tipo | Descrição |
|---|---|---|
X-CommunityIdopcional | string (uuid) | ID da comunidade em que a operação acontece. Obrigatório na maioria dos endpoints com escopo de comunidade. |
Corpo da requisição application/json
| Nome | Tipo | Descrição |
|---|---|---|
textobrigatório | string | O texto do campo, no formato indicado em `format`. · max 20000 |
fieldKindobrigatório | post | event | product | course | lesson | call | proposal | campaign | feedback | recognition | classified | download | survey | other | Onde a pessoa está escrevendo; ajusta o tom da reescrita. |
formatobrigatório | html | markdown | plain | Formato do texto; a resposta vem no mesmo. |
instructionopcional | string | Pedido opcional de estilo ("mais curto", "mais formal"). · max 500 |
Respostas
| Código | Descrição |
|---|---|
200 | Texto melhorado. |
400 | Requisição inválida — falha de validação. |
401 | Token ausente, inválido ou expirado; token de outra comunidade (o `X-CommunityId` ou o `communityId` do corpo não é o do token); token antigo ou de uma sessão encerrada (troca de senha, convite aceito). Nesses casos a mensagem pede para entrar de novo (`auth.signInAgain`). |
403 | Autenticado, mas sem permissão para esta operação. |
429 | Freio contra abuso (30 por minuto ou 500 por dia por pessoa; o cabeçalho `Retry-After` diz em quantos segundos tentar de novo) ou cota mensal `ai.textUsesPerMonth` da comunidade esgotada (sem `Retry-After`; volta no mês seguinte). |
503 | A IA não respondeu agora; nada mudou. |
Exemplo com curl
curl -X POST "https://api.memberfy.net/api/ai/improve-text" \
-H "Authorization: Bearer $TOKEN" \
-H "X-CommunityId: $COMMUNITY_ID" \
-H "Content-Type: application/json" \
-d '{"text":"string","fieldKind":"post","format":"html"}'