Concepto y arquitectura#

Un archivo en Kivox es un recurso que puede usarse como avatar, adjuntarse a un mensaje de conversación, incorporarse a una base de conocimiento o utilizarse como grabación o archivo de voz.

#Los bytes nunca pasan por la API de Kivox

Subir o descargar un archivo no envía sus bytes a server.kivox.com.co. En su lugar, la API emite una URL firmada de corta duración hacia el proveedor de almacenamiento de objetos, y el contenido viaja directamente entre su aplicación y ese proveedor.

Esta arquitectura tiene dos consecuencias prácticas. Primero, la latencia y el ancho de banda de una subida dependen del proveedor de almacenamiento, no de la API de Kivox. Segundo, integrando directamente contra la API, su aplicación necesita orquestar tres pasos por separado: solicitar la URL, subir los bytes y reportar el resultado. Un SDK puede unificar esos tres pasos en un solo método, como se describe en Subir archivos.

#El propósito de un archivo

Todo archivo se sube con un propósito (purpose), que determina qué tipos de contenido se aceptan y qué tamaño máximo se permite.

El detalle completo de tipos permitidos y tamaños máximos por propósito está en Políticas de archivo.

#Estado de un archivo

Un archivo pasa por varios estados desde que se crea hasta que está disponible para usarse.

processing aplica a los tipos de archivo que requieren procesamiento antes de estar disponibles para su uso. Los detalles sobre qué formatos requieren procesamiento están en Políticas de archivo.

Para un archivo subido con propósito knowledge, ready significa que el contenido ya está disponible para su uso en la base de conocimiento. Por eso, una subida completada no implica necesariamente que el archivo ya pueda utilizarse: debe esperarse al estado ready, como se explica en Subir archivos.

#Usar el cliente de archivos

El cliente principal de Kivox se encarga de las solicitudes a la API. Las operaciones de archivos, además, necesitan comunicarse directamente con el almacenamiento de objetos, por lo que el SDK proporciona KivoxFiles como cliente especializado.

KivoxFiles recibe una instancia existente de Kivox. De esta forma, reutiliza la misma configuración de API, incluyendo baseUrl, encabezados de autenticación, credenciales y middlewares.

import { Kivox } from "@kivox/sdk";
import { KivoxFiles } from "@kivox/sdk/files";

const kivox = new Kivox({
    headers: {
        Authorization: `Bearer ${process.env.KIVOX_API_KEY}`,
    },
});

const files = new KivoxFiles(kivox);

Mantenga una instancia de KivoxFiles y reutilícela para las operaciones de archivos de su aplicación. No es necesario crear un nuevo cliente para cada subida o descarga.

Las operaciones disponibles, incluyendo subir, descargar y eliminar archivos, se documentan en las siguientes páginas.