> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Utilizzare Ace Data Cloud in Jan

> Platform API guide - Ace Data Cloud

[Jan](https://jan.ai/) è un client desktop AI open source con priorità offline, in grado sia di eseguire modelli localmente sia di connettersi a endpoint compatibili con OpenAI tramite **Remote Engine**. Questo articolo spiega come connettersi ad Ace Data Cloud.

## Procedura di richiesta

Per connettere Ace Data Cloud in Jan, vai prima alla [console di Ace Data Cloud](https://platform.acedata.cloud/console/applications), ottieni il tuo API Token e conservalo come riserva.

![Ottenere l'API Key di Ace Data Cloud](https://cdn.acedata.cloud/dvc3cg.jpg)

Se non hai ancora effettuato l'accesso o non ti sei registrato, verrai automaticamente reindirizzato alla pagina di accesso per invitarti a registrarti e ad accedere; dopo l'accesso o la registrazione, tornerai automaticamente alla pagina corrente.

Al momento della prima richiesta verrà assegnato un credito gratuito, con cui potrai provare gratuitamente i servizi dei modelli di Ace Data Cloud.

## Scaricare Jan

Vai al [sito ufficiale di Jan](https://jan.ai/) e scarica in base alla piattaforma (Windows, macOS, Linux). Per i dispositivi Apple Silicon, scarica il pacchetto arm64 per ottenere le migliori prestazioni.

## Configurare Ace Data Cloud

Jan divide i modelli in due tipi: **Local Engine** (esecuzione locale) e **Remote Engine** (API di terze parti). Ace Data Cloud utilizza il protocollo compatibile con OpenAI e viene integrato come Remote Engine.

Apri Jan, vai in **Settings → Model Providers**, trova la scheda **OpenAI** e modificala:

| Campo | Valore | Descrizione |
| - | - | - |
| API Key | Il tuo Token di Ace Data Cloud | Token copiato dalla console |
| Base URL | `https://api.acedata.cloud/v1` | **Deve terminare con `/v1`, senza barra finale** |

> Il fatto che il Base URL debba terminare con `/v1` è una convenzione esplicita della documentazione ufficiale di Jan. Se non vuoi sovrascrivere la configurazione OpenAI originale, puoi usare «+ Add Provider» per creare un nuovo Provider di tipo `openai-compatible` e inserire gli stessi contenuti.

![Interfaccia di configurazione del Provider AceDataCloud aggiunto in Jan](https://cdn.acedata.cloud/26017d28afa1.png)

Dopo aver salvato il Provider personalizzato, Jan tenterà prima di chiamare `{Base URL}/models` per ottenere l'elenco dei modelli. Se la versione o l'endpoint corrente non restituisce un elenco disponibile, fai clic su **+ Add Model** nella parte inferiore della stessa pagina di modifica e inserisci manualmente l'ID del modello. Dopo l'aggiunta, il modello apparirà nel menu a discesa in alto a sinistra, con l'icona «Cloud» per distinguere remoto / locale.

![Interfaccia di gestione dei modelli Provider di Jan](https://cdn.acedata.cloud/ae485550946c.png)

> `MODEL_ID` è un segnaposto; vai al [catalogo dei modelli](https://platform.acedata.cloud/models) per visualizzare e sostituire con il nome del modello desiderato; per una verifica precisa, fai riferimento al valore `id` nella risposta di `/v1/models`. Questo valore è il nome del modello utilizzato dal parametro API `model`, non l'UUID del servizio o dell'API.

## Selezionare un modello

Il [catalogo dei modelli](https://platform.acedata.cloud/models) viene aggiornato continuamente. Dai priorità all'elenco dei modelli caricato automaticamente dal client; se devi compilare manualmente, richiedi prima `GET https://api.acedata.cloud/v1/models`, copia il valore `id` del modello desiderato dall'array `data` della risposta, quindi seleziona in base alle capacità di contesto, immagini e chiamate di strumenti supportate dal client.

## Verificare l'integrazione

Se non sei sicuro che il problema sia in Jan o nella rete, puoi prima verificare direttamente l'endpoint con curl (sostituisci `{token}` con il tuo Token):

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/v1/chat/completions' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "MODEL_ID",
    "messages": [{"role": "user", "content": "ping"}]
  }'
```

La restituzione di un oggetto `chat.completion` compatibile con OpenAI indica che sia il Token sia l'endpoint sono pronti; se viene restituito `HTTP 403 used_up`, significa che il Token è valido ma il saldo è insufficiente: basta ricaricare dalla [console](https://platform.acedata.cloud/console/applications).

## Avanzato: combinazione locale + cloud

Jan integra un API Server locale compatibile con OpenAI che può essere attivato (Settings → Local API Server); dopo l'attivazione, resta in ascolto su `http://localhost:1337/v1/chat/completions` ed esegue i modelli locali che hai scaricato. In questo modo, in framework come LangChain / LlamaIndex puoi indirizzare il Base URL al locale per il debugging gratuito, e passare ai modelli remoti di Ace Data Cloud per le attività complesse. Il contesto della conversazione non andrà perso quando cambi modello.

## Domande frequenti

### Viene visualizzato Connection error o 404

Di solito il Base URL non include `/v1`. Modificalo in `https://api.acedata.cloud/v1` (deve terminare con `/v1` e non scriverlo come `.../openai/v1`).

### Viene visualizzato 401 Unauthorized

Assicurati che nell'API Key sia incollato il Token di Ace Data Cloud (senza il prefisso `Bearer` e senza spazi aggiuntivi) e che il saldo dell'applicazione di appartenenza sia sufficiente.

### Il modello remoto non appare nel menu a discesa

Fai prima clic sul pulsante di aggiornamento dei modelli per attivare `/v1/models`; se il rilevamento automatico non riesce, usa **+ Add Model** manualmente e aggiungi senza modifiche il valore `id` del modello nel catalogo.

### È possibile caricare immagini affinché il modello le analizzi

Sì, ma devi selezionare dal catalogo dei modelli corrente un modello che supporti esplicitamente l'input visivo.

## Per saperne di più

* [Sito ufficiale di Jan](https://jan.ai/) ｜ [Jan GitHub](https://github.com/menloresearch/jan) ｜ [Documentazione di Jan](https://jan.ai/docs)
* [Documentazione ufficiale di Jan per la connessione a endpoint personalizzati compatibili con OpenAI](https://jan.ai/docs/desktop/remote-models/custom-endpoint)
* [Documentazione ufficiale del Local API Server di Jan](https://jan.ai/docs/desktop/api-server)
* [Documentazione API OpenAI Chat Completions di Ace Data Cloud](https://platform.acedata.cloud/documents/openai-chat-completions)
* [Elenco dei servizi di Ace Data Cloud](https://platform.acedata.cloud/documents)
* [Console di Ace Data Cloud](https://platform.acedata.cloud/console)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.