Protocolli API LLM

Atlas Cloud accetta sei diversi formati di richiesta sullo stesso URL di base con la stessa chiave API. Punta un SDK esistente verso Atlas Cloud e in genere funziona senza modifiche — nessuna riscrittura, nessun livello di adattamento da scrivere.

https://api.atlascloud.ai

Matrice dei protocolli

Autenticazione

La tua chiave API funziona con quattro stili di header, così gli SDK pensati per altri provider si autenticano senza modifiche:

-H "Authorization: Bearer $ATLASCLOUD_API_KEY"

Le chiavi API di Atlas Cloud iniziano con apikey-. Vedi Chiavi API.

OpenAI Chat Completions

Il formato supportato più ampiamente.

curl https://api.atlascloud.ai/v1/chat/completions \
  -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-ai/deepseek-v3.2",
    "messages": [{"role": "user", "content": "Explain HTTP vs HTTPS"}],
    "max_tokens": 1024,
    "stream": true
  }'

Con l'SDK OpenAI — cambia due righe:

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ATLASCLOUD_API_KEY"],
    base_url="https://api.atlascloud.ai/v1",
)

response = client.chat.completions.create(
    model="deepseek-ai/deepseek-v3.2",
    messages=[{"role": "user", "content": "Explain HTTP vs HTTPS"}],
)
print(response.choices[0].message.content)

Parametri di campionamento. Il supporto varia da modello a modello — ciascuno pubblica i propri supported_sampling_parameters. Comunemente disponibili: temperature (0–2), top_p (0–1), top_k, min_p, frequency_penalty (−2–2), presence_penalty (−2–2), repetition_penalty, stop, seed, logit_bias, logprobs, top_logprobs (0–20).

Output strutturato. response_format accetta sia {"type": "json_object"} sia una definizione json_schema, sui modelli che dichiarano json_mode o structured_outputs.

Chiamate di strumenti. tools, tool_choice e parallel_tool_calls vengono inoltrati sui modelli che dichiarano tools.

Input multimodale. Immagini, video e audio possono essere allegati come parti di contenuto:

{
  "role": "user",
  "content": [
    { "type": "text", "text": "What is in this image?" },
    { "type": "image_url", "image_url": { "url": "https://example.com/photo.jpg" } },
    { "type": "video_url", "video_url": { "url": "https://example.com/clip.mp4" } },
    { "type": "input_audio", "input_audio": { "data": "<base64>", "format": "mp3" } }
  ]
}

video_url è un'estensione di Atlas Cloud oltre la specifica OpenAI. L'audio deve essere Base64 inline — per input_audio non viene accettato un URL.

Anthropic Messages

curl https://api.atlascloud.ai/v1/messages \
  -H "x-api-key: $ATLASCLOUD_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-ai/deepseek-v3.2",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Punta l'SDK Anthropic verso Atlas Cloud impostando base_url su https://api.atlascloud.ai.

Supportato. system (stringa o array di blocchi), stop_sequences, tools con input_schema, tool_choice, thinking, blocchi immagine (sia sorgenti base64 sia url), blocchi document e tool_result. I blocchi thinking dell'assistente vengono mappati sull'output di ragionamento.

Differenze da conoscere:

Lo streaming segue la sequenza di eventi di Anthropic: message_start, content_block_start, content_block_delta, content_block_stop, message_delta, message_stop. Non esiste un sentinella [DONE].

OpenAI Responses

curl https://api.atlascloud.ai/v1/responses \
  -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-ai/deepseek-v3.2",
    "input": [{"role": "user", "content": [{"type": "input_text", "text": "Hello"}]}],
    "max_output_tokens": 1024
  }'

Supportato. instructions, input in tutte le sue forme, tools, tool_choice, reasoning.effort, text.format (sia json_object sia json_schema), text.verbosity, temperature, top_p, stream, parallel_tool_calls.

Ignorati silenziosamente — accettati senza errore ma senza alcun effetto: previous_response_id, store, include, background, conversation, prompt, truncation, max_tool_calls, top_logprobs e reasoning.summary. metadata viene restituito così com'è ma non inoltrato.

Multimodale. Immagini e audio. Nessun video su questo protocollo. Le immagini usano {"type": "input_image", "image_url": "<url string>"} — nota che il valore è una semplice stringa, non un oggetto.

Lo streaming emette l'insieme standard di eventi di Responses e termina con response.completed, response.incomplete o response.failed. Non esiste un sentinella [DONE].

Google Gemini

# Non-streaming
curl "https://api.atlascloud.ai/v1beta/models/MODEL_ID:generateContent" \
  -H "x-goog-api-key: $ATLASCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"role": "user", "parts": [{"text": "Hello"}]}],
    "generationConfig": {"maxOutputTokens": 1024, "temperature": 0.7}
  }'

# Streaming — the alt=sse parameter is required
curl "https://api.atlascloud.ai/v1beta/models/MODEL_ID:streamGenerateContent?alt=sse" \
  -H "x-goog-api-key: $ATLASCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents": [{"role": "user", "parts": [{"text": "Hello"}]}]}'

Supportato. contents[] con i ruoli user e model, systemInstruction, generationConfig e tools.

Multimodale. Immagini, video e audio — inline tramite inline_data, oppure per riferimento tramite file_data.file_uri.

Questo protocollo è servito solo dai modelli che lo parlano nativamente. I modelli il cui identificatore contiene nano, banana o omni vengono rifiutati qui; per quelli usa invece Chat Completions o gli endpoint di generazione media.

OpenAI Images

Generazione di immagini sincrona per i client compatibili con OpenAI:

curl https://api.atlascloud.ai/v1/images/generations \
  -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "MODEL_ID", "prompt": "a cat", "n": 1, "size": "1024x1024"}'

/v1/images/edits richiede multipart/form-data. Solo un numero ridotto di modelli dichiara questo protocollo.

Comportamento del gateway

Il gateway normalizza alcune cose lungo il percorso. Non sono previste dalle specifiche upstream e ti sorprenderanno mentre esamini una risposta:

Non disponibile

Questi endpoint non esistono su Atlas Cloud. Le richieste inviate a essi non funzioneranno, indipendentemente dal modello:

• /v1/embeddings
• /v1/rerank
• /v1/audio/speech e /v1/audio/transcriptions — l'audio passa da l'endpoint audio
• /v1/messages/count_tokens

Provider come Ollama, Cohere e Bedrock non sono esposti come protocolli nativi. I modelli di molti fornitori sono disponibili, ma sempre attraverso uno dei sei formati elencati sopra.

Limiti di frequenza ed errori

I limiti di frequenza si applicano per account e per modello. Quando ne superi uno, l'API restituisce 429.

Ogni risposta include un header X-Request-ID. Includilo quando contatti il supporto.

Argomenti correlati