Zum Inhalt springen

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

POST/api/ai/drop-description

Auth
Token erforderlich
API-Schlüssel:
Kein API-Schlüssel möglich
X-CommunityId
X-CommunityId Sende die X-CommunityId der Community, in der die Operation stattfindet.
Die Beschreibungen der Endpoints stammen aus der API-Spezifikation und sind vorerst auf Portugiesisch. Die Oberfläche drumherum ist übersetzt.

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

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

Request-Body application/json

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

Antworten

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

curl-Beispiel

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