Vercel AI SDK

L'AI SDK di Vercel è il toolkit standard per costruire funzionalità AI in TypeScript. Punta il suo provider @ai-sdk/openai-compatible su Synthorai e l'intero catalogo diventa disponibile con una sola chiave, con le famiglie Claude, GPT, Gemini e open-weight affiancate.

Prima di iniziare

Crea una chiave API in Console → API Keys. Copiala subito: viene mostrata una sola volta.

Passo 1 - Installare i pacchetti

npm i ai @ai-sdk/openai-compatible

Synthorai parla il formato Chat Completions di OpenAI, quindi non serve alcun pacchetto specifico per Synthorai: il provider ufficiale compatibile OpenAI è la strada supportata.

Passo 2 - Creare l'istanza del provider

import { createOpenAICompatible } from '@ai-sdk/openai-compatible';

const synthorai = createOpenAICompatible({
  name: 'synthorai',
  baseURL: 'https://synthorai.io/v1',
  apiKey: process.env.SYNTHORAI_API_KEY,
});

Il valore name è un'etichetta usata in trace e messaggi di errore; non influisce sul routing. Il routing è deciso da baseURL e dall'identificativo di modello che passi.

⚠

L'URL di base deve terminare con /v1. Il provider aggiunge percorsi come /chat/completions quindi senza di esso la richiesta finisce sul percorso sbagliato.

Passo 3 - Generare e trasmettere testo

import { generateText } from 'ai';

const { text } = await generateText({
  model: synthorai('claude-sonnet-5-5'),
  prompt: 'Tell me about yourself in one sentence.',
});

console.log(text);

Il primo argomento è un identificativo di modello del catalogo. Lo streaming usa la stessa istanza, senza configurazione aggiuntiva:

import { streamText } from 'ai';

const result = streamText({
  model: synthorai('claude-sonnet-5-5'),
  prompt: 'Write a short haiku about routing.',
});

for await (const textPart of result.textStream) {
  process.stdout.write(textPart);
}

Scegliere un modello

Qualsiasi identificativo del catalogo funziona. Questi sono default ragionevoli:

Parametro	Tipo	Descrizione
`claude-opus-5-5`	`agentic`	Una scelta solida per lunghe sessioni agentiche e modifica del codice.
`gpt-5.4`	`reasoning`	Ragionamento generico su carichi di lavoro misti.
`gpt-5.4-mini`	`fast`	Veloce ed economico: adatto a classificazione e completions brevi.
`deepseek-v4-flash`	`cheapest`	Tra i modelli più economici del catalogo, adatto ai grandi volumi.

Usare invece la superficie Anthropic

La stessa chiave serve anche il formato Anthropic Messages su un percorso diverso, che l'AI SDK raggiunge tramite il suo provider Anthropic. Usalo per le funzionalità native Anthropic e il provider compatibile OpenAI qui sopra per tutto il resto.

import { createAnthropic } from '@ai-sdk/anthropic';

const synthoraiAnthropic = createAnthropic({
  baseURL: 'https://synthorai.io/v1',
  apiKey: process.env.SYNTHORAI_API_KEY,
});

⚠

Attenzione alla differenza rispetto all'SDK Anthropic nativo: quello riceve la radice dell'host e aggiunge /v1/messages da sé, mentre il provider Anthropic dell'AI SDK si aspetta un prefisso che contenga già /v1. Passare il solo host porta al percorso sbagliato.

Risoluzione dei problemi

404 a ogni chiamata. L'URL di base deve terminare con /v1. Il provider aggiunge percorsi come /chat/completions quindi senza di esso la richiesta finisce sul percorso sbagliato.

401 Unauthorized. La variabile d'ambiente viene letta al caricamento del modulo, quindi una chiave esportata dopo l'avvio del processo non verrà considerata. Riavvia il processo dopo averla impostata.

Modello non trovato. Gli identificativi di modello distinguono maiuscole e minuscole e devono corrispondere esattamente al catalogo. Elenca ciò che la tua chiave raggiunge con: curl https://synthorai.io/v1/models -H "Authorization: Bearer $SYNTHORAI_API_KEY"

Ogni identificativo di modello e il suo prezzo sono nella model price comparison.