Protocolos de API para LLM

O Atlas Cloud aceita seis formatos de requisição diferentes na mesma base URL e com a mesma chave de API. Aponte um SDK existente para o Atlas Cloud e ele geralmente funciona sem alterações — sem reescrita, sem camada de adaptação própria.

https://api.atlascloud.ai

Matriz de protocolos

Autenticação

Sua chave de API funciona com qualquer um dos quatro estilos de cabeçalho, de modo que SDKs feitos para outros provedores autenticam sem modificação:

-H "Authorization: Bearer $ATLASCLOUD_API_KEY"

As chaves de API do Atlas Cloud começam com apikey-. Consulte Chaves API.

OpenAI Chat Completions

O formato com maior suporte.

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
  }'

Usando o SDK da OpenAI — mude duas linhas:

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)

Parâmetros de amostragem. O suporte varia por modelo — cada modelo publica seus próprios supported_sampling_parameters. Comumente disponíveis: 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).

Saída estruturada. O response_format aceita tanto {"type": "json_object"} quanto uma definição json_schema, em modelos que anunciam json_mode ou structured_outputs.

Chamada de ferramentas. tools, tool_choice e parallel_tool_calls são repassados em modelos que anunciam tools.

Entrada multimodal. Imagens, vídeo e áudio podem ser anexados como partes de conteúdo:

{
  "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 é uma extensão do Atlas Cloud além da especificação da OpenAI. O áudio precisa ser Base64 embutido — uma URL não é aceita em input_audio.

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"}]
  }'

Aponte o SDK da Anthropic para o Atlas Cloud definindo base_url como https://api.atlascloud.ai.

Suportado. system (string ou array de blocos), stop_sequences, tools com input_schema, tool_choice, thinking, blocos de imagem (fontes base64 e url), blocos document e tool_result. Blocos thinking do assistente são mapeados para a saída de raciocínio.

Diferenças que você precisa conhecer:

O streaming segue a sequência de eventos da Anthropic: message_start, content_block_start, content_block_delta, content_block_stop, message_delta, message_stop. Não há sentinela [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
  }'

Suportado. instructions, input em todas as suas formas, tools, tool_choice, reasoning.effort, text.format (tanto json_object quanto json_schema), text.verbosity, temperature, top_p, stream, parallel_tool_calls.

Ignorados silenciosamente — aceitos sem erro, mas sem efeito: previous_response_id, store, include, background, conversation, prompt, truncation, max_tool_calls, top_logprobs e reasoning.summary. O metadata é devolvido na resposta, mas não é encaminhado.

Multimodal. Imagens e áudio. Sem vídeo neste protocolo. As imagens usam {"type": "input_image", "image_url": "<url string>"} — observe que o valor é uma string simples, não um objeto.

O streaming emite o conjunto padrão de eventos do Responses, terminando com response.completed, response.incomplete ou response.failed. Não há sentinela [DONE].

Google Gemini

# Sem 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 — o parâmetro alt=sse é obrigatório
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"}]}]}'

Suportado. contents[] com os papéis user e model, systemInstruction, generationConfig e tools.

Multimodal. Imagens, vídeo e áudio — embutidos via inline_data ou por referência via file_data.file_uri.

Este protocolo é servido apenas por modelos que o falam nativamente. Modelos cujo identificador contém nano, banana ou omni são rejeitados aqui; use o Chat Completions ou os endpoints de geração de mídia para eles.

OpenAI Images

Geração síncrona de imagens para clientes compatíveis com 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"}'

O /v1/images/edits recebe multipart/form-data. Apenas um pequeno número de modelos anuncia este protocolo.

Comportamento do gateway

O gateway normaliza algumas coisas no caminho. Elas não constam das especificações originais e vão surpreender você se estiver depurando uma resposta:

Não disponível

Estes endpoints não existem no Atlas Cloud. Requisições para eles não funcionarão, independentemente do modelo:

• /v1/embeddings
• /v1/rerank
• /v1/audio/speech e /v1/audio/transcriptions — o áudio passa pelo endpoint de áudio
• /v1/messages/count_tokens

Provedores como Ollama, Cohere e Bedrock não são expostos como protocolos nativos. Modelos de muitos fornecedores estão disponíveis, mas sempre por um dos seis formatos acima.

Limites de taxa e erros

Os limites de taxa se aplicam por conta e por modelo. Quando você excede um deles, a API retorna 429.

Toda resposta traz um cabeçalho X-Request-ID. Inclua-o ao entrar em contato com o suporte.

Relacionado