Cliente de API de OpenAI

FacturaScripts incorpora la clase OpenAi, ubicada en la carpeta Lib, que simplifica el uso de las APIs de OpenAI para la generación de texto (chatGPT), imágenes y audio mediante inteligencia artificial.

Nota: Para utilizar estas APIs necesitas una clave API, lo cual puede generar costes. Consulta más detalles en la página de precios de OpenAI.

Todas las peticiones tienen un timeout por defecto de 60 segundos, que se puede cambiar con setTimeout().

💬 Uso de chatGPT

La función chat() de la clase OpenAi permite interactuar con chatGPT, recibiendo un array de mensajes y devolviendo la respuesta en formato string.

$mensajes = [];
$pregunta = '¿Qué es FacturaScripts?';
$respuesta = OpenAi::init('TU_CLAVE_API')
    ->setUserMessage($mensajes, $pregunta)
    ->chat($mensajes);

echo $respuesta; // Ejemplo de salida: "FacturaScripts es un software de código abierto para la gestión empresarial..."

Con setSystemMessage() podemos añadir también un mensaje de sistema, con las instrucciones de comportamiento:

$mensajes = [];
$respuesta = OpenAi::init('TU_CLAVE_API')
    ->setSystemMessage($mensajes, 'Eres un asistente experto en contabilidad española.')
    ->setUserMessage($mensajes, '¿Qué es el modelo 303?')
    ->chat($mensajes);

Y con getTotalTokens() obtenemos los tokens consumidos en la última petición de chat:

$tokens = OpenAi::init('TU_CLAVE_API')->getTotalTokens();

Selección de Modelos

De forma predeterminada se utiliza el modelo gpt-5-mini, optimizado por su rapidez y coste. Si deseas utilizar modelos específicos como GPT5 o GPT5.1, puedes especificarlo como tercer parámetro (el segundo es el identificador de usuario final, que puedes dejar vacío).

$mensajes = [];
$pregunta = '¿Qué es FacturaScripts?';
$respuesta = OpenAi::init('TU_CLAVE_API')
    ->setUserMessage($mensajes, $pregunta)
    ->chat($mensajes, '', 'gpt-5.1');

Respuestas estructuradas (JSON)

La función chatJson() fuerza al modelo a responder con el formato indicado en response_format, y devuelve la respuesta ya convertida en array:

$mensajes = [];
$formato = [
    'type' => 'json_schema',
    'json_schema' => [
        'name' => 'clasificacion',
        'schema' => [
            'type' => 'object',
            'properties' => [
                'categoria' => ['type' => 'string'],
                'confianza' => ['type' => 'number']
            ]
        ]
    ]
];
$resultado = OpenAi::init('TU_CLAVE_API')
    ->setUserMessage($mensajes, 'Clasifica este producto: tornillo de acero M8')
    ->chatJson($mensajes, $formato);

🎨 Generación de Imágenes con IA

Utiliza la función image() para generar imágenes a partir de una descripción en texto. Por defecto se utiliza el modelo gpt-image-2-mini. La imagen se guarda en la carpeta MyFiles y la función devuelve su ruta.

$image_path = OpenAi::init('TU_CLAVE_API')
    ->image('an illustration for an accounting software');

echo $image_path; // Ejemplo: MyFiles/image_XXXXX.png

Tamaños de Imagen

Los tamaños soportados por el modelo son 1024x1024 (por defecto), 1536x1024 y 1024x1536. Puedes pedir cualquier otra resolución con los parámetros width y height: la imagen se generará en el tamaño soportado más cercano según su orientación y después FacturaScripts la redimensionará automáticamente al tamaño solicitado.

$image_path = OpenAi::init('TU_CLAVE_API')
    ->image('an illustration for an accounting software', 800, 800);

// Se genera a 1024x1024 y luego se redimensiona a 800x800

Opciones avanzadas

La firma completa es image($prompt, $width, $height, $count, $model, $options). En el array options se pueden indicar parámetros adicionales de la API: output_format (png por defecto), output_compression, stream y content_moderation.

$image_path = OpenAi::init('TU_CLAVE_API')
    ->image('an illustration for an accounting software', 1024, 1024, 1, 'gpt-image-2-mini', [
        'output_format' => 'jpeg'
    ]);

🔊 Generación de Audio con IA

Utiliza la función audio() para transformar texto en un archivo de audio (modelo gpt-4o-mini-tts). El método guarda el archivo en MyFiles y devuelve su ruta.

$audio_path = OpenAi::init('TU_CLAVE_API')
    ->audio('Esto es una prueba de audio generada mediante IA y almacenada en un archivo mp3');

echo $audio_path; // Ejemplo: MyFiles/audio_XXX.mp3

Selección de Voces

Por defecto, se utiliza la voz alloy. Las voces adicionales disponibles son:

echo
fable
onyx
nova
shimmer

Puedes seleccionar una voz específica pasando el nombre de la voz como segundo parámetro a la función audio().

$audio_path = OpenAi::init('TU_CLAVE_API')
    ->audio('Esto es una prueba de audio', 'nova');

Formatos de Audio

El formato predeterminado del audio es mp3. Sin embargo, también puedes generar archivos en formato opus, aac o flac especificándolo en el tercer parámetro. El cuarto parámetro permite cambiar el modelo.

$audio_path = OpenAi::init('TU_CLAVE_API')
    ->audio('Esto es una prueba de audio', 'alloy', 'aac');

Transcripción de Audio

El proceso inverso, convertir un archivo de audio en texto, se hace con la función audioTranscript() (modelo gpt-4o-transcribe), pasando el archivo como CURLFile:

$file_path = Tools::folder('MyFiles', 'nota-de-voz.mp3');
$file = new CURLFile($file_path, mime_content_type($file_path), 'nota-de-voz.mp3');

$texto = OpenAi::init('TU_CLAVE_API')->audioTranscript($file);

🤖 API de Asistentes

La clase también cubre la API de asistentes de OpenAI (Assistants v2), con sus hilos, archivos y almacenes de vectores. Todos estos métodos devuelven la respuesta de la API como array (vacío en caso de error, que se registra en el log).

Asistentes

assistantCreate($params) : crea un asistente con los parámetros indicados.
assistantRead($idAssistant) : devuelve los datos de un asistente.
assistantUpdate($idAssistant, $params) : actualiza un asistente.

Hilos de conversación

threadCreate() : crea un hilo de conversación.
threadRead($idThread) : devuelve los datos de un hilo.
threadMessages($idThread, $idRun) : devuelve los mensajes de un hilo, opcionalmente de una ejecución concreta.
threadMessageCreate($message, $idThread) : añade un mensaje a un hilo.
threadRun($idThread, $idAssistant) : ejecuta un asistente sobre un hilo.
threadRunRead($idThread, $idRun) : devuelve el estado de una ejecución.
threadRunSubmitToolOutputs($idThread, $idRun, $outputs) : envía los resultados de las herramientas que ha solicitado una ejecución.

Archivos

fileUpload($file, $purpose) : sube un archivo (CURLFile) a OpenAI, por defecto con propósito assistants.
fileList() : lista los archivos subidos.
fileRead($idFile) : devuelve los datos de un archivo.
fileDelete($idFile) : elimina un archivo.

Almacenes de vectores (vector stores)

vectorCreate($data) : crea un almacén de vectores.
vectorRead($idVector) : devuelve los datos de un almacén.
vectorFiles($idVector) : lista los archivos de un almacén.
vectorFile($idVector, $idFile) : añade un archivo al almacén.
vectorFileDelete($idVector, $idFile) : elimina un archivo del almacén.

Anterior Siguiente