LLM API 프로토콜

Atlas Cloud는 동일한 기본 URL과 동일한 API 키로 여섯 가지 요청 형식을 받습니다. 이미 쓰고 있는 SDK를 Atlas Cloud로 향하게만 하면 대체로 그대로 동작합니다 — 코드를 다시 쓸 필요도, 직접 어댑터 계층을 만들 필요도 없습니다.

https://api.atlascloud.ai

프로토콜 매트릭스

인증

API 키는 네 가지 헤더 방식 중 무엇으로도 동작하므로, 다른 제공업체를 위해 만들어진 SDK도 수정 없이 인증할 수 있습니다:

-H "Authorization: Bearer $ATLASCLOUD_API_KEY"

Atlas Cloud API 키는 apikey-로 시작합니다. API 키를 참조하세요.

OpenAI Chat Completions

가장 널리 지원되는 형식입니다.

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

OpenAI SDK를 사용하는 경우 — 두 줄만 바꾸면 됩니다:

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)

샘플링 파라미터. 지원 여부는 모델마다 다르며, 각 모델이 자체 supported_sampling_parameters를 공개합니다. 일반적으로 사용할 수 있는 항목: temperature(02), top_p(01), top_k, min_p, frequency_penalty(−22), presence_penalty(−22), repetition_penalty, stop, seed, logit_bias, logprobs, top_logprobs(0~20).

구조화된 출력. json_mode 또는 structured_outputs를 공개한 모델에서는 response_format에 {"type": "json_object"}와 json_schema 정의를 모두 사용할 수 있습니다.

도구 호출. tools를 공개한 모델에서는 tools, tool_choice, parallel_tool_calls가 그대로 전달됩니다.

멀티모달 입력. 이미지, 동영상, 오디오를 콘텐츠 파트로 첨부할 수 있습니다:

{
  "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은 OpenAI 명세를 넘어선 Atlas Cloud 확장입니다. 오디오는 인라인 Base64여야 하며, input_audio에는 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"}]
  }'

Anthropic SDK의 base_url을 https://api.atlascloud.ai로 설정하면 Atlas Cloud로 향하게 됩니다.

지원 항목. system(문자열 또는 블록 배열), stop_sequences, input_schema가 포함된 tools, tool_choice, thinking, 이미지 블록(base64와 url 소스 모두), document 블록, tool_result. 어시스턴트의 thinking 블록은 추론 출력으로 매핑됩니다.

알아 두어야 할 차이점:

스트리밍은 Anthropic의 이벤트 순서를 따릅니다: message_start, content_block_start, content_block_delta, content_block_stop, message_delta, message_stop. [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
  }'

지원 항목. instructions, 모든 형태의 input, tools, tool_choice, reasoning.effort, text.format(json_object와 json_schema 모두), text.verbosity, temperature, top_p, stream, parallel_tool_calls.

조용히 무시되는 항목 — 오류 없이 받아들여지지만 아무 효과가 없습니다: previous_response_id, store, include, background, conversation, prompt, truncation, max_tool_calls, top_logprobs, reasoning.summary. metadata는 그대로 돌려주지만 전달되지는 않습니다.

멀티모달. 이미지와 오디오를 지원합니다. 이 프로토콜에서는 동영상을 사용할 수 없습니다. 이미지는 {"type": "input_image", "image_url": "<url string>"} 형태로 지정하며, 값이 객체가 아니라 단순 문자열이라는 점에 유의하세요.

스트리밍은 표준 Responses 이벤트 세트를 내보내며 response.completed, response.incomplete, response.failed 중 하나로 끝납니다. [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"}]}]}'

지원 항목. user와 model 역할을 포함한 contents[], systemInstruction, generationConfig, tools.

멀티모달. 이미지, 동영상, 오디오를 지원합니다 — inline_data로 인라인 전달하거나 file_data.file_uri로 참조할 수 있습니다.

이 프로토콜은 네이티브로 지원하는 모델에서만 제공됩니다. 식별자에 nano, banana, omni가 포함된 모델은 여기서 거부되므로, Chat Completions나 미디어 생성 엔드포인트를 사용하세요.

OpenAI Images

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는 multipart/form-data를 받습니다. 이 프로토콜을 공개하는 모델은 소수에 불과합니다.

게이트웨이 동작

게이트웨이는 요청이 지나갈 때 몇 가지를 정규화합니다. 이는 업스트림 명세에 없는 동작이므로, 응답을 디버깅할 때 예상과 다를 수 있습니다:

지원하지 않는 항목

다음 엔드포인트는 Atlas Cloud에 존재하지 않습니다. 어떤 모델을 지정하더라도 요청은 동작하지 않습니다:

• /v1/embeddings
• /v1/rerank
• /v1/audio/speech와 /v1/audio/transcriptions — 오디오는 오디오 엔드포인트를 거칩니다
• /v1/messages/count_tokens

Ollama, Cohere, Bedrock 같은 제공업체는 네이티브 프로토콜로 노출되지 않습니다. 여러 벤더의 모델을 사용할 수 있지만, 언제나 위의 여섯 가지 형식 중 하나를 통해야 합니다.

요청 제한과 오류

요청 제한은 계정별, 모델별로 적용됩니다. 제한을 초과하면 API는 429를 반환합니다.

모든 응답에는 X-Request-ID 헤더가 포함됩니다. 지원팀에 문의할 때 이 값을 함께 알려 주세요.

관련 문서