Pede a descrição do post a partir do Drop gravado
POST/api/ai/drop-description
- Auth
- Richiede un token
- Chiave API:
- Non accetta chiavi API
- X-CommunityId
X-CommunityIdInvia l’X-CommunityId della community in cui avviene l’operazione.
Drops + IA. Transcreve o áudio do Drop que a pessoa gravou para o post e escreve uma descrição curta (2 a 4 frases; com `kind: status`, o texto de um post curto em primeira pessoa, até 280 caracteres; com `kind: comment`, o texto curto de um comentário; com `kind: lesson`, a descrição de uma aula de curso, 1 ou 2 parágrafos sobre o que ela ensina) **no idioma da fala**, sem inventar fato, data, preço ou nome. Nada é salvo no post nem na aula: o app coloca a descrição no editor e a pessoa edita e decide se publica (na aula, em `body` do `PUT /api/courses/lesson/{lessonId}`).
**Assíncrono:** responde 202 com o pedido (`jobId`, `status: pending`); vindo do cache, já `done`. Quando a descrição fica pronta, quem pediu recebe no socket do chat o evento `ai.dropDescription.ready` com o mesmo formato de `AiDropDescriptionJob` (mais `transcript`), também quando falha (`status: failed`). Sem socket, consulte `GET /api/ai/drop-description/{jobId}` a cada poucos segundos. Um pedido sem resposta em 10 minutos falha.
Só **quem gravou** o Drop pede (nem a equipe pelo Drop de outra pessoa: 403). O `mediaId` é um vídeo já confirmado em `/api/media` da comunidade do `X-CommunityId`, com finalidade `contentVideo` (vídeo do post) ou `statusVideo` (post curto), ou, com `kind: comment`, `contentCommentVideo`/`statusCommentVideo`, ou, com `kind: lesson`, `lessonVideo` (Drop de aula); outra finalidade dá 400, outro id ou outra comunidade dá 404. Até **10 minutos** de fala: um vídeo já convertido e mais longo dá 400 aqui; os demais terminam em `failed` com `error: tooLong`. Sem fala reconhecível, `error: noSpeech`. Se o pedido não puder nem começar, 503 e nada muda.
**Gerar de novo:** chamar de novo com o mesmo `mediaId` depois de pronto reescreve a partir da transcrição já feita (sem transcrever de novo), até 5 vezes por Drop e 30 por dia por pessoa (equipe incluída); com o pedido ainda em andamento, volta o mesmo pedido. O mesmo arquivo enviado de novo pela mesma pessoa também não é transcrito de novo. A transcrição fica guardada cifrada só até o Drop entrar num post ou por 24 horas.
Limites por pessoa: até 3 pedidos em andamento e, para quem não é da equipe, 30 transcrições e 120 minutos de áudio por dia (429 com `errors[0].param = mediaId`); owner, admin e moderador não têm limite diário próprio. Limite da comunidade, para todos (equipe incluída): os minutos de áudio transcritos no mês do calendário (no fuso da comunidade) não passam do direito `ai.transcriptionMinutesPerMonth` do plano (padrão 500, o do Scale), e cada pedido (transcrição guardada incluída) conta um uso de `ai.textUsesPerMonth` (padrão 6000; o pedido em andamento já reserva o seu; um que termina sem chegar à IA de texto devolve), senão 429 com a mensagem do limite mensal. Tudo checado de forma atômica (pedidos em paralelo não passam juntos). A duração do arquivo enviado é medida antes de transcrever, pelo áudio decodificado e pelo cabeçalho: mais de 10 minutos, duração ilegível ou as duas medidas discordando dá 400; arquivo sem áudio, 422.
Mesmo freio contra abuso do `POST /api/ai/improve-text`, **somado** a ele e contado na chegada (30 por minuto, 500 por dia por pessoa): acima disso, 429 com `Retry-After`. Cada chamada a um provedor é registrada (comunidade, pessoa, segundos de áudio ou tokens, sucesso), **nunca a transcrição nem o texto**.
Header
| Nome | Tipo | Descrizione |
|---|---|---|
X-CommunityIdfacoltativo | string (uuid) | ID da comunidade em que a operação acontece. Obrigatório na maioria dos endpoints com escopo de comunidade. |
Corpo della richiesta application/json
| Nome | Tipo | Descrizione |
|---|---|---|
mediaIdobbligatorio | string (uuid) | Id do vídeo do Drop, devolvido pela confirmação do envio em `/api/media`. |
kindfacoltativo | content | status | comment | lesson | `content`: descrição de um post (2 a 4 frases, `format` vale); `status`: texto de um post curto, em primeira pessoa, até 280 caracteres, sem título; `comment`: texto curto de um comentário, em primeira pessoa, dentro do limite do comentário (280 no post curto, 2000 no post). `status` e `comment` são sempre texto simples (`title` e `format` são ignorados). `comment` exige um Drop de comentário (`contentCommentVideo` ou `statusCommentVideo`) e a comunidade com `dropsInComments` ligado (senão 403); `content` e `status` exigem um Drop de post; `lesson` (descrição da aula, 1 ou 2 parágrafos, `title` = título da aula e `format` valem) exige um Drop de aula (`lessonVideo`). |
titlefacoltativo | string | Título do post, se já houver; ajuda a dar contexto. · max 300 |
languagefacoltativo | string | Idioma esperado da fala (ISO 639-1, com ou sem região). Sem ele, o idioma é detectado. |
formatfacoltativo | html | plain | `html` para o editor de posts (parágrafos com `<p>`), `plain` para texto simples. |
Risposte
| Codice | Descrizione |
|---|---|
202 | Pedido aceito. Com a transcrição já guardada (o mesmo arquivo, ou gerar de novo) ele já volta com `status` igual a `done`. |
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 | O Drop não é de quem chama (ou o papel não permite). |
404 | Recurso não encontrado. |
429 | Freio contra abuso, somado ao de melhorar texto (com `Retry-After`), ou um limite do Drop: pedidos em andamento, transcrições do dia, minutos do mês da comunidade, ou gerar de novo (com `errors[0].param = mediaId`). |
503 | O pedido não pôde começar; nada mudou. |
Esempio con curl
curl -X POST "https://api.memberfy.net/api/ai/drop-description" \
-H "Authorization: Bearer $TOKEN" \
-H "X-CommunityId: $COMMUNITY_ID" \
-H "Content-Type: application/json" \
-d '{"mediaId":"00000000-0000-0000-0000-000000000000"}'