OpenAI 호환성

OpenAI 호환성 (OpenAI Compatibility)

이미 OpenAI 파이썬·TypeScript 클라이언트로 애플리케이션을 만들었다면, 코드를 거의 바꾸지 않고 Together에서 호스팅하는 오픈소스 모델을 호출할 수 있어요. API 키와 base URL만 바꾸면 되죠. 아래에서 Together의 OpenAI 호환 레이어를 어떻게 설정하는지, 어떤 엔드포인트가 지원되고 어떤 것이 안 되는지 정리할게요.

출처: 공식문서 - OpenAI compatibility

그대로 끼워 쓰는 클라이언트 설정

api_key에 Together API 키를, base_url에 https://api.together.ai/v1을 설정하면 돼요.

import os
import openai

client = openai.OpenAI(
    api_key=os.environ.get("TOGETHER_API_KEY"),
    base_url="https://api.together.ai/v1",
)

response = client.chat.completions.create(
    model="MiniMaxAI/MiniMax-M3",
    messages=[{"role": "user", "content": "Hello!"}],
)

print(response.choices[0].message.content)

curl https://api.together.ai/v1/chat/completions \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMaxAI/MiniMax-M3",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

API 키는 설정 페이지에서 찾을 수 있어요. 계정이 없다면 무료 등록을 하면 돼요.

model 필드에 Together 모델 ID 중 아무거나 넣으면 돼요. 모델 이름은 OpenAI의 평면 네임스페이스가 아니라 <provider>/<model_name> 관례를 따라요.

엔드포인트 호환성 매트릭스

base URL을 https://api.together.ai/v1로 설정하면 아래 OpenAI SDK 메서드들이 Together 네이티브 엔드포인트로 라우팅돼요.

OpenAI SDK 호출 Together 엔드포인트 상태 기능 페이지
chat.completions.create POST /v1/chat/completions 지원 채팅 개요, 스트리밍, 파라미터
chat.completions.create (비전 입력) POST /v1/chat/completions 지원 Vision
chat.completions.create (tools) POST /v1/chat/completions 지원 함수 호출
chat.completions.create (response_format) POST /v1/chat/completions 지원 구조화된 출력
completions.create POST /v1/completions 지원 레거시 텍스트 완성
embeddings.create POST /v1/embeddings 지원 임베딩
images.generate POST /v1/images/generations 지원 이미지 생성
audio.speech.create POST /v1/audio/speech 지원 텍스트-음성
audio.transcriptions.create POST /v1/audio/transcriptions 지원 음성-텍스트
audio.translations.create POST /v1/audio/translations 지원 음성-텍스트
models.list, models.retrieve GET /v1/models 지원 모델 목록
assistants.*, threads.*, runs.* 해당 없음 미지원 채팅 완성과 함수 호출로 에이전트 루프 구성
fine_tuning.jobs.* (OpenAI 형태) 해당 없음 미지원 Together 네이티브 fine-tuning API 사용
files.* (OpenAI 형태) 해당 없음 부분 지원 파인튜닝 데이터셋·배치용 자체 Files API 존재
batches.* (OpenAI 형태) 해당 없음 미지원 Together 네이티브 Batch API 사용
moderations.create 해당 없음 미지원 채팅 완성으로 Llama Guard 기반 moderation 모델 사용

OpenAI SDK가 노출하지 않는 Together 네이티브 엔드포인트는 requests·fetch·Together SDK로 호출해야 해요.

  • 비디오 생성
  • images.generate를 넘어서는 이미지 편집·인페인팅
  • reasoning 제어와 reasoning_content
  • logprobs 표면

드롭인 호환성 (Drop-in)

아래 기능들은 API 키와 base URL 외에 코드 변경 없이 동작해요.

기능 OpenAI SDK 메서드 기능 페이지
채팅 완성 (스트리밍 포함) chat.completions.create 채팅 개요
비전 (이미지 입력) 이미지 콘텐츠 파트를 가진 chat.completions.create Vision
함수 호출 tools·tool_choice를 가진 chat.completions.create 함수 호출
구조화된 출력 response_format을 가진 chat.completions.create 구조화된 출력
임베딩 embeddings.create 임베딩
이미지 생성 images.generate 이미지 생성
텍스트-음성 audio.speech.create 텍스트-음성
음성-텍스트·번역 audio.transcriptions.create, audio.translations.create 음성-텍스트

비디오 생성은 Together 네이티브라 OpenAI SDK로는 노출되지 않아요.

알려진 비호환성

모델 식별자

Together 모델 ID는 네임스페이스가 붙어요 (openai/gpt-oss-20b, meta-llama/Llama-3.3-70B-Instruct-Turbo, black-forest-labs/FLUX.2-dev). gpt-4o나 text-embedding-3-large 같은 OpenAI 모델 문자열은 404를 반환해요.

구현되지 않은 엔드포인트

  • Assistants, Threads, Runs는 구현되지 않았어요. 함수 호출로 에이전트 루프를 직접 만들어야 해요.
  • OpenAI 형태의 Batch API와 Files API는 /v1에 노출되지 않아요. Together에는 별도 등가물이 있어요.
  • moderations.create는 구현되지 않았어요. 채팅 완성으로 Llama Guard를 쓰면 돼요.

파라미터 특성

  • logprobs는 OpenAI보다 풍부한 Together 자체 형태를 돌려줘요.
  • seed는 best-effort예요. 복제본·모델 버전·부하 조건에 따라 결정성이 보장되지 않아요.
  • n (요청당 여러 완성)은 대부분의 채팅 모델에서 지원되지만 모든 모델은 아니에요. 모델이 거부하면 클라이언트 쪽에서 루프를 돌리세요.
  • logit_bias는 대부분의 모델에서 지원되지 않아요.
  • service_tier, store, metadata, prediction은 받아들이지만 무시돼요.
  • reasoning_effort는 GPT-OSS 모델에서 "low", "medium", "high"로 동작해요. 그 외 reasoning 제어(Together의 reasoning={"enabled": ...} 토글, chat_template_kwargs)는 OpenAI API 표면의 일부가 아니에요.
  • 비전 모델은 image_url에서 원격 URL과 base64 데이터 URI를 모두 받아요. detail 필드는 받아들이지만 무시돼요.

응답 형태 차이

  • usage는 항상 prompt_tokens, completion_tokens, total_tokens를 포함해요. 추가 토큰 카운트는 모델에 따라 위치가 달라지므로 두 형태를 방어적으로 모두 읽어야 해요.
    • Reasoning 모델(zai-org/GLM-5.2, deepseek-ai/DeepSeek-V4-Pro-0813, Qwen/Qwen3.6-Plus 등)은 OpenAI 스타일로 중첩해요. 캐시 프롬프트 토큰은 usage.prompt_tokens_details.cached_tokens, reasoning 토큰은 usage.completion_tokens_details.reasoning_tokens.
    • 일부 비-reasoning 모델(meta-llama/Llama-3.3-70B-Instruct-Turbo)은 cached_tokens를 usage 최상위에 평평하게 돌려주고 *_details 객체는 없어요.
    • 한 형태만 처리하도록 설정된 클라이언트는 다른 형태에 대해 (오류 메시지 없이) 0을 반환해요. 두 위치 모두 폴백하세요. 예: (usage.prompt_tokens_details or {}).get("cached_tokens") or usage.get("cached_tokens", 0).
  • Reasoning 모델은 사고 과정을 어시스턴트 메시지의 reasoning 또는 reasoning_content 필드로 돌려줘요(OpenAI의 중첩 reasoning 객체가 아니에요). 필드 이름은 모델에 따라 달라요. 이전 턴을 API로 보낼 때(사고 보존·멀티턴 도구 호출)는 같은 키 아래로 다시 넘겨주세요.
  • id와 system_fingerprint는 존재하지만 Together 형식을 써요. OpenAI ID로 파싱하지 마세요.
  • images.generate는 OpenAI처럼 response_format 파라미터에 따라 url이나 b64_json을 돌려줘요. 일부 이미지 모델은 Together 전용 메타데이터 필드(예: seed)도 돌려줘요.

오류

Together는 OpenAI 형태의 오류 객체({ "error": { "message", "type", "code" } })를 반환하지만, type과 code 값은 Together의 것이에요. 이식 가능한 처리를 위해 HTTP 상태(400, 401, 404, 429, 500, 503)로 매칭하세요.

커뮤니티 라이브러리

Together API는 커뮤니티가 만든 대부분의 OpenAI 라이브러리에서도 지원돼요. 예상치 못한 동작이 있다면 지원팀에 문의하세요.

더 알아보기 (Learn more)