API atual/Referência completa/Venddor Intelligence: conversas

Voz

Pergunta à VI por áudio ou por transcrição, transcreve áudio em texto e transforma texto em áudio.

O modo de voz permite falar com a VI e ouvir a resposta. Há três rotas independentes: voice-ask (pergunta e resposta de uma vez, para o app móvel), voice/transcribe (áudio para texto) e voice/speak (texto para áudio). As duas últimas dependem do recurso enable_chat_voice_mode em Configurações e de um provedor de voz configurado na instalação.

Perguntar por voz

Recebe um texto já transcrito ou um áudio, e devolve a resposta em texto. Não usa sessão: é uma pergunta avulsa. Se transcript vier preenchido, o áudio é ignorado.

POST/api/v1/admin/intelligence/voice-askAdmin

Perguntar por voz ou transcrição

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Corpo da requisição

transcriptstring

Texto da pergunta, em multipart/form-data ou formulário. Tem prioridade sobre o áudio.

audiofile

Arquivo de áudio (até 16 MB), em português. Usado só quando não há transcript.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/voice-ask" \
  -H "Authorization: Bearer $TOKEN" \
  -F "transcript=Quanto vendi hoje?"

Resposta

200Resposta

json

{
  "transcript": "Quanto vendi hoje?",
  "answer": "Hoje você vendeu R$ 3.480,00 em 12 pedidos."
}

Campos da resposta

transcriptstring

A pergunta usada (a recebida ou a transcrita).

answerstring

Resposta em texto.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}`
400	Nem `transcript` nem áudio utilizável.	`{"error":"no transcript or audio provided","detail":""}`
503	A inteligência não está configurada.	`{"error":"intelligence not configured","detail":""}`
500	Falha ao responder.	`{"error":"failed to answer","detail":"..."}`

Transcrever áudio

Converte um áudio curto em texto. O arquivo vai no campo audio de um multipart/form-data.

POST/api/v1/admin/intelligence/voice/transcribeAdmin

Transcrever áudio

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Corpo da requisição

audiofileobrigatório

Áudio, no máximo 5 MB.

mime_typestring

Tipo do áudio, se o arquivo não declarar um Content-Type.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/voice/transcribe" \
  -H "Authorization: Bearer $TOKEN" \
  -F "audio=@tabela-de-precos.pdf"

Resposta

200Texto

json

{ "text": "quanto eu vendi hoje" }

Campos da resposta

textstring

Transcrição.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}`
400	Não é multipart, falta `audio` ou o áudio é vazio.	`{"error":"audio field missing"}`
403	Modo de voz desligado.	`{"error":"voice mode is disabled..."}`
413	Áudio acima de 5 MB.	`{"error":"..."}`
503	Sem provedor de voz.	`{"error":"voice provider not configured"}`

Transformar texto em áudio

Gera a fala de um texto e devolve os bytes do áudio.

POST/api/v1/admin/intelligence/voice/speakAdmin

Transformar texto em áudio

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Content-Typestringobrigatório

application/json.

Corpo da requisição

textstringobrigatório

Texto a falar.

voicestring

Nome da voz, quando o provedor oferece mais de uma.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/voice/speak" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hoje você vendeu doze pedidos."
  }'

Resposta

200Áudio

text

Content-Type: audio/mpeg
Cache-Control: no-store

(bytes do áudio)

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}`
400	`text` vazio.	`{"error":"text required"}`
403	Modo de voz desligado.	`{"error":"voice mode is disabled..."}`
503	Sem provedor de voz.	`{"error":"voice provider not configured"}`

Veja também

API atual/Referência completa/Venddor Intelligence: conversas

Voz

Pergunta à VI por áudio ou por transcrição, transcreve áudio em texto e transforma texto em áudio.

Perguntar por voz

Recebe um texto já transcrito ou um áudio, e devolve a resposta em texto. Não usa sessão: é uma pergunta avulsa. Se transcript vier preenchido, o áudio é ignorado.

POST/api/v1/admin/intelligence/voice-askAdmin

Perguntar por voz ou transcrição

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Corpo da requisição

transcriptstring

Texto da pergunta, em multipart/form-data ou formulário. Tem prioridade sobre o áudio.

audiofile

Arquivo de áudio (até 16 MB), em português. Usado só quando não há transcript.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/voice-ask" \
  -H "Authorization: Bearer $TOKEN" \
  -F "transcript=Quanto vendi hoje?"

Resposta

200Resposta

json

{
  "transcript": "Quanto vendi hoje?",
  "answer": "Hoje você vendeu R$ 3.480,00 em 12 pedidos."
}

Campos da resposta

transcriptstring

A pergunta usada (a recebida ou a transcrita).

answerstring

Resposta em texto.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}`
400	Nem `transcript` nem áudio utilizável.	`{"error":"no transcript or audio provided","detail":""}`
503	A inteligência não está configurada.	`{"error":"intelligence not configured","detail":""}`
500	Falha ao responder.	`{"error":"failed to answer","detail":"..."}`

Transcrever áudio

Converte um áudio curto em texto. O arquivo vai no campo audio de um multipart/form-data.

POST/api/v1/admin/intelligence/voice/transcribeAdmin

Transcrever áudio

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Corpo da requisição

audiofileobrigatório

Áudio, no máximo 5 MB.

mime_typestring

Tipo do áudio, se o arquivo não declarar um Content-Type.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/voice/transcribe" \
  -H "Authorization: Bearer $TOKEN" \
  -F "audio=@tabela-de-precos.pdf"

Resposta

200Texto

json

{ "text": "quanto eu vendi hoje" }

Campos da resposta

textstring

Transcrição.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}`
400	Não é multipart, falta `audio` ou o áudio é vazio.	`{"error":"audio field missing"}`
403	Modo de voz desligado.	`{"error":"voice mode is disabled..."}`
413	Áudio acima de 5 MB.	`{"error":"..."}`
503	Sem provedor de voz.	`{"error":"voice provider not configured"}`

Transformar texto em áudio

Gera a fala de um texto e devolve os bytes do áudio.

POST/api/v1/admin/intelligence/voice/speakAdmin

Transformar texto em áudio

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Content-Typestringobrigatório

application/json.

Corpo da requisição

textstringobrigatório

Texto a falar.

voicestring

Nome da voz, quando o provedor oferece mais de uma.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/voice/speak" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hoje você vendeu doze pedidos."
  }'

Resposta

200Áudio

text

Content-Type: audio/mpeg
Cache-Control: no-store

(bytes do áudio)

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}`
400	`text` vazio.	`{"error":"text required"}`
403	Modo de voz desligado.	`{"error":"voice mode is disabled..."}`
503	Sem provedor de voz.	`{"error":"voice provider not configured"}`