Torna al blog
Guida·23 maggio 2026·6 min di lettura

Migrare da OpenAI a Kunavo in 10 minuti — Python, Node, LangChain, Vercel AI SDK

Quattro modalità di integrazione con OpenAI, la modifica di una riga necessaria per iniziare a passare da Kunavo e uno smoke test che costa meno di un centesimo.

Se la tua app comunica già con l'API di OpenAI, passare a Kunavo richiede circa dieci minuti, la maggior parte dei quali serve per la registrazione. Questa guida illustra i quattro principali tipi di integrazione e la modifica di una riga necessaria per ciascuno.

Passaggio 0 — Ottieni una chiave (2 minuti)

  1. Registrati su kunavo.com/app/signup. Ricarica da $10, paga a consumo e il tuo saldo non scade mai.
  2. Visita /app/keys e crea una chiave. Inizia con sk-kn-.
  3. Imposta la variabile d'ambiente: export KUNAVO_API_KEY=sk-kn-....

Passaggio 1 — Cambia il tuo SDK (1 minuto)

Python (pacchetto openai)

migrate.py
# Before — pointing at OpenAI directly
from openai import OpenAI
client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
)

# After — pointing at Kunavo. Everything else stays the same.
from openai import OpenAI
client = OpenAI(
    api_key=os.environ["KUNAVO_API_KEY"],
    base_url="https://api.kunavo.com/v1",
)

Node / TypeScript

migrate.mjs
// Before
import OpenAI from "openai";
const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

// After
import OpenAI from "openai";
const client = new OpenAI({
  apiKey: process.env.KUNAVO_API_KEY,
  baseURL: "https://api.kunavo.com/v1",
});

LangChain

LangChain usa internamente lo stesso client OpenAI, quindi la modifica è identica. L'ID del modello è ora uno slug Kunavo: consulta /models per l'elenco aggiornato (prova claude-sonnet-4-6, gpt-5-6-terra, claude-opus-4-7).

langchain_setup.py
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="claude-sonnet-4-6",          # switched the model
    api_key=os.environ["KUNAVO_API_KEY"],
    base_url="https://api.kunavo.com/v1",
)

Vercel AI SDK

@ai-sdk/openai legge per impostazione predefinita l'URL di base e la chiave API dalle variabili d'ambiente. Impostale e hai finito: ogni helper del framework (streamText, generateObject, retry, routing degli strumenti) funziona senza modifiche.

vercel_ai.mjs
import { openai } from "@ai-sdk/openai";

// @ai-sdk/openai reads OPENAI_BASE_URL automatically
process.env.OPENAI_BASE_URL = "https://api.kunavo.com/v1";
process.env.OPENAI_API_KEY = process.env.KUNAVO_API_KEY;

const model = openai("claude-sonnet-4-6");
// then use streamText / generateText / streamObject as before

SDK Anthropic (se usi già Claude)

Kunavo espone la Messages API nativa di Anthropic su /v1/messages oltre al formato OpenAI, quindi non devi cambiare SDK.

anthropic_sdk.py
from anthropic import Anthropic

# Before — Anthropic SDK against api.anthropic.com
client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

# After — same SDK, against Kunavo. Caching, thinking, tools all pass through.
client = Anthropic(
    api_key=os.environ["KUNAVO_API_KEY"],
    base_url="https://api.kunavo.com",   # SDK appends /v1/messages
)

Passaggio 2 — Verifica il wallet (1 minuto)

Prima di toccare il codice di produzione, esegui un test economico verso claude-haiku-4-5. Se restituisce correttamente una risposta, la chiave funziona, la fatturazione funziona e il livello di routing è operativo.

smoke_test.py
# Cheap, deterministic-ish smoke test for migration validation.
resp = client.chat.completions.create(
    model="claude-haiku-4-5",            # the cheapest Claude
    messages=[{"role": "user", "content": "ping"}],
    max_tokens=8,
    temperature=0,
)
assert resp.choices[0].message.content, "empty response"
print("ok — Kunavo wallet works, total cost ~$0.0001")

Passaggio 3 — Sposta il traffico (5 minuti)

Il modello sicuro: due variabili d'ambiente nella tua app — AI_BASE_URL e AI_API_KEY — selezionate per ambiente. La produzione resta su OpenAI; lo staging passa a Kunavo. Dopo 24 ore, trasferisci la produzione.

Se vuoi valutare l'impatto sui costi prima del passaggio, la dashboard di Kunavo mostra il costo per chiamata rispetto alla tariffa ufficiale upstream: è facile calcolare il risparmio mensile previsto sui tuoi prompt reali.

Cosa rimane invariato

  • Il tuo SDK e il tuo codebase.
  • Streaming, function calling, uso degli strumenti, visione e output strutturati.
  • Gli schemi esatti delle richieste e delle risposte di OpenAI.
  • Formato degli errori (error.message / error.type / error.code).

Cosa migliora

  • Prezzi. I prezzi e gli sconti disponibili variano in base al modello: consulta le tariffe attuali su /pricing.
  • Modalità. Lo stesso SDK raggiunge Claude (claude-opus-4-7), GPT (gpt-5-6-sol), GPT-Image-2, Nano Banana, Veo 3 e Suno — consulta /models.
  • Fatturazione. Portafoglio Stripe, con prezzi in USD. Carte ovunque; Apple Pay, Google Pay e Link ovunque tranne che in India; inoltre, metodi locali in base al Paese (Alipay e WeChat Pay in Cina, Cash App Pay, Klarna e ACH negli Stati Uniti, UPI in India, KakaoPay in Corea…) — l'elenco completo è disponibile su /docs/billing.
  • Failover. Failover immediato multi-provider con reindirizzamento automatico all'interno della stessa richiesta quando un upstream presenta problemi.

Note sui casi problematici

  • Endpoint specifici di OpenAI che oggi non supportiamo: /v1/responses (usa /v1/chat/completions), /v1/assistants (mantieni lo stato sul tuo lato; siamo un gateway stateless), /v1/realtime (in programma).
  • Alcune funzionalità specifiche di Claude — cache_control, thinking esteso — funzionano meglio tramite l'endpoint nativo /v1/messages, non tramite il formato OpenAI.
  • La cache dei prompt non è tra queste: nel formato OpenAI, Kunavo imposta da sé i punti di interruzione della cache di Claude su un prompt lungo, e un cache_control che metti su un messaggio o sulla definizione di uno strumento viene inoltrato a Claude.

Bloccato? contact@kunavo.com: una persona risponde entro una giornata lavorativa. Se stai gestendo una migrazione importante, organizzeremo una chiamata.

Approfondimenti correlati