Saltar al contenido

Pede a descrição do post a partir do Drop gravado

POST/api/ai/drop-description

Auth
Requiere token
Clave de API:
No acepta clave de API
X-CommunityId
X-CommunityId Envía el X-CommunityId de la comunidad en la que ocurre la operación.
Las descripciones de los endpoints vienen de la especificación de la API y, por ahora, están en portugués. La interfaz alrededor está traducida.

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**.

Headers

NombreTipoDescripción
X-CommunityIdopcionalstring (uuid)ID da comunidade em que a operação acontece. Obrigatório na maioria dos endpoints com escopo de comunidade.

Cuerpo de la solicitud application/json

NombreTipoDescripción
mediaIdobligatoriostring (uuid)Id do vídeo do Drop, devolvido pela confirmação do envio em `/api/media`.
kindopcionalcontent | 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`).
titleopcionalstringTítulo do post, se já houver; ajuda a dar contexto. · max 300
languageopcionalstringIdioma esperado da fala (ISO 639-1, com ou sem região). Sem ele, o idioma é detectado.
formatopcionalhtml | plain`html` para o editor de posts (parágrafos com `<p>`), `plain` para texto simples.

Respuestas

CódigoDescripción
202Pedido aceito. Com a transcrição já guardada (o mesmo arquivo, ou gerar de novo) ele já volta com `status` igual a `done`.
400Requisição inválida — falha de validação.
401Token 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`).
403O Drop não é de quem chama (ou o papel não permite).
404Recurso não encontrado.
429Freio 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`).
503O pedido não pôde começar; nada mudou.

Ejemplo 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"}'