API atual/Referência completa/Venddor Intelligence

Voz

Transcreve áudio em texto, transforma texto em áudio e libera a conversa por voz em tempo real.

O modo de voz permite falar com a VI e ouvir a resposta. Há duas formas. A primeira usa duas rotas simples: voice/transcribe (áudio para texto) e voice/speak (texto para áudio), que dependem do recurso enable_chat_voice_mode (veja Ferramentas e configurações) e de um provedor de voz na instalação. A segunda é a conversa em tempo real, em que o navegador fala direto com o provedor de voz usando a credencial de realtime/token e avisa o tempo gasto em realtime/usage.

Transcrever áudio

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

POST/api/v1/vendor/intelligence/voice/transcribeSeller

Transcrever áudio

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um seller (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/vendor/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 token não é de um usuário seller (por exemplo, é de um administrador da loja).	`{"error":"insufficient permissions"}`
403	Voz desligada na loja (`enable_chat_voice_mode`).	`{"error":"voice mode is disabled \u2014 toggle enable_chat_voice_mode in /admin/intelligence/settings"}` (a mensagem cita uma tela do administrador; o seller não altera esse recurso)
400	Não é multipart, falta `audio` ou o áudio é vazio.	`{"error":"audio field missing"}`
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/vendor/intelligence/voice/speakSeller

Transformar texto em áudio

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um seller (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/vendor/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)

O Content-Type do áudio depende do provedor de voz da instalação (audio/mpeg e audio/wav são possíveis). Leia sempre o cabeçalho da resposta em vez de assumir um formato.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é de um administrador da loja).	`{"error":"insufficient permissions"}`
403	Voz desligada na loja (`enable_chat_voice_mode`).	`{"error":"voice mode is disabled \u2014 toggle enable_chat_voice_mode in /admin/intelligence/settings"}` (a mensagem cita uma tela do administrador; o seller não altera esse recurso)
400	`text` vazio ou corpo que não é JSON.	`{"error":"text required"}` ou `{"error":"invalid request body"}`
503	Sem provedor de voz.	`{"error":"voice provider not configured"}`

Credencial de voz em tempo real

Para uma conversa por voz fluida, o navegador fala direto com o provedor de voz, sem passar os áudios pelo servidor da Venddor. Esta rota entrega a credencial temporária para isso e as configurações da sessão de voz. Cada chamada conta como uma sessão na cota semanal de voz da loja.

POST/api/v1/vendor/intelligence/realtime/tokenSeller

Obter a credencial de voz em tempo real

Cabeçalhos

Authorizationstringobrigatório

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

Content-Typestringobrigatório

application/json.

Corpo da requisição

surfacestring

De onde o seller fala (por exemplo lateral). Ajusta a abertura da conversa. O corpo inteiro é opcional e limitado a 8 KB.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/intelligence/realtime/token" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "surface": "lateral"
}'

Resposta

200Credencial emitida

json

{
  "value": "ek_example_0000000000",
  "expires_at": 1791737000,
  "model": "realtime-model-id",
  "session": {
    "type": "realtime"
  },
  "vad_threshold_speak": 0.75,
  "vad_threshold_base": 0.5,
  "max_session_seconds": 600,
  "tool_name": "venddor_intelligence"
}

Campos da resposta

valuestring

Credencial temporária do provedor de voz. Use no navegador para abrir a sessão e não a guarde nem a registre em logs.

expires_atany

Validade da credencial, no formato que o provedor devolve (em geral um número Unix). Trate como opaco e abra a sessão logo.

modelstring

Identificador do modelo de voz da sessão. Opaco: passe ao provedor como veio.

sessionobject

Configuração da sessão de voz, para aplicar sem alterações assim que a conexão abrir. O conteúdo não faz parte do contrato.

vad_threshold_speaknumber

Sensibilidade de detecção de fala enquanto a assistente está falando (0 a 1). Valor atual: 0.75.

vad_threshold_basenumber

Sensibilidade de detecção de fala nos demais momentos (0 a 1). Valor atual: 0.5.

max_session_secondsinteger

Teto desta conversa, em segundos: o menor entre o limite por sessão da loja (padrão 600) e o que sobrou da cota semanal.

tool_namestring

Nome da única função que a sessão de voz pode chamar para consultar a VI (venddor_intelligence).

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é de um administrador da loja).	`{"error":"insufficient permissions"}`
403	A conversa por voz está desligada para a loja. A decisão é do operador da Venddor, não do seller.	`{"error":"a conversa por voz está desligada para esta loja \u2014 ligue em /admin/io/storefronts/{id}, no bloco da voz"}` (em português)
429	A cota semanal de voz da loja acabou.	`{"error":"cota semanal de voz atingida","reason":"a loja já usou 120 de 120 minutos de voz nesta semana"}` (em português)
503	A voz em tempo real não está configurada na instalação.	`{"error":"voz em tempo real não configurada nesta instalação"}`
502	O provedor de voz não respondeu, recusou ou devolveu uma credencial vazia.	`{"error":"o provedor de voz recusou a credencial"}` (em português)

Registrar o tempo de voz usado

Enquanto a conversa por voz acontece, o navegador avisa quantos segundos foram consumidos. Sem esse aviso uma aba fechada no meio da conversa não pagaria nada da cota. Mande a cada minuto e uma última vez ao encerrar.

POST/api/v1/vendor/intelligence/realtime/usageSeller

Registrar o tempo de voz usado

Cabeçalhos

Authorizationstringobrigatório

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

Content-Typestringobrigatório

application/json.

Corpo da requisição

secondsintegerobrigatório

Segundos consumidos desde o último aviso. Negativo vira 0 e o valor é cortado em 3600 por chamada.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/intelligence/realtime/usage" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "seconds": 60
}'

Resposta

200Registrado

json

{
  "ok": true
}

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é de um administrador da loja).	`{"error":"insufficient permissions"}`
400	Corpo que não é JSON.	`{"error":"corpo inválido"}` (em português)

Veja também

API atual/Referência completa/Venddor Intelligence

Voz

Transcreve áudio em texto, transforma texto em áudio e libera a conversa por voz em tempo real.

Transcrever áudio

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

POST/api/v1/vendor/intelligence/voice/transcribeSeller

Transcrever áudio

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um seller (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/vendor/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 token não é de um usuário seller (por exemplo, é de um administrador da loja).	`{"error":"insufficient permissions"}`
403	Voz desligada na loja (`enable_chat_voice_mode`).	`{"error":"voice mode is disabled \u2014 toggle enable_chat_voice_mode in /admin/intelligence/settings"}` (a mensagem cita uma tela do administrador; o seller não altera esse recurso)
400	Não é multipart, falta `audio` ou o áudio é vazio.	`{"error":"audio field missing"}`
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/vendor/intelligence/voice/speakSeller

Transformar texto em áudio

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um seller (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/vendor/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)

O Content-Type do áudio depende do provedor de voz da instalação (audio/mpeg e audio/wav são possíveis). Leia sempre o cabeçalho da resposta em vez de assumir um formato.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é de um administrador da loja).	`{"error":"insufficient permissions"}`
403	Voz desligada na loja (`enable_chat_voice_mode`).	`{"error":"voice mode is disabled \u2014 toggle enable_chat_voice_mode in /admin/intelligence/settings"}` (a mensagem cita uma tela do administrador; o seller não altera esse recurso)
400	`text` vazio ou corpo que não é JSON.	`{"error":"text required"}` ou `{"error":"invalid request body"}`
503	Sem provedor de voz.	`{"error":"voice provider not configured"}`

Credencial de voz em tempo real

POST/api/v1/vendor/intelligence/realtime/tokenSeller

Obter a credencial de voz em tempo real

Cabeçalhos

Authorizationstringobrigatório

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

Content-Typestringobrigatório

application/json.

Corpo da requisição

surfacestring

De onde o seller fala (por exemplo lateral). Ajusta a abertura da conversa. O corpo inteiro é opcional e limitado a 8 KB.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/intelligence/realtime/token" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "surface": "lateral"
}'

Resposta

200Credencial emitida

json

{
  "value": "ek_example_0000000000",
  "expires_at": 1791737000,
  "model": "realtime-model-id",
  "session": {
    "type": "realtime"
  },
  "vad_threshold_speak": 0.75,
  "vad_threshold_base": 0.5,
  "max_session_seconds": 600,
  "tool_name": "venddor_intelligence"
}

Campos da resposta

valuestring

Credencial temporária do provedor de voz. Use no navegador para abrir a sessão e não a guarde nem a registre em logs.

expires_atany

Validade da credencial, no formato que o provedor devolve (em geral um número Unix). Trate como opaco e abra a sessão logo.

modelstring

Identificador do modelo de voz da sessão. Opaco: passe ao provedor como veio.

sessionobject

Configuração da sessão de voz, para aplicar sem alterações assim que a conexão abrir. O conteúdo não faz parte do contrato.

vad_threshold_speaknumber

Sensibilidade de detecção de fala enquanto a assistente está falando (0 a 1). Valor atual: 0.75.

vad_threshold_basenumber

Sensibilidade de detecção de fala nos demais momentos (0 a 1). Valor atual: 0.5.

max_session_secondsinteger

Teto desta conversa, em segundos: o menor entre o limite por sessão da loja (padrão 600) e o que sobrou da cota semanal.

tool_namestring

Nome da única função que a sessão de voz pode chamar para consultar a VI (venddor_intelligence).

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é de um administrador da loja).	`{"error":"insufficient permissions"}`
403	A conversa por voz está desligada para a loja. A decisão é do operador da Venddor, não do seller.	`{"error":"a conversa por voz está desligada para esta loja \u2014 ligue em /admin/io/storefronts/{id}, no bloco da voz"}` (em português)
429	A cota semanal de voz da loja acabou.	`{"error":"cota semanal de voz atingida","reason":"a loja já usou 120 de 120 minutos de voz nesta semana"}` (em português)
503	A voz em tempo real não está configurada na instalação.	`{"error":"voz em tempo real não configurada nesta instalação"}`
502	O provedor de voz não respondeu, recusou ou devolveu uma credencial vazia.	`{"error":"o provedor de voz recusou a credencial"}` (em português)

Registrar o tempo de voz usado

POST/api/v1/vendor/intelligence/realtime/usageSeller

Registrar o tempo de voz usado

Cabeçalhos

Authorizationstringobrigatório

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

Content-Typestringobrigatório

application/json.

Corpo da requisição

secondsintegerobrigatório

Segundos consumidos desde o último aviso. Negativo vira 0 e o valor é cortado em 3600 por chamada.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/intelligence/realtime/usage" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "seconds": 60
}'

Resposta

200Registrado

json

{
  "ok": true
}

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é de um administrador da loja).	`{"error":"insufficient permissions"}`
400	Corpo que não é JSON.	`{"error":"corpo inválido"}` (em português)