Come usare CometAPI in Raycast — una guida pratica

Le funzionalità AI di Raycast ora consentono di collegare qualsiasi provider compatibile con OpenAI tramite un provider personalizzato providers.yaml. CometAPI è un'API gateway che espone centinaia di modelli tramite un'interfaccia REST in stile OpenAI — quindi puoi puntare Raycast a https://api.cometapi.com/v1, aggiungere la tua chiave CometAPI e utilizzare i modelli CometAPI all'interno di Raycast AI (chat, comandi, estensioni).

Che cos'è Raycast?

Raycast è un launcher di produttività per macOS che integra comandi, script e — sempre più — l'AI direttamente nel sistema operativo. Il suo sottosistema AI offre chat, comandi AI, selezione del modello, estensioni (strumenti che consentono agli LLM di eseguire azioni) e la possibilità di usare modelli locali (via Ollama) o Bring Your Own Key / Custom Providers per collegare provider di modelli remoti. Raycast espone un selettore di modelli, impostazioni per l’AI e un template providers.yaml che gli utenti avanzati possono personalizzare per aggiungere backend compatibili con OpenAI.

Raycast ha introdotto BYOK (Bring Your Own Key) e Custom Providers nel 2025, consentendo agli utenti di eseguire Raycast AI usando le proprie chiavi API ed endpoint personalizzati (abilitando una gestione dei costi più flessibile e opzioni di provider privati). Questo cambiamento è la base tecnica che rende fattibile l’integrazione di CometAPI dalle preferenze Raycast dell’utente finale.

In che modo Raycast rende l’AI accessibile agli utenti?

• Quick AI: prompt istantanei dal launcher.
• AI Chat: sessioni conversazionali con allegati/contesto.
• AI Commands/Extensions: comandi o strumenti sviluppati che utilizzano LLM.
  (Puoi gestire modelli, chiavi BYOK e provider personalizzati da Settings → AI.)

Che cos’è CometAPI?

CometAPI è una piattaforma di aggregazione di API che espone centinaia di modelli diversi (testo, immagini, audio, video, embeddings) tramite un’unica interfaccia REST in stile OpenAI. Invece di scrivere e mantenere codice client specifico per OpenAI, Anthropic, Google, Midjourney, Runway, ecc., chiami l’endpoint CometAPI e scegli il modello desiderato tramite una stringa di modello. Questa semplificazione è potente per la sperimentazione, il routing per costo/failover e la centralizzazione della fatturazione e dell’osservabilità.

Funzionalità principali

• Completamenti di testo/chat e assistants (API chat in stile OpenAI).
• Generazione di immagini ed endpoint di image editing.
• Embeddings per ricerca semantica/RAG (retrieval-augmented generation).
• Audio (TTS e STT se forniti dai modelli sottostanti).
• Generazione video per backend specializzati (Sora, Veo, ecc.).
  CometAPI fornisce anche snippet SDK e formati di richiesta in stile OpenAI, così il porting del codice esistente è lineare.

Perché è significativo adesso: il mercato si sta spostando verso API gateway (endpoint unici comodi, opzioni più economiche e scelta del modello). CometAPI è uno degli attori commerciali in questo spazio, quindi combinarlo con il supporto ai provider personalizzati di Raycast ti dà accesso immediato a un ampio catalogo di modelli direttamente dal tuo flusso di lavoro su macOS.

Perché integrare CometAPI con Raycast?

In breve: per eseguire qualsiasi modello esposto da CometAPI direttamente dal tuo flusso Raycast AI — Quick AI, AI Chat o comandi AI personalizzati — senza cambiare strumenti.

Vantaggi:

• Usa modelli più economici/veloci o specializzati per diversi compiti (riassunti, codice, embeddings, generazione di immagini) rimanendo dentro Raycast.
• Fatturazione e throttling centralizzati tramite CometAPI, mantenendo la selezione del modello da Raycast.
• Modifiche minime al codice: Raycast supporta provider personalizzati compatibili con OpenAI e BYOK, quindi CometAPI spesso si integra semplicemente sostituendo base_url e la chiave API.

(Queste capacità sono possibili perché Raycast supporta provider personalizzati e BYOK, e CometAPI espone endpoint compatibili con OpenAI su https://api.cometapi.com/v1. )

Quali sono i buoni casi d’uso per questa integrazione?

1. Developer helper: spiegazione del codice, suggerimenti di refactoring, generazione di unit test e riassunto di PR — invoca da Raycast e ottieni risposte in linea.
2. Note e riassunti: seleziona testo, esegui un comando Raycast per riassumere o estrarre azioni utilizzando un modello di sintesi CometAPI.
3. Redazione di documentazione: genera documentazione di funzioni o snippet README tramite comandi AI di Raycast e mantieni le iterazioni in locale.
4. Generazione di immagini/multimedia: se CometAPI espone endpoint immagini, puoi usare estensioni Raycast che chiamano tali endpoint (ad es., estensione "Generate Image from Prompt") — utile per mockup rapidi.
5. Embeddings + ricerca semantica: usa gli embeddings CometAPI per alimentare flussi di ricerca locali — Raycast può essere il front end che interroga il tuo indice di embeddings via uno script locale o una funzione cloud.

Quali ambiente e condizioni devono essere predisposti?

Prima di iniziare, assicurati di avere quanto segue pronto:

Sistema & Raycast

• macOS (Raycast è nativo per macOS).
• Raycast installato. Preferisci una versione recente che supporti Custom Providers / BYOK (Raycast ha aggiunto BYOK in v1.100.0 e continua a distribuire Custom Providers). Se la tua versione di Raycast è più vecchia, aggiornala.

Account & chiavi

• Account CometAPI e una chiave API CometAPI valida (la userai nelle impostazioni di Raycast o nelle variabili d’ambiente). Vedi dashboard/documentazione CometAPI.

Strumenti sviluppatore opzionali (per test o sviluppo locale)

• Terminale (per cURL).
• Python / Node / SDK OpenAI se vuoi testare l’accesso a CometAPI direttamente prima di collegarlo a Raycast. CometAPI supporta l’uso diretto tramite SDK standard sovrascrivendo base_url.

Permessi & rete

• Assicurati che Raycast e le policy di rete del tuo macOS consentano chiamate HTTPS verso api.cometapi.com.
• Se sei in un ambiente aziendale con proxy/firewall, verifica che api.cometapi.com sia raggiungibile.

File locali & percorsi

La configurazione dei provider AI di Raycast si trova in un providers.yaml nella directory di configurazione di Raycast (l’app può mostrare un template dei provider che puoi copiare). Modificherai o creerai providers.yaml per definire provider personalizzati.

Come integro Raycast con CometAPI?

L’idea centrale: registrare CometAPI come provider personalizzato compatibile con OpenAI in Raycast, puntare Raycast a https://api.cometapi.com/v1 e aggiungere il tuo token Comet alle chiavi API personalizzate di Raycast.

Passaggio 1: Ottieni la tua chiave CometAPI

1. Registrati su CometAPI e apri la console / dashboard.
2. Crea un token API. Copia questo token in un luogo sicuro (o conservalo per il passaggio successivo).

Passaggio 2: Apri le impostazioni AI di Raycast e abilita i provider personalizzati

1. In Raycast: Preferences → AI.
2. Trova “Custom Providers” (o “Custom OpenAI-compatible APIs”) e fai clic su Reveal Providers Config. Raycast aprirà il Finder nella directory di configurazione e fornirà un file template (di solito providers.template.yaml) da copiare e rinominare in providers.yaml.

Passaggio 3: Aggiungi un provider CometAPI a providers.yaml

Crea o modifica il file providers.yaml. Lo schema esatto atteso da Raycast può variare in base alla versione, ma i template della community e il manuale Raycast mostrano una struttura comune: un elenco di voci provider con id, name, base_url e un blocco models opzionale. Di seguito un esempio sicuro e funzionante per registrare CometAPI come un OpenAI-co

Note importanti

• Sostituisci YOUR_COMETAPI_KEY con un riferimento sicuro — incolla il token (per uso personale) o, meglio: archivialo nel macOS Keychain / campi sicuri di Raycast se supportato.
• base_url è la linea importante: puntala a https://api.cometapi.com/v1. Raycast userà quel base URL per chiamate compatibili con OpenAI.
• Non è strettamente necessario elencare in anticipo tutti i modelli — Raycast può recuperare l’elenco dei modelli da un endpoint GET /v1/models in stile OpenAI se il tuo provider lo espone. Se CometAPI espone un elenco modelli, Raycast può aggiornarlo e mostrare i modelli disponibili.

Passaggio 4: Aggiorna i modelli ed esegui un test

• Di ritorno in Raycast, potresti dover riavviare l’app o usare un comando “Refresh Models” (in base alla versione) affinché Raycast recuperi i modelli dal nuovo provider e popoli il selettore di modelli. Consiglio di aggiornare o riavviare se i modelli non compaiono.
• Usa un semplice prompt Quick AI per scegliere il modello di CometAPI dal selettore e lanciare un prompt di test.

Best practice quando usi CometAPI dentro Raycast

Best practice di sicurezza: Non inserire mai token in chiaro in providers.yaml condivisi. Preferisci i campi sicuri di Raycast o il macOS Keychain, o inietta le chiavi localmente con variabili d’ambiente se usi un proxy locale. Leggi la documentazione sulla privacy sia di CometAPI sia di Raycast se gestisci dati sensibili.

Affidabilità & performance: Testa la latenza dei modelli che intendi usare — le API gateway possono avere routing variabile. Per flussi interattivi (autosummary, ricerche rapide) preferisci modelli più piccoli e veloci. Per attività di ragionamento più profonde scegli modelli con contesto maggiore.

Controllo dei costi: Usa in modo mirato la selezione del modello: scegli modelli leggeri per attività brevi, modelli ad alta capacità per ragionamento pesante. Monitora l’uso dalla dashboard di CometAPI e imposta avvisi di budget. Considera prompt più compatti per ridurre i token (ad es., messaggi di sistema più brevi, gestione efficiente del contesto).

Prompt engineering & UX: Quando crei Raycast AI Commands (duplica un comando integrato e modifica il prompt), mantieni i prompt deterministici per i comandi utilitaristici (riassunto, triage, ricerca) e più aperti per i flussi di ideazione. Copiare i comandi integrati e personalizzare i prompt è il modo consigliato.

Come risolvere i problemi comuni?

I modelli non compaiono in Raycast: assicurati che providers.yaml si trovi esattamente nella cartella mostrata da Reveal Providers Config. Usa il template come base e riavvia Raycast. Un riavvio o “Refresh Models” aiuta.

401 / token non valido: conferma che il tuo token CometAPI sia valido e non scaduto. Prova il test con curl indicato sopra. Verifica di usare un token Bearer e che l’header Authorization sia corretto.

Errori del modello o formati di risposta incompatibili: CometAPI mira a essere compatibile con OpenAI, ma esistono edge case (ID dei modelli, comportamenti di streaming). Se Raycast si aspetta un formato di streaming specifico e CometAPI emette una forma leggermente diversa, prova prima una chiamata non in streaming e contatta il supporto CometAPI se necessario.

Conclusione

CometAPI ti offre accesso unificato e multi-vendor a molti modelli (testo, immagini, audio, video) e consente ai team di centralizzare fatturazione e routing. Raycast ti offre un luogo istantaneo e orientato alla tastiera per chiamare quei modelli nel contesto dei tuoi flussi desktop. Insieme rendono la sperimentazione sui modelli e l’automazione desktop senza attriti — puoi cambiare modello per costo o qualità, mantenere le chiavi in locale e usare gli stessi pattern in stile OpenAI che già adoperi in script e app.

Se vuoi provare subito, esplora le capacità dei models's(Gemini 3 Pro Preview API ecc) di CometAPI nel Playground e consulta la guida API per istruzioni dettagliate. Prima di accedere, assicurati di aver effettuato l’accesso a CometAPI e di aver ottenuto la chiave API. CometAPI offre un prezzo molto inferiore al prezzo ufficiale per aiutarti a integrare.

Pronto a iniziare?→ use CometAPI in Raycast today !

Se vuoi conoscere altri suggerimenti, guide e novità sull’AI seguici su VK, X e Discord!