sgcWebSockets 2026.4.0 introduce una grande estensione dell'integrazione con l'API OpenAI, portando il supporto completo per la nuova Responses API (sostituto ufficiale dell'API Assistants deprecata), Audio Speech text-to-speech, la gestione dei Fine-Tuning Jobs, la Batch API per l'elaborazione bulk asincrona, la Uploads API per la gestione di file di grandi dimensioni e Chat Completions modernizzate con supporto al tool calling e all'output strutturato. Questo articolo copre ogni nuovo metodo, i suoi parametri ed esempi pratici di codice Delphi.
Indice
- Responses API (sostituisce Assistants)
- Audio Speech (text-to-speech)
- Fine-Tuning Jobs
- Aggiornamenti Chat Completions
- Batch API
- Uploads API
1. Responses API (sostituisce Assistants)
La Responses API e' l'aggiunta piu' significativa di questa release. Sostituisce la deprecata API Assistants con un'
interfaccia stateless snella esposta tramite l'endpoint /responses.
Tutti i metodi sono disponibili sul componente TsgcHTTP_API_OpenAI.
A differenza di Assistants, ogni chiamata alla Responses API e' un singolo round-trip che puo' includere definizioni di tool, file search,
web search e output strutturato — tutto in un'unica richiesta.
Metodi
| Metodo | Descrizione | Endpoint |
|---|---|---|
CreateResponse |
Crea una nuova response del modello. Accetta un model identifier e un input testuale (o un array di input strutturato). Restituisce l'output generato dal modello, incluse eventuali tool call. | POST /responses |
RetrieveResponse |
Recupera una response creata in precedenza tramite il suo ID univoco. Utile per polling o auditing delle response completate. | GET /responses/{response_id} |
DeleteResponse |
Elimina definitivamente una response memorizzata. Applicabile solo se in fase di creazione e' stato usato store: true. |
DELETE /responses/{response_id} |
CancelResponse |
Annulla una response in corso. Applicabile alle response create in modalita' background. | POST /responses/{response_id}/cancel |
ListInputItems |
Elenca gli input item associati a una response. Utile per ispezionare il contesto della conversazione inviato al modello. | GET /responses/{response_id}/input_items |
Esempio Delphi
var
OpenAI: TsgcHTTP_API_OpenAI;
vResponse: String;
begin
OpenAI := TsgcHTTP_API_OpenAI.Create(nil);
Try
OpenAI.OpenAIOptions.ApiKey := 'sk-your-api-key';
// Create a simple response
vResponse := OpenAI._CreateResponse('gpt-4o', 'Explain quantum computing');
ShowMessage(vResponse);
// Retrieve a previously created response
vResponse := OpenAI._RetrieveResponse('resp_abc123');
ShowMessage(vResponse);
// Delete a stored response
OpenAI._DeleteResponse('resp_abc123');
Finally
OpenAI.Free;
end;
end;2. Audio Speech (text-to-speech)
L'API Audio Speech fornisce capability di text-to-speech utilizzando i modelli TTS di OpenAI. Supporta due tier di modello:
tts-1 per casi d'uso streaming a bassa latenza e
tts-1-hd per output di qualita' superiore.
Sono disponibili sei voci integrate: alloy, echo, fable,
onyx, nova e shimmer.
L'output puo' essere restituito nei formati mp3, opus, aac, flac, wav o pcm.
Metodi
| Metodo | Descrizione | Endpoint |
|---|---|---|
CreateSpeech |
Genera audio speech a partire dal testo di input usando il modello e la voce specificati. Restituisce il contenuto audio come stream binario. | POST /audio/speech |
Esempio Delphi
var
OpenAI: TsgcHTTP_API_OpenAI;
vAudioStream: TMemoryStream;
begin
OpenAI := TsgcHTTP_API_OpenAI.Create(nil);
Try
OpenAI.OpenAIOptions.ApiKey := 'sk-your-api-key';
// Generate speech using the 'alloy' voice
oStream := TFileStream.Create('stream.mpeg', fmCreate or fmOpenRead);
Try
OpenAI._CreateSpeech('tts-1', 'Hello world', 'alloy', oStream);
Finally
oStream.Free;
End;
// Generate high-definition speech with 'nova' voice
oStream := TFileStream.Create('stream.mpeg', fmCreate or fmOpenRead);
Try
OpenAI._CreateSpeech('tts-1-hd', 'Welcome to sgcWebSockets.', 'nova', oStream);
Finally
oStream.Free;
End;
Finally
OpenAI.Free;
end;
end;tts-1 e' ottimizzato per
applicazioni in tempo reale a bassa latenza, mentre tts-1-hd
offre maggiore fedelta' audio al costo di una latenza leggermente maggiore. Scegli in base ai requisiti della tua applicazione.
3. Fine-Tuning Jobs
L'API Fine-Tuning Jobs sostituisce il deprecato /fine-tunes
con il nuovo endpoint /fine_tuning/jobs.
Fornisce gestione completa del ciclo di vita delle operazioni di fine-tuning: creazione di job, elenco dei job attivi e completati,
recupero dei dettagli, annullamento di job in corso e streaming degli eventi di training. Quest'API supporta il fine-tuning
di modelli come gpt-4o-mini-2024-07-18 usando i tuoi dati di training.
Metodi
| Metodo | Descrizione | Endpoint |
|---|---|---|
CreateFineTuningJob |
Crea un nuovo job di fine-tuning usando un base model specificato e un file di training caricato in precedenza. Restituisce l'oggetto job con il suo ID e stato. | POST /fine_tuning/jobs |
ListFineTuningJobs |
Elenca tutti i job di fine-tuning dell'organizzazione, con supporto alla paginazione. Restituisce i job ordinati per data di creazione. | GET /fine_tuning/jobs |
RetrieveFineTuningJob |
Recupera informazioni dettagliate su uno specifico job di fine-tuning, inclusi stato, iperparametri e file di risultato. | GET /fine_tuning/jobs/{job_id} |
CancelFineTuningJob |
Annulla un job di fine-tuning in corso. Lo stato del job diventa "cancelled" e non viene eseguito ulteriore training. | POST /fine_tuning/jobs/{job_id}/cancel |
ListFineTuningJobEvents |
Elenca gli eventi di stato di un job di fine-tuning, inclusi training loss, metriche di validazione e stato di completamento. Supporta la paginazione. | GET /fine_tuning/jobs/{job_id}/events |
Esempio Delphi
var
OpenAI: TsgcHTTP_API_OpenAI;
vResponse: String;
begin
OpenAI := TsgcHTTP_API_OpenAI.Create(nil);
Try
OpenAI.OpenAIOptions.ApiKey := 'sk-your-api-key';
// Create a fine-tuning job
vResponse := OpenAI._CreateFineTuningJob('gpt-4o-mini-2024-07-18', 'file-abc123');
ShowMessage(vResponse);
// List all fine-tuning jobs
vResponse := OpenAI._ListFineTuningJobs;
ShowMessage(vResponse);
// Retrieve a specific job
vResponse := OpenAI._RetrieveFineTuningJob('ftjob-xyz789');
ShowMessage(vResponse);
// List events for a job
vResponse := OpenAI._ListFineTuningJobEvents('ftjob-xyz789');
ShowMessage(vResponse);
// Cancel an in-progress job
OpenAI._CancelFineTuningJob('ftjob-xyz789');
Finally
OpenAI.Free;
end;
end;4. Aggiornamenti Chat Completions
L'API Chat Completions in sgcWebSockets 2026.4.0 e' stata modernizzata con diverse nuove proprieta' di richiesta e campi di risposta. Queste aggiunte portano supporto completo a tool/function calling, output JSON strutturato, generazione deterministica tramite seed ed esecuzione parallela di tool.
Nuove proprieta' di richiesta
| Proprietà | Descrizione | Endpoint |
|---|---|---|
Tools |
Definisce un elenco di tool (funzioni) che il modello puo' chiamare. Ogni tool include nome, descrizione e JSON Schema dei parametri. | POST /chat/completions |
ToolChoice |
Controlla come il modello seleziona i tool. Opzioni: auto, none, required o uno specifico nome di funzione. |
POST /chat/completions |
ResponseFormat |
Specifica il formato dell'output. Usa json_object per garantire output JSON o json_schema per output strutturato conforme a uno schema fornito. |
POST /chat/completions |
Seed |
Un seed intero per il sampling deterministico. Usando lo stesso seed e gli stessi parametri, il modello tenta di produrre lo stesso output. | POST /chat/completions |
MaxCompletionTokens |
Imposta un limite superiore al numero di token che il modello puo' generare nella response. Sostituisce il vecchio parametro max_tokens. |
POST /chat/completions |
ParallelToolCalls |
Quando abilitato, il modello puo' emettere piu' tool call in una singola response, permettendo l'esecuzione parallela lato client. | POST /chat/completions |
StreamOptions |
Configurazione per le response in streaming. Include opzioni come include_usage per ricevere le statistiche di token usage nell'ultimo chunk streamato. |
POST /chat/completions |
Nuovi campi di risposta
| Campo | Descrizione | Endpoint |
|---|---|---|
ToolCalls |
Array di oggetti tool call nel messaggio assistant. Ognuno contiene ID, nome della funzione e argomenti per l'esecuzione lato client. | POST /chat/completions |
Refusal |
Contiene il messaggio di rifiuto del modello quando si rifiuta di soddisfare una richiesta per vincoli di sicurezza o di content policy. | POST /chat/completions |
SystemFingerprint |
Un fingerprint che rappresenta la configurazione di backend usata per generare la response. Utile per verificare l'output deterministico quando usi Seed. |
POST /chat/completions |
Esempio Delphi
var
OpenAI: TsgcHTTP_API_OpenAI;
vResponse: String;
begin
OpenAI := TsgcHTTP_API_OpenAI.Create(nil);
Try
OpenAI.OpenAIOptions.ApiKey := 'sk-your-api-key';
// Configure Chat Completions with new properties
OpenAI.ChatCompletions.Model := 'gpt-4o';
OpenAI.ChatCompletions.MaxCompletionTokens := 1024;
OpenAI.ChatCompletions.Seed := 42;
OpenAI.ChatCompletions.ParallelToolCalls := True;
OpenAI.ChatCompletions.ResponseFormat := 'json_object';
// Add a user message and create the completion
OpenAI.ChatCompletions.AddMessage('user', 'List 3 benefits of Delphi in JSON format.');
vResponse := OpenAI._CreateChatCompletion;
ShowMessage(vResponse);
Finally
OpenAI.Free;
end;
end;5. Batch API
L'API Batch permette di inviare grandi gruppi di richieste API per elaborazione asincrona. E' ideale per
carichi di lavoro che non richiedono risposte immediate, come classificazione bulk, generazione di embedding o
content moderation su larga scala. Le richieste batch si completano in genere entro 24 ore e offrono uno sconto del 50%
rispetto alle chiamate API sincrone. Tutti i metodi batch sono disponibili sul
componente TsgcHTTP_API_OpenAI tramite l'
endpoint /batches.
Metodi
| Metodo | Descrizione | Endpoint |
|---|---|---|
CreateBatch |
Crea un nuovo job batch a partire da un file JSONL caricato in precedenza contenente richieste API. Richiede l'ID del file di input e l'endpoint target. | POST /batches |
RetrieveBatch |
Recupera lo stato corrente e i dettagli di un job batch, inclusi i conteggi di avanzamento e i riferimenti ai file di output. | GET /batches/{batch_id} |
ListBatches |
Elenca tutti i job batch dell'organizzazione. Supporta la paginazione tramite i parametri after e limit. |
GET /batches |
CancelBatch |
Annulla un job batch in corso. Le richieste gia' completate all'interno del batch non vengono influenzate. | POST /batches/{batch_id}/cancel |
Esempio Delphi
var
OpenAI: TsgcHTTP_API_OpenAI;
vResponse: String;
begin
OpenAI := TsgcHTTP_API_OpenAI.Create(nil);
Try
OpenAI.OpenAIOptions.ApiKey := 'sk-your-api-key';
// Create a batch job targeting chat completions
vResponse := OpenAI._CreateBatch('file-abc123', '/v1/chat/completions');
ShowMessage(vResponse);
// Check batch status
vResponse := OpenAI._RetrieveBatch('batch_xyz789');
ShowMessage(vResponse);
// List all batches
vResponse := OpenAI._ListBatches;
ShowMessage(vResponse);
// Cancel a batch if needed
OpenAI._CancelBatch('batch_xyz789');
Finally
OpenAI.Free;
end;
end;CreateBatch deve essere un file JSONL
caricato tramite la Files API con purpose batch. Ogni riga
del file rappresenta una singola richiesta API con ID custom, metodo, URL e body.
6. Uploads API
L'API Uploads abilita il caricamento di file di grandi dimensioni in piu' parti, fondamentale quando lavori con file che
superano il limite di upload in singola richiesta (in genere 512 MB). Il workflow prevede la creazione di una sessione di upload,
l'aggiunta delle parti in sequenza e infine il completamento dell'upload per ottenere un oggetto
File utilizzabile con
altri endpoint API. Tutti i metodi sono disponibili sul
componente TsgcHTTP_API_OpenAI tramite l'
endpoint /uploads.
Metodi
| Metodo | Descrizione | Endpoint |
|---|---|---|
CreateUpload |
Avvia una nuova sessione di upload multipart. Richiede nome del file, purpose, conteggio totale dei byte e tipo MIME. Restituisce un oggetto upload con ID univoco. | POST /uploads |
AddUploadPart |
Aggiunge un chunk di dati a un upload in corso. Le parti devono essere aggiunte in sequenza e ogni parte restituisce un part ID necessario per il completamento. | POST /uploads/{upload_id}/parts |
CompleteUpload |
Completa l'upload multipart fornendo l'elenco ordinato dei part ID. Restituisce l'oggetto File finale utilizzabile con altre API. |
POST /uploads/{upload_id}/complete |
CancelUpload |
Annulla una sessione di upload in corso. Tutte le parti gia' caricate vengono scartate e l'upload ID diventa non valido. | POST /uploads/{upload_id}/cancel |
Esempio Delphi
var
OpenAI: TsgcHTTP_API_OpenAI;
vUploadResponse: String;
vPartResponse: String;
vCompleteResponse: String;
begin
OpenAI := TsgcHTTP_API_OpenAI.Create(nil);
Try
OpenAI.OpenAIOptions.ApiKey := 'sk-your-api-key';
// Step 1: Create an upload session
vUploadResponse := OpenAI._CreateUpload(
'training_data.jsonl', 'fine-tune', 104857600, 'application/jsonl');
ShowMessage(vUploadResponse);
// Step 2: Add file parts
vPartResponse := OpenAI._AddUploadPart('upload_abc123', 'C:\data\part1.jsonl');
ShowMessage(vPartResponse);
vPartResponse := OpenAI._AddUploadPart('upload_abc123', 'C:\data\part2.jsonl');
ShowMessage(vPartResponse);
// Step 3: Complete the upload
vCompleteResponse := OpenAI._CompleteUpload('upload_abc123',
'["part_def456", "part_ghi789"]');
ShowMessage(vCompleteResponse);
Finally
OpenAI.Free;
end;
end;