Skip to main content

Gerenciamento de Arquivos

Esta página documenta como fazer upload e download de arquivos para uso nas conversas com agentes.

Upload File​

Faz upload de um arquivo para ser usado em mensagens ou retorna um ID para um arquivo externo via URL.

Endpoint​

POST https://api.tech4.ai/agent/v2/files/upload

Headers​

x-client-key: YOUR_API_KEY
Content-Type: application/json  OU  multipart/form-data

Formatos Aceitos​

A API aceita dois formatos de requisição:

  1. application/json - Para enviar URL de arquivo externo
  2. multipart/form-data - Para enviar arquivo diretamente (bytes)

Opção 1: Upload via JSON (URL)​

Use este método quando o arquivo já estiver hospedado em algum lugar acessível.

Parâmetros​

NomeTipoObrigatórioDescrição
session_iduuidSimID da sessão ativa
file_urlstringSimURL pública do arquivo

Exemplo de Requisição​

curl -X POST https://api.tech4.ai/agent/v2/files/upload \
  -H "x-client-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "file_url": "https://example.com/path/to/file.pdf"
  }'

Opção 2: Upload via Multipart (Arquivo Binário)​

Use este método para enviar arquivos diretamente do seu sistema.

Parâmetros (Form-Data)​

NomeTipoObrigatórioDescrição
session_idstringSimUUID da sessão ativa
filefileSimArquivo binário a ser enviado
file_urlstringNãoURL alternativa (opcional)

Exemplo de Requisição​

curl -X POST https://api.tech4.ai/agent/v2/files/upload \
  -H "x-client-key: YOUR_API_KEY" \
  -F "session_id=550e8400-e29b-41d4-a716-446655440000" \
  -F "file=@/path/to/local/document.pdf"

Respostas do Upload​

Sucesso (200 OK)​

Arquivo enviado com sucesso.

{
  "file_id": "e5f6a7b8-c9d0-1234-ef56-789012345678",
  "detail": "File uploaded successfully"
}

Requisição Inválida (400 Bad Request)​

Requisição inválida ou erro de validação do arquivo.

{
  "detail": "Invalid request or file validation error"
}

Não Autorizado (401 Unauthorized)​

Chave de API inválida.

{
  "detail": "Invalid client key"
}

Não Encontrado (404 Not Found)​

Recurso não encontrado.

{
  "detail": "Resource not found"
}

Erro Interno (500 Internal Server Error)​

Erro interno do servidor.

{
  "detail": "Internal server error"
}

Download de Arquivo​

Obtém a URL de download de um arquivo previamente enviado ou gerado pelo agente.

Endpoint​

GET https://api.tech4.ai/agent/v2/files/{file_id}

Headers​

x-client-key: YOUR_API_KEY

Parâmetros​

NomeTipoLocalObrigatórioDescrição
file_iduuidPathSimID único do arquivo retornado no upload ou enviado pelo agente

Exemplo de Requisição​

curl -X GET https://api.tech4.ai/agent/v2/files/e5f6a7b8-c9d0-1234-ef56-789012345678 \
  -H "x-client-key: YOUR_API_KEY"

Respostas​

Sucesso (200 OK)​

Retorna a URL de download válida por 10 minutos.

{
  "file_url": "https://example.com/files/download/e5f6a7b8-c9d0-1234-ef56-789012345678",
  "detail": "File successfully retrieved"
}
Atenção

A URL de download expira após 10 minutos. Se precisar acessar o arquivo novamente depois desse período, faça uma nova requisição para obter uma URL atualizada.

Não Autorizado (401 Unauthorized)​

Chave de API inválida.

{
  "detail": "Invalid client key"
}

Não Encontrado (404 Not Found)​

O arquivo não foi encontrado.

{
  "detail": "File not found"
}

Erro Interno (500 Internal Server Error)​

Erro interno do servidor.

{
  "detail": "Internal server error"
}

Tipos de Arquivo Suportados​

A API suporta diversos tipos de arquivo:

Documentos​

  • PDF (.pdf)
  • Texto (.txt)
  • Pkpass (.pkpass)

Imagens​

  • JPEG (.jpg, .jpeg)
  • PNG (.png)
  • WebP (.webp)

Áudio​

  • MP3 (.mp3)
  • WAV (.wav)
  • OGG (.ogg)
  • MP4 (.mp4)
Limites

Consulte os limites de tamanho de arquivo com o suporte técnico, pois podem variar de acordo com o tipo de arquivo e seu plano.

Exemplo Completo: Upload e Envio​

Aqui está um exemplo completo de como fazer upload de um arquivo e enviá-lo em uma mensagem:

Passo 1: Upload do Arquivo​

# Upload do arquivo
curl -X POST https://api.tech4.ai/agent/v2/files/upload \
  -H "x-client-key: YOUR_API_KEY" \
  -F "session_id=550e8400-e29b-41d4-a716-446655440000" \
  -F "file=@/path/to/contract.pdf"

# Resposta:
# {
#   "file_id": "e5f6a7b8-c9d0-1234-ef56-789012345678",
#   "detail": "File uploaded successfully"
# }

Passo 2: Enviar Mensagem com o Arquivo​

# Enviar mensagem com o arquivo
curl -X POST https://api.tech4.ai/agent/v2/conversation/550e8400-e29b-41d4-a716-446655440000/message \
  -H "x-client-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "document",
    "document": {
      "id": "e5f6a7b8-c9d0-1234-ef56-789012345678",
      "caption": "Contrato assinado para análise"
    }
  }'

Boas Práticas​

Recomendações
  • Valide arquivos antes do upload: Verifique tipo e tamanho no cliente
  • Use nomes descritivos: Adicione caption relevante ao enviar arquivos
  • Armazene file_id: Guarde o ID retornado para referência futura
  • Gerencie expiração: URLs de download expiram em 10 minutos

Próximos Passos​

Agora que você sabe gerenciar arquivos, explore: