API 레퍼런스¶

Continuum Router는 OpenAI 호환 API를 제공하며 모니터링과 관리를 위한 추가 관리 엔드포인트도 함께 노출합니다. 이 문서는 사용 가능한 모든 엔드포인트, 요청/응답 형식, 오류 처리에 대한 상세 정보를 담고 있습니다.

개요¶

기본 URL¶

http://localhost:8080

Content Type¶

별도로 명시되지 않는 한 모든 요청과 응답은 application/json을 사용합니다.

OpenAI 호환성¶

Continuum Router는 다음 OpenAI 호환 API 표면을 제공합니다:

• 스트리밍을 포함한 채팅 완료
• 텍스트 완료
• 임베딩
• 리랭킹 (Cohere 호환 /v1/rerank)
• 모더레이션 (/v1/moderations, 설정된 가드레일로 분류)
• System One 결정 (/v1/decisions, 별칭 /v1/systemone)
• 희소 임베딩 (TEI/Jina 호환 /embed_sparse)
• 이미지 생성
• 이미지 편집/인페인팅
• 이미지 변형
• Files API (업로드, 목록, 조회, 삭제)
• 채팅 완료에서의 파일 해결 (image_file 참조)
• 모델 목록
• 오류 응답 형식

x-backend로 백엔드 지정하기¶

여러 백엔드가 동일한 모델 id를 제공할 수 있습니다. /v1/models는 이들을 하나의 통합 항목으로 합치고, 그 항목의 backends 배열에 해당 id를 제공하는 모든 백엔드 이름을 담습니다. 기본 동작은 이들 사이의 부하 분산입니다.

원하는 백엔드를 지정하려면 선택적 요청 헤더 x-backend를 보내십시오.

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-backend: provider-openai-a1b2c3d4" \
  -d '{"model": "gpt-5.6-terra", "messages": [{"role": "user", "content": "안녕하세요"}]}'

적용 범위¶

라우터는 모델로 라우팅하는 모든 추론 엔드포인트(스트리밍·비스트리밍 공통)에서 x-backend를 읽습니다:

• /v1/chat/completions, /v1/completions, /v1/responses
• /anthropic/v1/messages, /anthropic/v1/messages/count_tokens(루트 수준 별칭 /v1/messages, /v1/messages/count_tokens 포함)
• /v1/embeddings, /v1/rerank, /embed_sparse
• /tokenize, /detokenize (및 /v1 별칭)
• /v1/images/generations, /v1/images/edits, /v1/images/variations
• /v1/audio/transcriptions, /v1/audio/translations, /v1/audio/speech
• /v1/realtime WebSocket 핸드셰이크

다음 경로에서는 헤더를 읽지 않습니다:

동작 방식¶

x-backend는 라우팅 선호도이며 고정 핀(pin)이 아닙니다. 다음 네 가지 적격 조건이 모두 충족될 때 첫 시도에 지정한 백엔드가 사용됩니다:

1. 사용자 라우팅 가능: 백엔드가 활성 상태(enabled: true)이고 내부 전용(internal: false)이 아닙니다.
2. 허용 목록 포함: API 키에 allowed_backends 허용 목록이 설정되어 있으면 그 목록에 포함됩니다.
3. 후보 풀 포함: 헤더가 없었을 때 요청이 선택할 수 있었던 백엔드 후보 집합에 속합니다:
   • 모델 기반 라우팅 엔드포인트: 요청한 모델을 제공하는 백엔드들입니다.
   • Nano Banana (Gemini 네이티브) 이미지 요청: 선택된 백엔드의 자격 증명을 실어 Gemini 엔드포인트로 요청을 보내므로, 반드시 type: gemini 백엔드를 지정해야 합니다(백엔드 이름과 URL은 보지 않으며, 비-Gemini 백엔드는 자격 증명을 빌려 쓰지 않고 거부합니다).
   • OpenAI 호환 /v1/images/edits 및 /v1/images/variations: 지정한 백엔드 자신의 URL과 자격 증명으로 직접 요청을 보내므로 기능 필터를 적용하지 않습니다. 가시적이고 allowed_backends를 통과한 백엔드라면 이미지 편집·변형 기능이 없는 백엔드도 지정할 수 있으며, 이 경우 일반 선택으로 폴백하지 않고 해당 백엔드에서 실패합니다.
4. 헬스 및 서킷 브레이커 통과: 백엔드가 정상(healthy) 상태이고 서킷 브레이커가 요청을 허용합니다.

조건 중 하나라도 충족하지 않으면 라우터는 경고를 기록하고 일반 선택 로직으로 폴백합니다. 따라서 헤더가 없거나, 알 수 없거나, 숨겨졌거나, 허용되지 않거나, 비정상인 백엔드 이름을 보내도 요청은 실패하지 않으며 헤더를 보내지 않은 것처럼 동작합니다.

• 첫 시도에만 적용: 재시도와 폴백 체인 홉에는 일반 선택 로직이 적용되므로, 요청 도중 백엔드가 실패해도 정상적으로 페일오버됩니다.
• /v1/realtime 세션: 실시간 세션은 WebSocket 핸드셰이크 시점에 백엔드를 한 번만 선택하며, 세션이 닫힐 때까지 해당 백엔드에 고정됩니다. 두 번째 선택이나 세션 도중 페일오버는 없습니다.

어느 백엔드가 처리했는지 확인하기¶

x-backend를 보낸 요청에는 실제로 응답을 생성한 백엔드 이름을 담은 x-served-backend 응답 헤더가 반환됩니다(재시도나 폴백 체인 이동 이후에는 실제로 응답한 최종 백엔드 이름을 보고합니다):

curl -sS -D - -o /dev/null http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-backend: provider-openai-a1b2c3d4" \
  -d '{"model": "gpt-5.6-terra", "messages": [{"role": "user", "content": "안녕하세요"}]}' \
  | grep -i '^x-served-backend:'

• 보낸 x-backend와 값이 같음: 선호도가 반영되어 지정한 백엔드가 처리했습니다.
• 보낸 x-backend와 값이 다름: 지정한 백엔드가 적격 조건을 충족하지 못했거나(예: 이름 오타, 비정상 상태) 재시도·폴백이 발생해 다른 백엔드가 처리했습니다.
• 헤더가 없음: 업스트림 백엔드가 직접 생성한 응답이 아니거나(아래 표 참고), 해당 경로가 x-backend를 읽지 않는 경우입니다. 헤더가 없는 것을 '선호도가 적용되었다'는 뜻으로 해석하지 마십시오.

백엔드가 돌려준 오류¶

라우터는 요청에 x-backend가 있었고 업스트림 백엔드가 직접 생성한 HTTP 응답(예: 업스트림 429 할당량 초과)을 받았을 때만 x-served-backend를 붙입니다. 라우터가 직접 작성한 응답이나 전송 실패에는 HTTP 상태 코드와 무관하게 이 헤더가 붙지 않습니다.

지원 여부 확인 (backend_preference_header_v1)¶

• Admin API: 라우터가 x-backend를 지원하면 GET /admin/capabilities의 capabilities 배열에 backend_preference_header_v1을 광고합니다(Admin REST API 레퍼런스 참고).
• 추론 API: 일반 추론 요청에 x-backend를 보내고, 캐시되지 않은 성공(200) 응답에 x-served-backend가 있는지 확인하십시오. 헤더가 있으면 라우터가 이 기능을 지원한다는 뜻이며, 보낸 값과 비교해 선호도 적용 여부를 확인할 수 있습니다.

인증¶

Continuum Router는 설정 가능한 적용 모드를 통한 API 키 인증을 지원합니다.

인증 모드¶

라우터는 API 엔드포인트에 대해 두 가지 인증 모드를 지원합니다:

설정¶

api_keys:
  # 인증 모드: "permissive" (기본값) 또는 "blocking"
  mode: blocking

  # API 키 정의
  api_keys:
    - key: "${API_KEY_1}"
      id: "key-production-1"
      user_id: "user-admin"
      organization_id: "org-main"
      scopes: [read, write, files, admin]

보호된 엔드포인트 (mode가 blocking일 때)¶

API 키 미들웨어는 코어 API 라우터의 모든 경로를 보호합니다: /v1/models*, /v1/quota, /v1/chat/completions, /v1/completions, /v1/embeddings, /v1/responses*, /v1/images/*, /v1/rerank, /v1/moderations, /v1/fine_tuning/jobs*, /v1/vector_stores*, /tokenize, /detokenize(및 /v1 별칭), /v1/decisions, /v1/systemone, /embed_sparse, /anthropic/v1/messages*, /v1/messages*, /anthropic/v1/models, 기능 게이트가 적용된 /v1/batches*.

키에 비어 있지 않은 scopes 목록이 있으면 blocking 모드는 라우트의 read 또는 write 등급도 검사합니다. write는 read를 포함하고 admin은 둘 다 포함하며 files는 별도 Files API를 제어할 뿐 /v1 read/write 라우트를 만족하지 않습니다. scopes가 비어 있거나 없으면 기존 호환성을 위해 제한 없음으로 남고 permissive 모드는 인증된 키의 scope가 좁다는 이유만으로 요청을 거부하지 않습니다. 전체 라우트 분류는 보안 & 관리를 참고하세요.

참고: 생존, 준비성, 버전 엔드포인트(/health, /health/ready, /version)는 항상 인증 없이 접근 가능합니다. Admin, Files, Metrics 엔드포인트는 별도의 인증 메커니즘을 가집니다.

키는 prompt_logging_consent(allowed 또는 denied)로 프롬프트 캡처 동의를 나타낼 수도 있습니다. 키의 동의가 오는 곳을 참고하세요.

인증된 요청 만들기¶

보호된 모든 경로는 API 키를 Authorization: Bearer <api_key> 또는 Anthropic 고유의 x-api-key: <api_key> 두 헤더 형식 중 하나로 받습니다. 두 형식 모두 /anthropic/* 엔드포인트뿐 아니라 모든 경로에서 동작하므로 ANTHROPIC_API_KEY만 설정하고 이를 x-api-key로 보내는 Anthropic SDK와 Claude Code도 OpenAI 방식 클라이언트와 동일하게 인증됩니다. 요청에 두 헤더가 모두 있으면 Authorization: Bearer가 우선합니다.

POST /v1/chat/completions HTTP/1.1
Authorization: Bearer sk-your-api-key
Content-Type: application/json

{
  "model": "gpt-5.6-sol",
  "messages": [{"role": "user", "content": "Hello"}]
}

POST /v1/chat/completions HTTP/1.1
x-api-key: sk-your-api-key
Content-Type: application/json

{
  "model": "gpt-5.6-sol",
  "messages": [{"role": "user", "content": "Hello"}]
}

인증 오류¶

인증 실패 시 API는 다음을 반환합니다:

{
  "error": {
    "message": "Missing or invalid API key. Expected Authorization: Bearer <api_key> or x-api-key",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

상태 코드:

• 401 Unauthorized: API 키가 없거나 유효하지 않음

Core API 엔드포인트¶

헬스 체크¶

라우터 서비스의 헬스 상태를 확인합니다.

GET /health

응답:

{
  "status": "ok",
  "service": "continuum-router",
  "version": "2.0.0"
}

상태 코드:

• 200: 서비스가 정상

준비성 체크¶

이 레플리카에 활성화된 비내부 백엔드가 하나 이상 있는지 확인합니다. 드레이닝 중인 백엔드는 세지 않습니다. 업스트림 헬스와 서킷 브레이커 상태는 계속 요청 선택에서 처리하며 이 엔드포인트의 결과를 바꾸지 않습니다.

GET /health/ready

준비 완료 응답:

{
  "status": "ready",
  "service": "continuum-router",
  "routable_backend_count": 2
}

서빙 풀에 라우팅 가능한 백엔드가 없으면 같은 본문에서 "status": "not_ready", 개수 0을 반환합니다.

상태 코드:

• 200: 활성화된 비내부 백엔드가 하나 이상 활성 상태
• 503: 활성화된 비내부 백엔드가 없음

버전¶

실행 중인 라우터 버전을 반환합니다.

GET /version

응답:

{
  "version": "2.0.0"
}

상태 코드:

• 200: 항상 반환되며 인증이 필요하지 않음

호출자 할당량¶

GET /v1/quota는 호출자가 인증한 신원에 묶인 한도와 각 한도의 남은 양을 반환합니다. 매개변수와 본문이 없고, 신원에 묶인 할당량을 소비하지 않으므로 조회한 값을 쓰지 않고 반복해서 호출할 수 있습니다.

응답에는 호출자 신원에 묶인 값만 담깁니다. 공유 함대 한도(global, per_client, per_model, per_backend), 배치 차원, 키 ID·이름·사용자·팀은 포함되지 않습니다.

{
  "object": "quota",
  "degraded": false,
  "dimensions": [
    {"dimension": "request_rate", "unit": "requests", "limit": 20, "remaining": 17, "reset_seconds": 9, "window_seconds": null, "scope": "replica"},
    {"dimension": "token_rate", "unit": "tokens", "limit": 20000, "remaining": 18400, "reset_seconds": 6, "window_seconds": null, "scope": "fleet"},
    {"dimension": "token_budget", "unit": "tokens", "limit": 5000000, "remaining": 4100000, "reset_seconds": null, "window_seconds": 2592000, "scope": "replica"}
  ]
}

scope는 값이 유효한 범위를 나타냅니다. 모든 레플리카가 공유하는 스토어에서 읽은 값은 fleet, 그 밖의 값은 replica입니다. request_rate, user_request_rate, team_request_rate, inflight, token_budget은 레플리카별입니다. 설정된 공유 스토어에 연결할 수 없어 이 레플리카 값으로 대체했거나 rate_limiting.redis.fallback_to_memory에 따라 Redis 속도 제한 스토어가 폴백했으면 degraded가 true입니다.

호출자별 응답:

한도에 도달한 키도 거부되지 않고 remaining: 0과 함께 200을 받습니다. 공유 global과 per_client 상한은 /v1/models 비용인 0.1로 계속 차감되므로 이 경로도 다른 API 경로처럼 인증 전에 계량됩니다. 다만 두 값의 수준은 보고하지 않습니다. 할당량 응답에는 x-ratelimit-* 또는 x-continuum-ratelimit-* 헤더가 없습니다.

상태 코드:

• 200: 할당량 조회. dimensions가 비어 있을 수 있음
• 401: blocking 모드에서 키가 없거나 유효하지 않음
• 403: 키 scope에 read가 없음
• 429: 공유 global 또는 per_client 상한이 조회를 거부함
• 503: rate_limiting.redis.fallback_to_memory: false이고 Redis 스토어에 연결할 수 없음

읽기 동작과 장애 시 동작은 속도 제한을 참고하세요.

모델 목록¶

구성에서 활성화된 백엔드의 통합 모델 카탈로그를 조회합니다.

GET /v1/models

응답:

{
  "object": "list",
  "data": [
    {
      "id": "gpt-5.6-sol",
      "object": "model",
      "created": 1677610602,
      "owned_by": "openai",
      "context_length": 400000,
      "max_output_tokens": 128000,
      "pricing": {
        "input_tokens": 1.25,
        "output_tokens": 10.0
      },
      "capabilities": ["chat", "vision", "tool"],
      "supported_parameters": ["temperature", "top_p", "max_tokens", "presence_penalty", "frequency_penalty", "logprobs", "top_logprobs"]
    },
    {
      "id": "llama2:7b",
      "object": "model",
      "created": 1677610602,
      "owned_by": "library",
      "context_length": 4096,
      "max_output_tokens": 4096,
      "supported_parameters": ["temperature", "top_p", "max_tokens", "presence_penalty", "frequency_penalty", "top_k", "min_p", "logprobs", "top_logprobs"]
    },
    {
      "id": "anthropic/claude-haiku-4.5",
      "object": "model",
      "created": 1760547638,
      "owned_by": "anthropic",
      "context_length": 200000,
      "max_output_tokens": 64000,
      "pricing": {
        "input_tokens": 1.0,
        "output_tokens": 5.0
      },
      "capabilities": ["chat", "vision", "tool"],
      "supported_parameters": ["temperature", "top_p", "max_tokens", "presence_penalty", "frequency_penalty", "top_k", "min_p", "logprobs", "top_logprobs"]
    }
  ]
}

상태 코드:

• 200: 모델이 성공적으로 조회됨
• 503: 모든 백엔드가 비정상

기능:

• 모델 집계: 구성에서 활성화된 백엔드의 모델을 결합
• 중복 제거: 백엔드 간 중복 모델 제거
• 캐싱: 내부 60초 하드 TTL, stale-while-revalidate 및 요청 병합 사용
• 장애 시 유지: 실시간 검색에 실패하면 라우터는 해당 백엔드의 마지막으로 확인된 모델을 카탈로그에 유지합니다. 설정이나 대체 목록(Bedrock, OAuth 백엔드, 내장 Anthropic 목록)으로 채운 검색 결과는 백엔드를 정상으로 표시하지 않으며, 실제 응답을 받은 경우에만 정상으로 표시합니다.
• 호출 가능한 모델만 노출: 호출자가 지금 요청할 수 있는 모델만 목록에 나옵니다. 기준은 다음과 같습니다.
  • 호출자의 키가 사용할 수 있는 백엔드 중 하나 이상이 비정상(unhealthy)으로 판정되지 않았습니다. 아직 검사 전이거나 워밍업 중인 백엔드는 사용 가능한 것으로 봅니다.
  • 또는 모델 이름에 활성화된 폴백 체인이 구성되어 있습니다. 이 경우 성능이 저하된 기본 모델도 계속 보이므로, 이 엔드포인트로 모델 선택기를 구성하는 클라이언트도 폴백에 도달할 수 있습니다.
  • 둘 다 아니면 백엔드가 복구될 때까지 목록에서 빠집니다. 이때도 GET /v1/models/{model}은 available: false와 함께 200을 반환하고, GET /admin/models는 해당 모델을 degraded로 표시합니다. /v1/models/extended, /v1/models/refresh, /anthropic/v1/models에도 같은 기준이 적용됩니다.
• 백엔드 별칭: 활성화된 백엔드의 model_configs에 선언된 aliases 항목은 별칭 디스패치가 그 이름을 해석하는 동안 별도 항목으로 목록에 나오며, 정규 모델의 backends와 메타데이터를 그대로 가집니다.
  • 사용자가 라우팅할 수 있는 백엔드가 정규 모델을 제공하는 동안에만 나오고, 정규 모델이 빠지는 새로고침에서 함께 빠집니다.
  • 키별 allowed_models 목록에는 별칭 자체가 있어야 합니다. 백엔드 허용 목록, 내부 백엔드, 호출 가능 모델 기준은 정규 모델의 백엔드를 기준으로 적용됩니다.
  • 어떤 백엔드가 그 이름을 그대로 제공하면 해당 항목이 유지되고, 모델 실험이 응답하는 이름은 실험이 처리합니다.
  • model-metadata.yaml의 별칭과 model_aliases 섹션(haiku, sonnet, exact 등)은 목록에 나오지 않습니다. GET /admin/models는 선언된 별칭을 정규 항목의 aliases에 표시합니다.
• 공급사 표시: OpenRouter처럼 백엔드가 vendor/model ID에 owned_by를 보내지 않으면 ID의 공급사 네임스페이스를 owned_by로 사용합니다(anthropic/claude-haiku-4.5는 anthropic). 업스트림 공급사와 메타데이터를 참고하세요.

• 기능 메타데이터: 라우터가 값을 아는 모델에는 다음 필드가 함께 나옵니다. 값의 출처는 라우터가 확정한 모델 메타데이터(model-metadata.yaml, 백엔드가 보고한 값, 내장 카탈로그 항목)입니다.

  • context_length: 컨텍스트 창(토큰)
  • max_output_tokens: 최대 출력 토큰 수
  • pricing: 100만 토큰당 USD 단가
  • capabilities: chat, vision, tool 같은 기능 태그
  • supported_parameters: 라우터가 백엔드까지 전달하는 채팅 요청 파라미터로 temperature, top_p, max_tokens, presence_penalty, frequency_penalty, top_k, min_p, logprobs, top_logprobs 중에서 고릅니다. 모델을 제공하는 각 백엔드의 변환 규칙에서 도출합니다(로컬 엔진과 OpenAI 호환 원본 백엔드는 모두 전달하고 api.openai.com과 Gemini는 top_k와 min_p를 제외하며, Anthropic과 Bedrock은 temperature, top_p, max_tokens, top_k를 전달하되 샘플링 필드를 거부하는 Claude 모델에는 max_tokens만 전달하고 Bedrock Converse는 top_k도 제외합니다). 모델을 제공하는 모든 백엔드가 전달하는 파라미터만 나열합니다. capabilities에 chat도 업스트림 카탈로그가 보고하는 text 출력 모달리티도 없는 모델(예: 이미지나 임베딩 모델)에는 supported_parameters가 없습니다. 요청 형태에 따라 범위가 더 좁아지는 경우(예: reasoning을 담은 Claude 요청은 temperature를 제외)는 반영하지 않습니다.

  model-metadata.yaml 항목이 limits를 지정하지 않으면 context_length는 모델을 제공하는 엔진이 보고한 컨텍스트 창(/v1/models의 max_model_len 또는 context_length)에서 가져오며, 어느 백엔드든 요청을 처리할 수 있으므로, 백엔드 간 최솟값을 씁니다. 값을 알 수 없는 필드는 null로 보내지 않고 생략합니다. 메타데이터도 엔진 보고도 없는 모델은 id, object, created, owned_by, supported_parameters만 가집니다.

메타데이터 포함 모델 목록¶

GET /v1/models와 같은 통합 카탈로그를 조회하되, 라우터가 확정한 메타데이터와 각 모델을 제공하는 백엔드를 함께 반환합니다.

GET /v1/models/extended

응답:

{
  "object": "list",
  "data": [
    {
      "id": "qwen3-32b",
      "object": "model",
      "created": 1700000000,
      "owned_by": "vllm",
      "backends": ["vllm-large", "vllm-small"],
      "metadata": {
        "limits": {
          "context_window": 32768,
          "max_output": 32768
        }
      },
      "max_model_len": 32768,
      "root": "Qwen/Qwen3-32B"
    }
  ]
}

필드:

업스트림 필드: 그 밖의 최상위 키는 해당 모델에 대한 한 백엔드의 /v1/models 항목에서 복사됩니다(백엔드가 여럿이면 어느 백엔드인지는 정해져 있지 않습니다). 이 키들은 계약이 아니라 그대로 전달되는 값입니다. 백엔드가 보낸 경우에만 나타나며 그 백엔드의 형태를 유지합니다. 라우터가 직접 직렬화하는 키(id, object, created, owned_by, backends, metadata, tier, domains)는 업스트림에서 가져오지 않습니다.

어느 값이 기준인가: metadata가 라우터의 답이며 라우터가 실제로 따르는 값입니다. 업스트림 필드가 metadata와 같은 내용을 다시 표시하면 metadata를 읽으세요.

• 컨텍스트 윈도는 라우터가 맞춰 주는 유일한 예외입니다. max_model_len(vLLM 계열 엔진)과 context_length(OpenRouter 같은 애그리게이터)는 존재할 때 metadata.limits.context_window 값으로 다시 쓰이므로 객체가 윈도를 두 개 표시하지 않습니다. 이 윈도는 메타데이터가 limits를 제공하면 운영자가 설정한 값이고 그렇지 않으면 요청이 어느 백엔드로든 갈 수 있으므로 제공 백엔드들이 보고한 값의 최솟값입니다. 백엔드가 보내지 않은 키는 추가하지 않으며 게시된 context_window가 0(해당 없음)이면 다시 쓰지 않습니다.
• 그 밖의 업스트림 키는 그대로 유지됩니다. 특히 애그리게이터의 pricing(토큰당 USD, 문자열)과 top_provider.max_completion_tokens는 업스트림이 보낸 그대로 두며 백엔드 전체에 걸쳐 결합한 라우터의 값은 metadata.pricing(100만 토큰당 USD)과 metadata.limits.max_output에 있습니다. 업스트림 공급사와 메타데이터를 참고하세요.

상태 코드:

• 200: 모델이 성공적으로 조회됨
• 503: 모든 백엔드가 비정상

모델 필터 조회¶

capability와 컨텍스트 길이 조건으로 카탈로그를 서버 측에서 필터링합니다. 이 엔드포인트는 GET /v1/models/extended와 같은 모델 객체를 반환하되, 카탈로그가 명시된 모든 조건을 충족한다고 증명할 수 있는 모델만 남깁니다. 조건을 충족하는 모델이 없으면 에러가 아니라 빈 data 배열의 성공 응답을 돌려줍니다.

POST /v1/models/query

요청 바디 (모든 필드는 선택적입니다. 바디가 없거나 비어 있으면 보이는 모든 모델을 선택하므로, 이 경우 엔드포인트는 GET /v1/models/extended와 동일하게 동작합니다):

{
  "capabilities": ["chat", "vision"],
  "min_context_length": 64000,
  "max_output": 4096,
  "q": "gpt",
  "limit": 20
}

필드:

필터는 같은 호출자에게 GET /v1/models/extended가 반환하는 목록(별칭과 실험 이름, 호출자의 backend/model allow-list, internal 백엔드 필터, 라우팅 가능 여부 필터까지 적용한 목록)에 그대로 적용됩니다. 따라서 쿼리는 그 목록을 좁히기만 합니다.

검증:

• capability는 capabilities의 다른 표기로 받으며, 마찬가지로 배열을 받습니다. 두 표기를 함께 쓴 바디는 400(invalid_query)을 반환합니다.
• 알 수 없는 필드는 400(invalid_query)으로 거부합니다. 필드 이름을 잘못 써도 모든 모델이 반환되지 않습니다.
• capabilities는 각 1~64바이트인 항목을 최대 32개까지 받습니다. 대소문자를 구분해 정확히 일치하는 값만 매칭합니다.
• q는 1~256바이트여야 합니다.
• limit은 1~1000이어야 합니다.
• 바디 크기는 16 KiB로 제한하며, 더 큰 바디는 413을 반환합니다.
• 스코프: 다른 모델 목록과 마찬가지로 read API 키 스코프가 필요합니다. 상태를 바꾸지 않고 추론도 보내지 않기 때문입니다.

예시:

curl -s -X POST http://localhost:8080/v1/models/query \
  -H 'Content-Type: application/json' \
  -d '{"capabilities":["vision"],"min_context_length":64000}'

상태 코드:

• 200: 필터링된 모델 목록 반환 (비어 있을 수 있음)
• 400: 요청 바디가 있지만 유효한 쿼리가 아님 (OpenAI 형식 오류 객체, 코드 invalid_query)
• 413: 요청 바디가 16 KiB를 넘음
• 503: 모든 백엔드가 비정상

백엔드 모델 목록 프록시¶

모든 백엔드를 집계하지 않고 선택된 적격 백엔드 하나의 원본 /v1/models 응답을 반환합니다. 이 호환 엔드포인트에는 일반 백엔드 선택, 재시도, 상태 및 호출자 백엔드 가시성 규칙이 적용됩니다.

GET /v1/models/proxy

라우터가 중복 제거한 통합 카탈로그에는 GET /v1/models를 사용하십시오. 단일 백엔드의 제공자 네이티브 모델 목록 페이로드가 필요한 클라이언트에만 이 엔드포인트를 사용하십시오.

상태 코드:

• 200: 선택된 백엔드 응답 반환
• 502: 백엔드 연결 또는 게이트웨이 오류
• 503: 적격 정상 백엔드 없음

모델 강제 새로고침¶

구성된 모든 백엔드에서 동기적으로 다시 집계하고 모델 집계 캐시를 교체합니다. 백엔드를 검색할 수 없으면 성공한 백엔드의 최신 결과를 우선하면서 해당 백엔드의 마지막으로 확인된 모델을 유지합니다. 반환되는 목록에는 GET /v1/models와 같은 호출 가능 모델 기준이 적용됩니다. GET /v1/models와 동일한 OpenAI 호환 모델 목록 형태를 반환하므로 호출자가 응답을 바로 사용할 수 있습니다.

이 엔드포인트는 데스크톱 클라이언트의 대화형 '새로고침' 동작 (예: backend.ai-go의 '모델 새로고침' 버튼)을 위해 설계되었습니다. stale-while-revalidate와 소프트 TTL 윈도우를 우회하여, 응답하기 전에 모든 백엔드에서 업스트림 가져오기를 트리거합니다.

POST /v1/models/refresh

응답:

{
  "object": "list",
  "data": [
    {
      "id": "gpt-5.6-sol",
      "object": "model",
      "created": 1677610602,
      "owned_by": "openai-compatible"
    }
  ]
}

상태 코드:

• 200: 새로고침이 완료되고 갱신된 모델 목록이 반환됨
• 429 Too Many Requests: 강제 새로고침 속도 제한 초과 (5초 버스트 윈도우당 3 요청, 분당 12 요청)

속도 제한:

이 엔드포인트는 호출할 때마다 구성된 모든 백엔드에서 업스트림 가져오기가 트리거되기 때문에 일반 GET /v1/models보다 더 엄격한 예산을 적용합니다. 기본 제한은 5초 윈도우당 3 요청, 분당 12 요청입니다. 유효한 API 키는 API 키 ID를 기준으로 별도의 버킷을 받습니다. 익명 호출자와 유효하지 않은 bearer 토큰을 사용한 요청은 하나의 전역 익명 버킷을 공유하므로, Authorization, X-Forwarded-For, X-Real-IP 헤더를 위조해도 강제 새로고침 예산을 우회할 수 없습니다. 제한을 초과한 클라이언트는 429를 받으며 재시도 전에 기다려야 합니다.

캐시 정책:

모델 목록 캐시는 현재 내부 고정 기본값인 60초 하드 TTL, 80% 소프트 TTL, stale-while-revalidate, 요청 병합, 제한된 빈 결과 백오프를 사용합니다. 이 값과 강제 새로고침 사용 여부는 공개 설정 스키마의 필드가 아닙니다.

단일 모델 조회¶

특정 모델의 정보를 가용성 상태, 그리고 선택적으로 제공되는 풍부한 메타데이터와 함께 조회합니다.

GET /v1/models/{model}

경로 파라미터:

응답 (기본):

{
  "id": "gpt-5.6-sol",
  "object": "model",
  "created": 1677610602,
  "owned_by": "openai",
  "available": true
}

응답 (확장 메타데이터 포함):

model-metadata.yaml에 모델 메타데이터가 있으면 응답에 추가 필드가 포함됩니다. OpenRouter 같은 OpenAI 호환 애그리게이터가 제공하는 모델은 설정된 메타데이터에 limits가 없을 때 업스트림 카탈로그가 limits(와 그에 따른 max_tokens)를 보고할 수 있으며 백엔드 자체 model_configs에 가격이 없으면 업스트림 가격이 공유 model-metadata.yaml이나 내장 카탈로그의 가격을 대체합니다. GET /v1/models/extended는 같은 metadata와 함께 업스트림의 원본 필드도 제공합니다. 업스트림 공급사와 메타데이터를 참고하세요:

{
  "id": "gpt-5.6-sol",
  "object": "model",
  "created": 1704067200,
  "owned_by": "openai",
  "available": true,
  "supported_methods": ["chat.completions"],
  "features": ["chat", "vision", "code", "reasoning", "tool"],
  "max_tokens": 128000,
  "metadata": {
    "display_name": "GPT-5.6 Sol",
    "developer": "OpenAI",
    "summary": "Frontier GPT-5.6 model for complex professional work.",
    "knowledge_cutoff": "2026-02",
    "relative_speed": 3,
    "pricing": {
      "input_tokens": 5.0,
      "output_tokens": 30.0
    },
    "limits": {
      "context_window": 1050000,
      "max_output": 128000
    }
  }
}

응답 필드:

메타데이터 객체 필드:

이미지 모델의 limits 객체는 토큰 한도와 함께 선택 이미지 키를 담는다. 모두 API 소비자를 위한 참고 정보다. 라우터는 이미지 요청 제한을 모델 계열별로 코드에서 강제하며 이 값을 읽지 않는다. dall-e-3는 다음과 같이 제공한다.

"limits": {
  "context_window": 0,
  "max_output": 0,
  "max_prompt_length": 4000,
  "supported_sizes": ["1024x1024", "1792x1024", "1024x1792"],
  "max_n": 1,
  "supported_qualities": ["standard", "hd"],
  "supported_styles": ["vivid", "natural"]
}

선택 limits 키는 값이 없으면 응답에서 아예 빠진다. 토큰 모델의 limits 객체는 이 필드들이 추가되기 전과 똑같이 직렬화된다.

아티팩트 식별 정보¶

artifact와 draft_model은 운영자가 model_configs나 메타데이터 계층에 선언한 자체 호스팅 모델에만 나타나며 내장 OpenAI 카탈로그가 설명하는 모델에는 나타나지 않는다. metadata의 다른 키와 마찬가지로 설정된 backends 순서에서 첫 번째 서빙 백엔드의 항목에서 가져오므로 뒤쪽 백엔드의 model_configs 오버라이드는 여기서 보이지 않는다. GET /admin/models는 모든 서빙 백엔드의 식별 정보를 artifacts에 나열하고 각 사용량 레코드는 실제로 응답한 백엔드의 식별 정보를 담는다. artifact.source는 모든 호출자에게 그대로 반환되므로 운영자는 여기에 사전 서명된 URL이나 토큰이 담긴 URL이 아닌 안정적인 공개 위치를 선언해야 한다.

"metadata": {
  "display_name": "Qwen 3.8 27B",
  "artifact": {
    "digest": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
    "registry_version": "v2.1-fp8",
    "revision": "4c2e9a1",
    "source": "hf://Qwen/Qwen3.8-27B-FP8"
  },
  "draft_model": {
    "name": "qwen3.8-0.6b"
  }
}

가격 객체 필드¶

input_tokens와 output_tokens는 1,000,000 토큰 기준이며 벤더가 정가를 표기하는 단위와 같다. smart_routing의 cost_per_1k_input_tokens는 1000 토큰 기준이므로 서로 다르다. 변환하려면 1000으로 나눈다.

long_context는 threshold_tokens, input_tokens, output_tokens로 구성됩니다. 프롬프트가 임계값과 같으면 기본 요율을 사용하고, 임계값을 넘으면 두 티어 요율을 요청 전체에 적용합니다. 이 필드는 API 소비자를 위한 메타데이터이며 라우터의 스마트 라우팅 티어 추론은 계속 기본 입력 요율을 사용합니다.

"pricing": {
  "input_tokens": 0.1,
  "output_tokens": 0.5,
  "long_context": {
    "threshold_tokens": 100000,
    "input_tokens": 0.5,
    "output_tokens": 2.5
  }
}

image_input_tokens와 cached_image_input_tokens는 텍스트 요율을 대체하지 않고 함께 쓰인다. gpt-image-2는 텍스트 입력을 input_tokens로, 이미지 입력을 image_input_tokens로 과금한다.

"pricing": {
  "input_tokens": 5.0,
  "output_tokens": 30.0,
  "cached_input_discount": 0.75,
  "image_input_tokens": 8.0,
  "cached_image_input_tokens": 2.0
}

per_image 값은 생성된 이미지 한 장당 USD로, 위 필드들과는 단위가 다르다. 키는 크기(1024x1024)이거나 티어 이름(ultra)이고 값은 단일 가격이거나 품질별 중첩 맵이다. 세 가지 형태를 모두 제공한다.

"per_image": {"1024x1024": 0.02, "512x512": 0.018, "256x256": 0.016}

"per_image": {"fast": 0.02, "standard": 0.04, "ultra": 0.06}

"per_image": {
  "1024x1024": {"standard": 0.04, "hd": 0.08},
  "1792x1024": {"standard": 0.08, "hd": 0.12}
}

이미지 단위로 과금하는 모델은 input_tokens: 0, output_tokens: 0을 보고한다. 이 0은 카탈로그에 실제로 적힌 값이며 데이터 누락이 아니다. per_image가 있다는 사실 자체가 해당 모델의 과금 축이 토큰이 아니라는 신호다. 클라이언트는 토큰 요율 0을 가격으로 표시하기 전에 per_image 존재 여부를 확인해야 한다.

위 선택 필드는 값이 없으면 응답에서 아예 빠진다. 토큰 가격만 있는 모델은 이 필드들이 추가되기 전과 똑같이 직렬화된다.

지원 메서드 매핑:

supported_methods 필드는 모델 기능에서 도출됩니다:

상태 코드:

• 200: 모델이 조회되어 정보가 반환됨
• 404: 구성된 모든 백엔드에 해당 모델이 존재하지 않음

기능:

• OpenAI 호환: 응답 형식이 OpenAI API와 일치하며 추가 확장 필드를 포함
• 헬스 인식: available 필드는 실시간 백엔드 헬스 상태를 반영
• 프라이버시: 내부 백엔드 정보를 노출하지 않음
• 선택적 메타데이터: 확장 필드는 메타데이터가 있을 때만 존재
• 풍부한 메타데이터: 클라이언트 측 모델 선택에 참고할 수 있도록 표시 이름, 개발사, 기능, 컨텍스트 윈도우 제한을 포함

모델 가용성 알고리즘:

available 필드는 다음 알고리즘으로 결정됩니다:

알고리즘은 단락 평가를 사용합니다: 첫 번째 정상 백엔드를 찾는 즉시 true를 반환하므로 나머지 백엔드에 대한 불필요한 헬스 체크를 피합니다. 백엔드가 대체로 정상일 때 성능이 최적화됩니다.

성능 최적화:

• 빠른 경로: 모델 캐시가 유효하면 조회는 O(n) (n = 모델 수)
• 느린 경로: 캐시가 비어 있거나 만료되었으면 캐시 스탬피드를 방지하는 singleflight 보호와 함께 일회성 집계를 트리거
• Stale-While-Revalidate: 캐시가 백그라운드에서 갱신되는 동안 오래된 데이터를 제공

요청 예시:

curl http://localhost:8080/v1/models/gpt-5.6-sol

응답 예시 (전체 메타데이터와 함께 모델 사용 가능):

{
  "id": "gpt-5.6-sol",
  "object": "model",
  "created": 1704067200,
  "owned_by": "openai",
  "available": true,
  "supported_methods": ["chat.completions"],
  "features": ["chat", "vision", "code", "reasoning", "tool"],
  "max_tokens": 128000,
  "metadata": {
    "display_name": "GPT-5.6 Sol",
    "developer": "OpenAI",
    "summary": "Frontier GPT-5.6 model for complex professional work, with text and image input.",
    "knowledge_cutoff": "2026-02",
    "relative_speed": 3,
    "pricing": {
      "input_tokens": 5.0,
      "output_tokens": 30.0
    },
    "limits": {
      "context_window": 1050000,
      "max_output": 128000
    }
  }
}

응답 예시 (확장 메타데이터가 없는 모델):

model-metadata.yaml에 메타데이터가 없는 모델은 기본 필드만 반환됩니다:

{
  "id": "custom-model",
  "object": "model",
  "created": 1677610602,
  "owned_by": "local",
  "available": true
}

응답 예시 (모델 존재하지만 사용 불가):

{
  "id": "gpt-5.6-sol",
  "object": "model",
  "created": 1704067200,
  "owned_by": "openai",
  "available": false,
  "supported_methods": ["chat.completions"],
  "features": ["chat", "vision", "code", "reasoning", "tool"],
  "max_tokens": 128000,
  "metadata": {
    "display_name": "GPT-5.6 Sol",
    "developer": "OpenAI"
  }
}

채팅 완료¶

OpenAI Chat API 형식을 사용하여 채팅 완료를 생성합니다.

POST /v1/chat/completions

요청 본문:

{
  "model": "gpt-5.6-luna",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "Explain quantum computing in simple terms."
    }
  ],
  "temperature": 0.7,
  "max_tokens": 150,
  "top_p": 1.0,
  "frequency_penalty": 0.0,
  "presence_penalty": 0.0,
  "stream": false,
  "stop": null,
  "logit_bias": {},
  "user": "user123"
}

파라미터:

클라이언트 provider 기본 설정¶

proxy.client_provider_preferences: true이면 클라이언트가 요청 본문에 OpenRouter의 provider 객체를 보내 이 요청이 사용할 수 있는 백엔드를 좁히고 정렬할 수 있습니다. 이 객체는 선택 사항입니다. 스위치가 꺼져 있으면(기본값) 지금과 똑같이 그대로 전달되므로, generic 백엔드 뒤의 애그리게이터 백엔드도 그대로 객체를 받습니다.

지원 필드:

보안과 우선순위:

• 후보 집합은 다음 순서로 만들어집니다. 먼저 백엔드 가시성(internal, enabled), 다음으로 키의 allowed_models와 allowed_backends, 다음으로 Hub와 정책의 축소, 마지막으로 클라이언트의 provider 필터입니다. 기본 설정은 이 집합을 좁히거나 순서를 바꿀 수만 있으며, 허용 목록을 넓히거나 보이지 않거나 비활성화된 백엔드를 도달 가능하게 만들 수 없습니다.
• only, ignore, order에 후보 집합 밖의 백엔드를 적어도 아무것도 넓히지 않습니다. 비어 있지 않은 후보 집합을 비우는 필터, 예를 들어 교집합이 빈 only는 400 invalid_request_error로 응답하며 해당 필드(provider.only, provider.ignore, provider.max_price)를 지목하고 아무 데도 디스패치하지 않습니다. 필터 이전부터 비어 있던 집합은 기존처럼 503입니다.
• x-backend는 여전히 첫 시도 고정이며 provider보다 우선합니다. 그 첫 시도 뒤의 재시도에는 provider 객체가 다시 적용됩니다.
• provider 객체를 담은 요청은 다른 요청의 진행 중인 디스패치에 합류하지 않습니다. 중복 제거는 디스패치되는 본문으로 키를 만들고 라우터는 그 본문에서 provider를 제거하므로, 기본 설정만 다른 두 요청이 하나의 디스패치를 공유해 한쪽이 자신이 배제한 백엔드의 응답을 받을 수 있기 때문입니다. 따라서 이 기본 설정이 있으면 요청은 자기 디스패치 하나를 더 치릅니다.
• 스위치가 켜져 있으면 라우터가 객체를 소비해 제거하므로 어떤 백엔드도 이를 받지 않습니다. 운영자는 backends[].request_extensions.body.overrides.provider로 이 객체를 이해하는 백엔드에 provider 객체를 보낼 수 있으며, 이 값은 클라이언트 키를 제거한 뒤 디스패치 시점에 적용됩니다. request_extensions.body.defaults.provider로는 제거된 클라이언트 객체를 복원할 수 없습니다. 기본값은 비어 있는 키만 채우기 때문입니다. 따라서 정적 운영자 설정이 클라이언트 객체보다 우선하며, 클라이언트 객체가 업스트림에 원문 그대로 도달하는 일은 없습니다.
• 스위치가 꺼져 있으면 아무것도 달라지지 않습니다. 객체는 지금처럼 그대로 전달됩니다.

거부하는 필드: 알 수 없는 필드는 필드 이름(provider.<field>)을 지목하는 400입니다. 이 라우터가 구현하지 않은 OpenRouter 필드(allow_fallbacks, quantizations 등)도 포함합니다. 조용히 무시된 라우팅 기본 설정은 거부된 것보다 나쁩니다. 같은 이유로 알려진 OpenRouter 필드 두 개는 이름을 밝혀 거부합니다. 라우터는 모든 요청 파라미터가 모든 후보의 변환을 거쳐 살아남는다고 보장할 수 없으므로 require_parameters: true를 받지 않고, 백엔드별 데이터 수집 메타데이터가 없으므로 data_collection: "deny"를 받지 않습니다.

검증 한도: 직렬화한 객체는 16 KiB로 제한합니다. 각 이름 목록은 16개 항목으로 제한하며, 각 이름은 1~128바이트이고 앞뒤 공백과 제어 문자를 허용하지 않습니다. 중복은 첫 등장만 남겨 합칩니다. provider는 JSON 객체여야 합니다. 객체 파싱을 거부할 때는 param: "provider"를 담은 400 invalid_request_error로 응답합니다. 후보 집합이 채울 수 없는 필터도 같은 상태와 타입으로 응답하며, 메시지에 해당 필드를 밝힙니다.

순위 대체 동작: sort와 order는 확인된 데이터로만 순위를 정합니다. 최신 엔진 스냅숏이 없거나 기록된 지연 시간이 없는 후보는 뒤의 한 순위 그룹에 합류하고, 텔레메트리가 전혀 없는 플릿은 그룹이 하나가 됩니다. 이때 선택은 정확히 설정된 selection_strategy를 따릅니다. 즉 기본 설정은 없는 데이터로 순서를 바꾸지 않습니다. max_price는 더 엄격합니다. 가격을 확인할 수 없으므로 가격이 없는 후보는 제외합니다.

확인된 모든 키에서 동률인 후보는 하나의 순위 그룹을 이룹니다. 곧 order상 위치(또는 목록에 없음)가 같고, sort가 있으면 그 값도 같은 후보의 집합입니다. 설정된 selection_strategy가 그 그룹 안에서 고르므로 같은 가격이나 같은 순서 등급에서도 첫 후보에 고정되지 않고 순환합니다.

Anthropic Messages 인그레스는 스위치가 켜져 있을 때 최상위 provider 키를 조용히 버리지 않고 400으로 거부합니다. 이 인그레스는 클라이언트 라우팅 기본 설정을 적용하지 않기 때문입니다.

입력 컨텍스트 제한¶

라우터는 입력 토큰 추정치가 라우팅된 모델의 context_window 이상이면 백엔드 전송 전에 요청을 거절합니다. 버퍼 응답과 스트리밍 응답 모두 400 invalid_request_error와 context_length_exceeded 코드를 반환하며, 메시지에 윈도우와 입력 토큰 추정치를 표시합니다. 출력 토큰 예산이 없어도 적용합니다.

기본 설정에서는 거절 시 더 큰 모델로 fallback하지 않습니다. fallback.fallback_policy.trigger_conditions.context_window_exceeded: true이면 라우터가 디스패치 전에 입력을 담을 수 있는 첫 번째 설정 체인 대상으로 홉하며, 적합한 대상이 없을 때만 원래 거절 응답을 반환합니다. 자세한 내용은 컨텍스트 윈도우 폴백을 참고하세요.

추정에는 메시지와 도구 스키마를 포함하며, fallback 허용 판단과 같은 일반 추정 방식을 사용합니다. 모델 라우팅과 선택적 컨텍스트 압축 후 계산하며, 모델별 토크나이저의 정확한 결과는 아닙니다. 컨텍스트 제한이 없거나 0이면 요청을 통과시킵니다.

허용된 서빙 백엔드별로 설정된 제한이 캐시된 엔진 보고보다 우선합니다. fallback 허용 판단과 마찬가지로, 다른 백엔드의 윈도우가 더 크거나 미확인이어도 확인된 양수 윈도우 중 최솟값을 적용합니다. 출력 예산 검증보다 보수적인 정책입니다. 메타데이터가 실제 백엔드 윈도우보다 작다면 모델 메타데이터를 수정해야 기존에 성공하던 요청을 다시 처리할 수 있습니다.

백엔드별 유효한 reasoning_effort 값:

• OpenAI O-series (o1, o3, o4-mini): low, medium, high
• OpenAI GPT-5 (mini/nano 포함): minimal, low, medium, high
• OpenAI GPT-5.1: none, low, medium, high
• OpenAI GPT-5.2 ~ GPT-5.5: none, low, medium, high, xhigh
• OpenAI GPT-5.6: none, low, medium, high, xhigh, max
• OpenAI GPT-5 Pro (Responses API 전용): high
• OpenAI GPT-5.⅖.⅘.5 Pro (Responses API 전용): medium, high, xhigh
• Anthropic Claude (Opus 4.7, Opus 4.6, Sonnet 4.6 등): none, minimal, auto, low, medium, high, xhigh*
  • auto는 적응형 사고({"type": "adaptive"})로 매핑됩니다. 모델이 사고의 시점과 정도를 동적으로 결정합니다.
  • *xhigh는 Opus 4.6/4.7에서 max로 매핑되고 그 외 모델에서는 high로 다운그레이드됩니다. Opus 4.7에서는 temperature, top_p, top_k가 제거됩니다.
• Gemini (2.0-flash, 2.5-flash, 2.5-pro, 3-flash, 3-pro): none*, auto**, minimal, low, medium, high
  • *none은 Flash 모델 (2.0-flash, 2.5-flash, 3-flash)에서만 지원됩니다.
  • **auto는 medium으로 자동 다운그레이드됩니다.

OpenAI 모델은 스트리밍과 비스트리밍 요청에 동일한 모델별 검증을 적용합니다. 지원하지 않는 값은 400 invalid_request_error로 거절하며 auto, xhigh, max를 다른 effort로 바꾸지 않습니다. 다른 공급자는 위에 설명한 공급자별 변환 동작을 유지합니다.

응답 (비스트리밍):

{
  "id": "chatcmpl-123456789",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-5.6-luna",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Quantum computing is a revolutionary computing paradigm that harnesses quantum mechanical phenomena..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 150,
    "total_tokens": 175
  }
}

응답 (스트리밍): stream: true일 때 응답은 Server-Sent Events (SSE)를 사용합니다:

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-5.6-luna","choices":[{"delta":{"role":"assistant","content":""},"index":0,"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-5.6-luna","choices":[{"delta":{"content":"Quantum"},"index":0,"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-5.6-luna","choices":[{"delta":{"content":" computing"},"index":0,"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-5.6-luna","choices":[{"delta":{},"index":0,"finish_reason":"stop"}]}

data: [DONE]

상태 코드:

• 200: 완료가 성공적으로 생성됨
• 400: 유효하지 않은 요청 형식 또는 파라미터
• 404: 정상 백엔드에서 모델을 찾을 수 없음
• 502: 백엔드 연결 오류
• 504: 요청 타임아웃
• 503: 모든 백엔드가 비정상

기능:

• 모델 기반 라우팅: 요청된 모델을 제공하는 백엔드로 자동 라우팅
• 로드 밸런싱: 정상 백엔드 간 로드 분산
• 스트리밍 지원: SSE를 통한 실시간 응답 스트리밍
• 오류 복구: 일시적 실패 시 자동 재시도
• 요청 중복 제거: 동일한 요청의 중복 처리 방지
• 추론 파라미터 정규화: 중첩된 reasoning 형식을 평면 reasoning_effort 형식으로 자동 정규화; 지원하지 않는 모델에서는 추론 파라미터 제거
• 투명한 Responses-API 라우팅: 요청된 모델이 responses_only: true로 표시된 경우(예: gpt-5-pro, gpt-5.2-pro, gpt-5.4-pro, gpt-5.5-pro), 클라이언트는 /v1/chat/completions를 그대로 사용하면 됩니다. 전체 모델 목록과 설정은 Responses-API 전용 모델을 참조하세요.
  • 업스트림 디스패치: 라우터가 업스트림 /v1/responses 엔드포인트로 투명하게 디스패치한 뒤, 응답을 strict 모드의 chat.completion(스트리밍은 chat.completion.chunk) 봉투로 다시 변환합니다.
  • 보존되는 필드: reasoning_content, refusal(finish_reason: "content_filter"), incomplete_details 절단(finish_reason: "length" 또는 "content_filter"), 그리고 업스트림 failed/cancelled 오류 봉투가 그대로 보존됩니다.
  • 백엔드 요구사항: /v1/responses는 OpenAI와 Azure OpenAI 백엔드만 제공하며, 다른 백엔드 유형과 짝지어지면 디스패치 전에 400 invalid_request_error가 반환됩니다.
• Gemini 네이티브 API 라우팅: Gemini 백엔드로 전달되는 요청 중 네이티브 전용 기능(tools: [{"google_search": {}}], tools: [{"code_execution": {}}], modalities: ["text", "image"], cachedContent, 다중 턴 어시스턴트 이미지 기록, 또는 gemini_context_cache.prefer_native_api: true)을 사용하는 요청은 자동으로 Gemini 네이티브 generateContent / streamGenerateContent 엔드포인트로 라우팅되며 응답은 reasoning_content, code_execution, annotations, grounding_metadata, 인라인 images를 포함한 OpenAI 호환 형식으로 변환됩니다.

Gemini 네이티브 전용 기능 요청/응답 예시 (/v1/chat/completions)¶

1. Google Search 그라운딩 및 Python 코드 실행:

{
  "model": "gemini-2.5-flash",
  "messages": [
    {
      "role": "user",
      "content": "최신 안정 버전 Rust 릴리스를 Google에서 검색하고 Python 코드로 계산해 주세요."
    }
  ],
  "tools": [
    { "type": "google_search" },
    { "type": "code_execution" }
  ]
}

정규화된 chat.completion 응답에는 포맷팅된 content와 함께 annotations(type: "url_citation"), grounding_metadata, 구조화된 code_execution 배열이 포함됩니다:

{
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "```python\nprint(42)\n```\n\n```output\n42\n```\n최신 릴리스는...",
        "annotations": [
          {
            "type": "url_citation",
            "url_citation": {
              "url": "https://...",
              "title": "rust-lang.org",
              "start_index": 0,
              "end_index": 24
            }
          }
        ],
        "grounding_metadata": {
          "webSearchQueries": ["latest stable Rust release"],
          "groundingChunks": [],
          "groundingSupports": []
        },
        "code_execution": [
          { "type": "executable_code", "language": "PYTHON", "code": "print(42)\n" },
          { "type": "code_execution_result", "outcome": "OUTCOME_OK", "output": "42\n" }
        ]
      },
      "finish_reason": "stop"
    }
  ]
}

2. 멀티턴 대화형 이미지 생성 및 편집:

Gemini 이미지 모델(gemini-2.5-flash-image, nano-banana, nano-banana-2, nano-banana-pro)에 modalities: ["text", "image"]를 지정하고 이전 턴 응답의 assistant.images 배열을 다음 요청 messages에 그대로 포함하면 대화를 이어가며 이미지를 수정할 수 있습니다:

{
  "model": "gemini-2.5-flash-image",
  "modalities": ["text", "image"],
  "messages": [
    { "role": "user", "content": "파란색 원 모양의 플랫 아이콘을 생성해 주세요." },
    {
      "role": "assistant",
      "content": "",
      "images": [
        {
          "type": "image_url",
          "image_url": { "url": "data:image/png;base64,iVBORw0KGgo..." }
        }
      ]
    },
    { "role": "user", "content": "원 색상을 파란색에서 빨간색으로 바꾸고 가운데에 노란 별을 추가해 주세요." }
  ]
}

도구 변환 경고¶

요청을 실제 응답 백엔드의 형식으로 변환하면서 도구 선언을 생략하면, 성공 응답에 x-continuum-dropped-tools 헤더가 포함됩니다. Chat Completions, Responses, Anthropic Messages 변환 경로와 스트리밍 응답에 적용됩니다. 기존처럼 요청 처리는 계속되므로, 선언한 모든 도구가 필요한 애플리케이션은 이 헤더를 확인하세요.

값은 중복을 제거하고 정렬한 도구 유형 목록이며, 쉼표로 구분합니다. 알려진 유형은 web_search, web_search_preview, file_search, code_interpreter, computer_use_preview, image_generation, mcp, local_shell, custom이며, 나머지는 other로 표시합니다. CORS에서도 이 헤더를 노출합니다.

x-continuum-dropped-tools: file_search, other

실제로 생략한 도구만 표시합니다. Gemini 네이티브 내장 도구로 변환한 검색 및 코드 실행 도구는 포함하지 않습니다. 실패한 백엔드 시도의 경고는 성공한 폴백 응답에 포함되지 않습니다. 스트리밍에서는 응답 핸드셰이크까지 완료한 변환을 표시하며, 이후 OpenAI 형식의 릴레이 폴백은 도구 선언을 보존합니다.

캐시된 본문에는 변환 경고가 보존되지 않으므로, 함수 외 도구나 네이티브 도구 선언이 포함된 요청은 라우터 응답 캐시를 사용하지 않습니다. 정확 일치, 접두사, 시맨틱 응답 캐시에 모두 적용되며, 함수 도구만 포함한 요청은 계속 캐시할 수 있습니다. 제공자의 프롬프트 및 컨텍스트 캐시는 기존대로 동작합니다.

Responses API¶

OpenAI의 Responses API 형식을 사용하여 응답을 생성합니다. 이 엔드포인트는 Chat Completions에 대한 대안적 인터페이스를 제공하며 내부적으로 요청을 Chat Completions 형식으로 변환하여 백엔드에서 처리합니다.

클라이언트가 취소했거나, 타임아웃되었거나, 가드레일에 차단되었거나, 도중에 실패한 스트리밍 응답은 끊긴 시점까지 생성된 토큰만큼 과금됩니다. 해당 종료 결과를 담은 사용량 레코드 하나가 기록되며 수치는 엔진 사용량이 도착했으면 그 값을, 아니면 라우터의 델타 수를 씁니다. Anthropic이나 Gemini 업스트림이 입력은 보고했지만 출력 수(Anthropic의 message_delta, Gemini 마지막 청크의 candidatesTokenCount)를 보고하기 전에 끊기면, 그 입력과 라우터의 델타 수로 과금됩니다.

POST /v1/responses

요청 본문:

{
  "model": "gpt-5.6-sol",
  "input": "양자 컴퓨팅을 간단한 용어로 설명해주세요.",
  "instructions": "당신은 복잡한 주제를 간단하게 설명하는 유용한 어시스턴트입니다.",
  "max_output_tokens": 1000,
  "temperature": 0.7,
  "reasoning": {
    "effort": "high"
  }
}

파라미터:

라우터가 모델링하지 않는 필드(conversation, background, service_tier, parallel_tool_calls, 그리고 API에 나중에 추가되는 필드)는 패스스루 백엔드로 보낸 그대로 전달됩니다. 변환 전략은 위 필드로만 요청을 만들고 나머지는 버리며 이런 필드가 하나라도 있는 요청은 응답 캐시에서 제공되지 않습니다. 라우터가 모델링하지 않는 유형의 입력 항목(예: mcp_approval_response, computer_call_output)도 패스스루 백엔드를 위해 그대로 보존되며 변환 전략은 이를 버리지 않고 400 unsupported_request_parameter로 거부합니다.

내장 목록에 없는 도구 유형에도 같은 규칙이 적용되며, Codex CLI는 이 규칙 덕분에 이 엔드포인트로 백엔드에 도달할 수 있습니다. 패스스루 백엔드는 responses_tools 정책이 허용한 도구를 클라이언트가 보낸 것과 같은 JSON 내용으로 받으며, 객체 키의 순서는 유지되지 않습니다. 변환 전략은 다음과 같이 처리합니다.

이 정책은 두 흐름 모두에서 백엔드 선택 전에 실행됩니다. 따라서 정책이 거부한 유형은 어떤 백엔드에서든 tools[<type>]을 명시한 400 unsupported_request_parameter를 받으며, 업스트림 요청은 나가지 않습니다. execution: "client"인 tool_search는 항상 허용되고, 다른 execution 값이면 "그 밖의 유형" 행을 따릅니다.

평면화한 이름이 서로 충돌해도 400 unsupported_request_parameter로 거부됩니다. name이 없는 function 도구처럼 알려진 type의 필수 필드가 빠지면 422로 실패합니다.

변환 전략은 평면화한 도구가 4096개를 넘는 요청도 400 unsupported_request_parameter로 거부합니다. 이때 namespace 멤버는 각각 하나로 셉니다. 평면화 비용은 도구 수에 비례해 늘어나며, 10 MiB 본문 한도에 가까운 요청은 요청 하나가 쓸 수 있는 CPU를 크게 넘습니다. 패스스루 백엔드는 영향을 받지 않습니다. 도구를 선언한 그대로 보내며 평면화하지 않습니다.

변환된 응답은 스트리밍 여부와 관계없이 평면화한 도구 호출을 원래 name과 namespace로 보고하므로, 이 조합으로 호출을 찾는 클라이언트도 호출을 처리할 수 있습니다.

모델링된 형식에 있는 필드 중 라우터가 모델링하지 않는 필드도 유지됩니다. 패스스루 백엔드는 이 필드를 그대로 받고, 변환 전략은 무시합니다.

• 호스팅 도구: web_search(예: external_web_access, filters), file_search(vector_store_ids), code_interpreter(container), computer_use, programmatic_tool_calling.
• 재전송 항목: message(id, status 및 그 밖의 모든 필드로, type 없이 role과 content를 가진 항목도 포함. type이 있을 때 phase, agent, caller, 비표준 id나 status가 있으면 변환 전략이 거부하는 네이티브 전용 항목이 됩니다), function_call(id, status, encrypted_content, encrypted_function_args)과 function_call_output(id, status). 이 필드는 입력 크기 제한에 포함됩니다.

백엔드가 모르는 id를 재전송하면(예: store: false인 경우) 백엔드를 직접 호출했을 때와 마찬가지로 거부될 수 있습니다.

tool_choice 형식:

알 수 없는 문자열, name이 없는 {"type": "function"}, namespace가 문자열이 아닌 이름 있는 객체 같은 그 밖의 값은 422로 실패합니다. Gemini 변환에서 tool_choice는 요청이 function 도구를 선언한 경우에만 tool_config로 변환됩니다. web_search나 code_interpreter만 있는 요청에는 tool_config가 없으므로 강제 선택이 효과가 없습니다. function 도구를 web_search나 code_interpreter와 함께 쓰는 요청에는 서버 측 도구 순환을 지원하는 모델이 필요합니다. gemini-2.5-flash는 tool_choice가 none이 아니면 이런 요청을 400으로 거부합니다. Gemini가 직접 실행한 도구는 불투명한 encrypted_content를 담은 reasoning 항목으로 돌아오고, function_call에도 encrypted_content가 있을 수 있습니다. 이후 세대 Gemini 모델은 이 값이 없는 호출을 재전송하면 400으로 응답하므로, 대화 기록을 직접 관리하는 클라이언트는 두 필드를 변경 없이 다시 보내야 합니다.

reasoning 항목의 encrypted_content는 이를 발급한 라우터 인스턴스가 서명합니다. 서명이 검증되지 않는 값(재시작 후 또는 다른 인스턴스에서 발급한 값)은 재전송되지 않고 버려집니다. 서버 측 도구 파트는 출력 시 검사되며, 마스킹 판정이 발생하면 해당 항목을 제거합니다.

/v1/chat/completions의 Gemini 네이티브 요청은 다음 도구 규칙을 따릅니다.

• toolConfig 전송 조건: 함수 선언에 도달할 수 있을 때만 전송합니다. 인라인 선언이거나, 클라이언트가 관리하는 cachedContent에 담긴 선언이 여기에 해당합니다. 내장 도구(web_search_options, code_execution 등)만 있으면 toolConfig를 보내지 않으므로, required나 이름 지정 선택은 검증만 되고 강제되지 않습니다. 이런 요청마다 경고를 기록하고 tool_choice_unenforced_total{reason="forced_without_functions"}을 증가시킵니다.
• 함수와 내장 도구를 함께 쓰는 경우: toolConfig에 include_server_side_tool_invocations: true를 넣습니다. 클라이언트가 tool_choice를 보내지 않아도 마찬가지입니다. 이 조합을 지원하지 않는 모델은 여전히 400으로 거부하며, gemini-2.5-flash가 그렇습니다.
• tool_choice: "none": web_search_options에서 파생된 도구를 포함해 내장 도구를 본문에서 제거하므로, 요청은 도구 없이 실행됩니다. 제거할 때마다 tool_choice_unenforced_total{reason="none_with_built_ins"}을 증가시킵니다.

Gemini가 4xx로 응답하면 두 경로 모두에서 Google이 보낸 정제한 메시지(예: Invalid tool)를 클라이언트 오류에 담아 전달합니다. 5xx 본문은 전달하지 않으며, 클라이언트는 상태 코드로 만든 메시지를 받습니다.

도구 정의 형식:

Responses API는 함수 속성이 type 필드와 같은 레벨에 있는 플랫 도구 형식을 사용합니다. 이는 중첩된 function 객체를 사용하는 Chat Completions API와 다릅니다.

{
  "type": "function",
  "name": "get_weather",
  "description": "위치의 날씨 조회",
  "parameters": {
    "type": "object",
    "properties": {
      "location": {"type": "string", "description": "도시 이름"}
    },
    "required": ["location"]
  },
  "strict": true
}

기타 지원되는 도구 유형: code_interpreter, file_search, web_search, computer_use. Gemini 백엔드를 대상으로 할 때, web_search는 네이티브 google_search 그라운딩(url_citation 주석 및 grounding_metadata 제공)으로 자동 매핑되고 code_interpreter는 네이티브 code_execution(코드 블록 및 실행 결과 제공)으로 매핑됩니다.

Gemini 백엔드에서 MALFORMED_FUNCTION_CALL이나 TOO_MANY_TOOL_CALLS처럼 도구 또는 잘못된 출력과 관련된 종료 사유로 턴이 끝나면, 응답은 status: failed이고 소문자로 바꾼 사유를 error.code에 담습니다. 프롬프트 차단 없이 후보가 없는 응답은 empty_response 코드와 함께 failed로 보고하며, 스트리밍과 비스트리밍 모두 동일합니다. failed 응답은 HTTP 200이지만 아무 답변도 제공하지 않은 것입니다. 그대로 반환되며 캐시되지 않고, previous_response_id로 이어 쓸 수 있도록 저장되지 않으며, 사용 품질 판정에도 쓰이지 않습니다. 해당 요청은 upstream_error로 기록되지만 제공자가 보고한 토큰은 그대로 청구됩니다.

멀티모달 입력 유형:

input이 항목 배열인 경우 각 항목은 멀티모달 콘텐츠 파트를 포함하는 메시지가 될 수 있습니다. 다음 콘텐츠 파트 유형이 지원됩니다:

메시지 역할:

각 메시지 항목은 다섯 가지 역할 중 하나를 가집니다. 라우터는 /v1/responses에서 다섯 가지를 모두 받아들이고 백엔드별로 변환합니다.

developer와 system 메시지가 여러 개 들어오면 라우터는 도착 순서를 그대로 유지합니다. 대상 백엔드(Anthropic, Gemini)가 단일 지시 슬롯만 허용하는 경우, 빈 줄 구분자로 이어붙여서 어떤 지시 텍스트도 누락되지 않도록 합니다.

아이템 참조:

{"type": "item_reference", "id": "item_..."} 형태의 입력 항목은 이전에 저장된 응답의 출력 아이템을 가리킵니다. OpenAI와 Vercel AI SDK가 기본값으로 다단계 도구 왕복을 제출하는 방식이 바로 이것으로, 2단계 요청이 함수 호출 아이템 전체를 다시 보내는 대신 1단계에서 생성된 아이템을 참조합니다.

• OpenAI / Azure OpenAI 패스스루 경로에서는 참조가 변경 없이 전달되고 업스트림이 해소합니다.
• 변환 경로(Anthropic, Gemini, chat completions 기반 라우팅)에서는 라우터가 디스패치 전에 세션 저장소에서 각 참조를 해소해, 참조가 가리키는 인라인 function_call, message, function_call_output 아이템으로 다시 씁니다. 참조는 call_id 기준으로 중복이 제거됩니다(먼저 온 것이 유지됨).
• 스트리밍 응답도 똑같이 참여합니다. 스트림이 완료되면 누적된 응답이 저장되므로, 후속 요청이 스트리밍 단계에서 생성된 아이템을 참조할 수 있습니다.
• 해소할 수 없는 참조는 해당 id를 명시한 HTTP 400을 반환하며 요청 하나가 가질 수 있는 참조는 최대 256개입니다.

Input File 형식:

input_file 콘텐츠 파트는 세 가지 입력 방법을 지원합니다:

{
  "type": "input_file",
  "filename": "document.pdf",
  "file_data": "data:application/pdf;base64,JVBERi0xLjQ..."
}

Input Image 형식:

{
  "type": "input_image",
  "image_url": "data:image/png;base64,iVBORw0KGgo...",
  "detail": "high"
}

image_url과 file_id 중 하나는 반드시 있어야 합니다. 둘 다 없으면 400 오류가 반환됩니다. file_id를 사용하면 백엔드로 요청을 보내기 전에 파일이 인라인 base64 데이터 URL로 변환되며 input_file + file_id 경로와 동일하게 파일 소유권이 검증되고 10MB 크기 제한이 적용됩니다.

멀티모달 요청 예시:

curl -X POST http://localhost:8080/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "input": [
      {
        "type": "message",
        "role": "user",
        "content": [
          {"type": "input_text", "text": "이 문서에 무엇이 적혀있나요?"},
          {"type": "input_file", "filename": "report.pdf", "file_data": "data:application/pdf;base64,..."}
        ]
      }
    ]
  }'

보안 참고 사항:

• file_url의 외부 URL은 SSRF 공격 방지를 위해 검증됩니다
• 개인 IP 주소와 localhost URL은 거부됩니다
• 외부 파일에는 HTTPS URL만 권장됩니다
• file_id 필드는 Files API를 통해 업로드된 파일을 참조합니다. 파일은 백엔드로 전송되기 전에 base64로 변환됩니다. 파일 소유권이 검증되며 파일 주입에 10MB 크기 제한이 적용됩니다

Reasoning 파라미터:

reasoning 파라미터는 추론 가능 모델의 추론 노력 수준을 제어합니다. 중첩 형식을 사용합니다:

{
  "reasoning": {
    "effort": "high"
  }
}

유효한 effort 값:

라우터는 이 중첩 형식을 Chat Completions 백엔드에서 사용하는 평면 reasoning_effort 형식으로 자동 변환합니다. 잘못된 노력 수준은 400 Bad Request 오류로 거부됩니다.

Reasoning을 포함한 요청 예시:

curl -X POST http://localhost:8080/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "o1",
    "input": "이 복잡한 수학 문제를 단계별로 풀어주세요.",
    "reasoning": {
      "effort": "high"
    }
  }'

응답:

{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1699000000,
  "model": "o1",
  "output": [
    {
      "type": "message",
      "id": "msg_001",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "단계별로 풀어보겠습니다..."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 25,
    "output_tokens": 150
  },
  "status": "completed"
}

상태 코드:

• 200: 응답 생성 성공
• 400: 잘못된 요청 형식, 파라미터 또는 잘못된 reasoning effort 값
• 404: 정상 백엔드에서 모델을 찾을 수 없음
• 502: 백엔드 연결 오류
• 504: 요청 타임아웃
• 503: 모든 백엔드가 비정상

기능:

• 스마트 라우팅: 백엔드 기능에 따라 요청 라우팅 - OpenAI/Azure와 responses_api: native로 설정한 백엔드는 네이티브 패스스루, 기타는 자동 변환
• 네이티브 패스스루: OpenAI 및 Azure OpenAI 백엔드, 그리고 responses_api: native로 설정한 모든 OpenAI 와이어 백엔드의 경우 요청이 백엔드의 /v1/responses 엔드포인트로 직접 전달되어 모든 네이티브 기능 유지
• 자동 변환: 기타 백엔드(Anthropic, Gemini, vLLM, Ollama 등)의 경우 Responses API 형식을 해당 네이티브 형식으로 변환
• 추론 지원: 타입 안전 검증을 통한 reasoning 파라미터 전체 지원
• 다중 백엔드 지원: OpenAI, Anthropic, Gemini, Ollama, vLLM 및 기타 백엔드와 호환
• 스트리밍 지원: stream: true일 때 SSE를 통한 실시간 응답 스트리밍
• 세션 관리: previous_response_id를 통한 다중 턴 대화 지원

라우팅 전략:

라우터는 각 백엔드에 대해 최적의 전략을 자동으로 결정합니다:

위 표는 각 유형의 기본값입니다. 자체 대화 상태를 유지하는 에이전트 런타임이나 SGLang의 /v1/responses처럼 Responses API를 직접 구현한 셀프 호스팅 서버는 해당 백엔드에 responses_api: native를 설정하면 변경 없이 제공할 수 있습니다(백엔드: 네이티브 Responses API 참고). 이 옵션은 OpenAI 와이어 형식을 쓰는 모든 유형(openai, azure, generic, continuumrouter, vllm, sglang, tensorrt-llm, ollama, llamacpp, mlxcel, lmstudio)에서 허용되며 anthropic, bedrock, gemini에서는 로드 시 거부됩니다. 이 옵션은 /v1/responses(와 /v1/responses/compact)가 백엔드에 도달하는 방식만 바꾸며 모델 목록, owned_by, 헬스 체크 등 다른 모든 엔드포인트는 유형의 동작을 그대로 따릅니다.

패스스루 전략에서 백엔드는 previous_response_id, conversation, 라우터가 모델링하지 않는 입력 항목(예: mcp_approval_response)을 포함해 클라이언트가 보낸 그대로의 요청을 받고 백엔드의 출력은 라우터가 모델링하지 않는 출력 항목(예: mcp_approval_request)을 포함해 스트리밍과 비스트리밍 경로 모두에서 그대로 클라이언트에 전달됩니다. responses_tools.deny_resource_fields 목록으로 이 전략의 previous_response_id, conversation, prompt 필드와 item_reference 입력 항목을 거부할 수 있고, input_item_resource_ids로 file_id나 container_id 같은 리소스 ID를 담은 입력 항목도 거부할 수 있으며, 이 다섯 항목은 기본적으로 꺼져 있습니다.

세 가지 예외로 거버넌스를 유지합니다. background: true는 패스스루 전략에서만 전달됩니다(백그라운드 응답 참고). 변환 전략은 이전과 같이 이 필드를 제거하고 동기적으로 응답합니다. 요청의 모델과 키에 가드레일 정책이 적용되는 동안 재사용 prompt는 입력 단계가 그 variables를 읽지 않으므로 검사할 수 없는 입력으로 처리됩니다(enforce 모드는 거부, monitor 모드는 기록). request_params나 허브 티어 제한이 top_k, min_p, max_tokens를 제어하는 동안에는 모델링되지 않은 필드 top_k, min_p, max_tokens, max_completion_tokens가 제한을 우회해 전달되지 않도록 400으로 거부됩니다.

패스스루 이점:

OpenAI 또는 Azure OpenAI 백엔드를 패스스루 모드로 사용할 때:

• 네이티브 PDF 파일 지원 (Chat Completions는 이미지만 지원)
• 턴 간 추론 상태 보존으로 성능 향상
• 내장 도구(web_search, file_search 등) 접근 가능
• 향상된 캐시 활용 (OpenAI 문서에 따르면 40-80% 개선)
• 최신 OpenAI Responses API 기능과의 완벽한 호환성

Anthropic 네이티브 변환 이점:

Anthropic (Claude) 백엔드를 네이티브 변환 모드로 사용할 때:

• Anthropic 문서 이해 기능을 통한 네이티브 PDF 파일 지원
• 자동 형식 감지를 통한 이미지 파일 지원
• Claude 3+ 모델의 확장 사고(Extended Thinking) 지원
• 외부 파일 URL에 대한 SSRF 보호
• 보안을 위한 미디어 타입 화이트리스트

가드레일: 가드레일이 설정되면 이 엔드포인트는 스트리밍 여부와 관계없이 모든 요청에 대해 응답 캐시, 백엔드 선택, 모든 폴백 시도보다 먼저 입력 단계를 실행하고 모든 비스트리밍 응답에 대해 store: true 세션을 저장하기 전에 출력 단계를 실행합니다. 차단된 요청은 SSE 이벤트를 보내기 전에 status가 incomplete이고 incomplete_details.reason이 content_filter인 response 객체(HTTP 200)로 응답하며 block_behavior: error에서는 OpenAI content_filter 오류 봉투(HTTP 400)로 응답합니다. 변환 전략에서는 previous_response_id 또는 item_reference 이어가기를 재구성된 히스토리에 대해 디스패치된 모델의 정책으로 다시 검사합니다. 차단 응답은 캐시되지 않으며 폴백 홉을 일으키지 않습니다. 가드레일: 라우트별 적용 범위를 참고하세요.

저장된 응답 조회, 삭제 또는 취소¶

store: true로 생성한 응답은 ID로 조회하거나 삭제할 수 있습니다.

• 저장소 및 라우팅:
  • 라우터가 만든 응답 (변환 전략): 응답을 생성한 라우터 인스턴스의 메모리 내 세션 저장소에서 제공됩니다(인스턴스당 최대 10,000개, 1시간 후 만료). 한 프로세스에 내장된 두 라우터(예: serve_embedded나 라이브러리 빌더로 만든 라우터)는 저장소를 따로 두므로 서로의 응답을 읽지 않습니다.
  • 패스스루 백엔드가 만든 응답: 업스트림 백엔드가 저장하므로, 라우터는 호출을 응답을 처리한 백엔드로 전달합니다.
• 소유권 및 범위 격리: 저장 세션은 응답을 생성한 인증된 API 키 주체(api_keys[].user_id) 범위로 격리됩니다. Authorization: Bearer <key>와 X-API-Key: <key> 자격 증명은 같은 설정 identity namespace를 사용합니다. 없거나, 만료되었거나, 인증되지 않았거나, 다른 범위의 요청은 모두 404를 반환합니다.

X-User-ID 범위 지정에서 마이그레이션¶

X-User-ID는 Responses API의 권한 경계가 아닙니다. 라우터는 저장된 응답 접근, previous_response_id 컨텍스트 재구성, item-reference 해석, 로컬 Files API 소유권 검사에서 이 헤더를 무시하며 백엔드로 전달하지 않습니다. 이전에 하나의 공유 라우터 API 키 뒤에서 여러 최종 사용자를 X-User-ID로 나누던 배포는 격리해야 하는 사용자 또는 테넌트마다 별도 라우터 API 키를 사용하거나, 라우터 앞의 신뢰할 수 있는 서비스에서 사용자별 상태를 관리하고 라우터의 저장된 Responses 세션 및 Files API 소유권 제어에 의존하지 않는 구조로 옮겨야 합니다.

GET /v1/responses/{response_id}
DELETE /v1/responses/{response_id}
POST /v1/responses/{response_id}/cancel

성공한 GET은 저장된 응답 객체를 반환합니다. 성공한 DELETE는 다음을 반환합니다.

{
  "id": "resp_abc123",
  "object": "response.deleted",
  "deleted": true
}

패스스루 응답¶

패스스루 백엔드가 store: true 응답을 처리하면, 라우터는 그 응답 ID를 처리한 백엔드를 응답을 만든 인증 주체 기준으로 기억합니다. 이후 그 ID에 대한 GET, DELETE, POST .../cancel은 같은 백엔드로 그 백엔드에 설정된 자격 증명과 함께 전달되고 백엔드의 상태 코드, Content-Type, 본문이 반환됩니다(?stream=true 같은 GET 쿼리 문자열도 전달됩니다). DELETE가 성공하면 바인딩도 잊습니다. 가드레일 출력 단계가 차단, 마스킹 또는 중단한 응답은 백엔드에 저장된 사본이 필터링되지 않은 텍스트이므로 바인딩하지 않으며 이에 대한 GET은 404를 반환합니다.

라우터는 기록하지 않은 ID를 어떤 백엔드로도 보내지 않으며 매 호출마다 현재 설정을 기준으로 바인딩을 다시 검사합니다. 백엔드가 여전히 설정되어 있고 활성 상태이며 internal이 아니고 패스스루로 제공되어야 하며 호출자의 키가 여전히 그 백엔드에 접근할 수 있어야 합니다(allowed_backends). 검사 중 하나라도 실패하면 백엔드에 연결하지 않고 알 수 없는 ID와 같은 404를 반환합니다. 바인딩은 라우터 인스턴스별로 메모리에 최대 10,000개까지 보관되며(가장 오래된 것부터 잊음), 재시작하면 사라집니다. 잊힌 ID도 404를 반환합니다. 라우터가 직접 만든 응답에 대한 cancel은 이미 완료된 응답이므로 400을 반환합니다.

백그라운드 응답¶

패스스루 백엔드에 보낸 background: true 요청은 그대로 전달되며 백엔드는 즉시 queued(또는 in_progress)로 응답하고 나중에 응답을 완성합니다. 승인 검사(속도 제한, 로컬 및 허브 예산)는 다른 요청과 마찬가지로 그 POST에서 실행됩니다.

• 미터링. queued 응답은 아무것도 기록하지 않습니다. 라우터가 usage를 담은 최종 결과(completed, incomplete, failed, cancelled)를 GET /v1/responses/{id} 또는 POST .../cancel로 처음 전달할 때, 동기 응답과 같은 경로로 요청과 사용량을 한 번 기록하며 같은 주체의 다른 키가 가져오더라도 응답을 만든 키에 귀속합니다. 다시 가져와도 기록하지 않습니다.
• 가드레일. 요청의 모델과 결과를 가져오는 키에 가드레일 정책이 적용되는 동안에는 결과를 가져올 때마다 전달 전에 출력 단계를 거치며 동기 응답과 같이 차단이나 마스킹이 적용됩니다. 클라이언트가 그 스트림을 나중에 라우터가 검사할 수 없는 GET ?stream=true로 재개할 수 있으므로, 가드레일이 적용되는 동안 stream: true와 background: true를 함께 보내면 400 unsupported_request_parameter로 거부됩니다.
• 가드레일 없는 스트리밍 백그라운드는 전달되며 한 번 미터링됩니다. 클라이언트가 연결을 유지하면 스트림의 최종 이벤트에서, 그렇지 않으면 최종 결과를 stream 없이 처음 가져오는 GET이나 cancel에서 기록합니다. 클라이언트 연결이 끊기면 라우터는 스트림 읽기를 멈추지만 백엔드는 생성을 계속하기 때문입니다.
• 재생. 아직 미터링되지 않은 백그라운드 결과(최종 이벤트 전에 클라이언트 연결이 끊긴 스트리밍 결과 포함)나 가드레일이 적용되는 결과에 대한 GET ?stream=true는 400 unsupported_request_parameter로 거부되므로, stream 없이 가져오세요.
• 제한 사항. 라우터를 거쳐 가져오지 않은 백그라운드 결과(백엔드에서 직접 가져오거나 아예 가져오지 않은 경우)는 미터링되지 않습니다. 라우터는 결과를 전달할 때만 사용량을 알 수 있고 스스로 백엔드를 폴링하지 않습니다. 대기 중인 기록을 담는 바인딩은 라우터 인스턴스별 메모리에 있으며 재시작이나 제거 시 사라집니다.

Responses Compact¶

input 항목 시퀀스를 요약하거나 압축해 대화 컨텍스트를 줄입니다. OpenAI와 Azure OpenAI 백엔드, 그리고 responses_api: native로 설정한 백엔드의 경우 요청이 백엔드의 네이티브 /v1/responses/compact 엔드포인트로 그대로 전달됩니다. 다른 백엔드는 컨텍스트 압축을 네이티브로 지원하지 않으므로 HTTP 501(Not Implemented)을 반환합니다.

가드레일이 설정되면 input 항목과 instructions는 백엔드 선택 전에 입력 단계를 거치며 차단은 항상 OpenAI content_filter 오류 봉투(HTTP 400)로 응답합니다. 압축 결과는 불투명하므로 게이트되지 않습니다. 가드레일: 라우트별 적용 범위를 참고하세요.

POST /v1/responses/compact

요청 본문:

{
  "model": "gpt-5.6-sol",
  "instructions": "이 대화의 핵심 내용을 요약해주세요.",
  "input": [
    {
      "type": "message",
      "role": "user",
      "content": [{"type": "input_text", "text": "프랑스의 수도는 어디인가요?"}]
    },
    {
      "type": "message",
      "role": "assistant",
      "content": [{"type": "output_text", "text": "프랑스의 수도는 파리입니다."}]
    }
  ]
}

파라미터:

응답:

{
  "id": "cmpt_abc123",
  "object": "response.compaction",
  "created_at": 1699000000,
  "output": [
    {
      "type": "text",
      "text": "압축된 대화 요약..."
    }
  ],
  "usage": {
    "input_tokens": 120,
    "output_tokens": 45
  }
}

상태 코드:

• 200: 압축 성공
• 400: 잘못된 요청 (빈 모델, 빈 입력, 너무 긴 instructions)
• 501: 백엔드가 네이티브 컨텍스트 압축을 지원하지 않음
• 502: 백엔드 연결 오류
• 504: 요청 타임아웃

Batch API (control-plane 빌드)¶

OpenAI 스타일 Batch API는 control-plane Cargo 기능으로 빌드할 때만 컴파일되며 기본 소스 빌드에는 없습니다. 공식 릴리스 바이너리에는 기능이 컴파일되지만 control_plane.enabled, 정책 적용, control_plane.batch.enabled가 활성화되고 Hub가 제시된 키/티어를 배치 적격으로 표시해야 라우트가 동작합니다.

Hub 동기화 API 키가 필요합니다. 소유권 검사는 알 수 없는 ID와 다른 키의 ID에 의도적으로 동일한 404를 반환합니다. 결과가 준비되기 전에는 409를 반환합니다. 선택된 배치 백엔드는 OpenAI 호환 또는 네이티브 Anthropic일 수 있으며 라우터는 하나의 공통 표면을 제공합니다. x-continuum-batch: off는 항상 요청을 배치에서 제외하며 정책이 이를 덮어쓸 수 없습니다.

OpenAI 스타일 배치 생성 시 input_file_id는 제공자 소유 파일 또는 Continuum Router의 로컬 /v1/files 저장소에 있는 파일을 지정할 수 있습니다. 제공자 소유 ID는 변경 없이 전달합니다. 라우터 로컬 파일은 Files API 소유권 정책을 적용하고 purpose=batch인지 확인하며, 메타데이터 크기가 200 MiB를 넘으면 콘텐츠를 읽기 전에 거부합니다. 지연과 배치 풀 승인이 끝난 뒤 선택된 OpenAI 호환 백엔드의 URL, 자격 증명, 요청 확장 설정으로 파일을 한 번 스트리밍하고, 반환된 제공자 파일 ID로 배치 요청을 치환합니다. 네이티브 Anthropic 배치는 인라인 요청을 사용하므로 라우터 로컬 input_file_id를 받을 수 없습니다.

라우터는 POST /v1/batches를 전달하기 전에 선택한 백엔드를 API 키의 allowed_backends와 대조합니다. 또한 Hub 티어의 model_allowlist와 키의 로컬 allowed_models를 교집합으로 적용하며, Hub 허용 목록이 명시적인 빈 목록이면 모든 모델을 거부합니다. 네이티브 Anthropic 배치는 각 requests[].params.model을 검사합니다. 모델 제한이 있는 OpenAI 스타일 배치는 라우터 로컬 파일이면 업로드 전에 스캔하고, 제공자 소유 파일이면 해당 백엔드의 자격 증명으로 가져와 모든 JSONL body.model을 검사합니다. 제한이 없는 OpenAI 스타일 배치는 모델 스캔을 생략하며 요청의 모델 힌트는 사용량 귀속에만 사용할 수 있습니다.

입력 스캔은 전체 200 MiB, JSONL 레코드당 16 MiB로 제한되며 60초 기한을 둡니다. 잘못된 파일 ID, 올바르지 않은 JSONL, 누락된 모델, 가져오기 실패, 크기 제한 초과처럼 검증할 수 없는 입력은 거부합니다. 이 검사는 지연이나 배치 풀 승인 전에 완료됩니다. 라우터 로컬 입력은 저장소에서 스트리밍으로 스캔하며 현재 처리 중인 제한된 JSONL 레코드만 보관합니다. 제한이 없는 지연 요청은 파일 콘텐츠가 아니라 메타데이터만 보관합니다.

승인 후에는 백엔드를 다시 선택합니다. 설정 리로드로 백엔드 이름, URL, 인증 정보, 제공자 유형, 요청 확장 설정이 달라졌으면 슬롯을 반환하고 제공자 배치를 만들지 않은 채 batch_backend_changed를 반환합니다.

제공자 업로드는 한 번만 시도합니다. 업로드가 실패하면 제공자 오류를 반환하고, 전송 단계에서 실패하면 batch_input_upload_failed를 반환하며 배치를 만들지 않습니다. 첫 업로드가 제공자에 도달했지만 응답이 유실된 경우 클라이언트가 요청을 다시 보내면 제공자 파일이 하나 더 생길 수 있습니다. 제출에 성공한 뒤 제공자 복사본은 제공자의 보존 정책을 따릅니다. 라우터 로컬 파일을 삭제해도 배치를 취소하거나 제공자 복사본을 삭제하지 않습니다.

파인튜닝 API¶

OpenAI Fine Tuning 작업 경로는 선택된 OpenAI-wire 백엔드로 전달됩니다. 생성, 조회, 취소는 백엔드의 응답을 그대로 반환하고, 목록 본문은 호출자 자신의 작업만 남깁니다. 기능 게이트가 적용되는 Batch API와 달리 모든 빌드에 마운트됩니다.

http 또는 https의 openai, generic 백엔드 유형만 후보입니다. Azure OpenAI는 파인튜닝 엔드포인트 경로가 다르고 api-version이 필수이므로 제외합니다. 후보가 처리할 수 없는 요청은 라우터 수준 404가 아니라 400 fine_tuning_not_supported를 반환합니다.

라우터는 (주체, 작업 ID)를 작업을 생성한 백엔드에 기록합니다. 조회와 취소는 이 바인딩을 실행 중인 설정과 호출자의 allowed_backends에 대해 다시 검사합니다. 알 수 없거나 다른 주체의 ID는 백엔드에 접속하지 않고 404 fine_tuning_job_not_found를 반환합니다. 목록은 라우터가 호출자에게 바인딩한 항목만 남기므로 다른 주체의 작업 ID나 학습 파일 ID를 노출하지 않습니다. 바인딩은 프로세스 메모리에 있으므로, 라우터를 재시작하기 전에 생성한 작업은 목록에 나오지 않고 not-found를 반환합니다.

작업 CRUD에는 인증, 속도 제한, 사용량 귀속이 적용되지만 요청 파라미터 정책, 가드레일, 응답 캐싱, 모델별 생성 예산은 적용되지 않습니다. 각 호출은 0 토큰의 non-completion 요청으로 기록됩니다. training_file과 validation_file은 선택된 백엔드에 이미 존재해야 합니다. 라우터 로컬 /v1/files ID는 프로바이더로 업로드되지 않습니다.

벡터 스토어 API¶

OpenAI Vector Stores 경로는 선택된 OpenAI 계열 백엔드로 전달됩니다. 스토어와 파일 작업은 백엔드 응답을 그대로 반환하며, 목록 응답은 호출자 자신의 스토어만 남깁니다. 이 경로는 모든 빌드에 마운트됩니다.

http 또는 https의 openai, generic 백엔드 유형만 후보입니다. Azure OpenAI는 Vector Stores 엔드포인트 경로가 다르고 api-version이 필수이므로 제외합니다. 후보가 처리할 수 없는 요청은 라우터 수준 404가 아니라 400 vector_stores_not_supported를 반환합니다.

벡터 스토어 호출은 모델을 지정하지 않으므로 x-backend 헤더를 사용하지 않습니다. 생성과 목록은 설정된 선택 전략으로 지원 백엔드 하나를 고릅니다. 이어서 라우터는 (주체, 스토어 ID)를 스토어를 생성한 백엔드에 기록하고, 스토어 범위 호출은 이 바인딩을 실행 중인 설정과 호출자의 allowed_backends에 대해 다시 검사합니다. 알 수 없거나 다른 주체의 ID는 백엔드에 접속하지 않고 404 vector_store_not_found를 반환합니다. 목록은 라우터가 호출자에게 바인딩한 항목만 남기므로 다른 주체의 스토어 ID를 노출하지 않습니다. has_more, first_id, last_id는 백엔드 페이지를 그대로 설명하므로, 호출자는 has_more가 false가 될 때까지 페이지를 넘깁니다. 바인딩은 프로세스 메모리에 있으므로, 라우터를 재시작하기 전에 생성한 스토어는 목록에 나오지 않고 not-found를 반환합니다.

첨부는 공유 백엔드 자격 증명의 프로바이더 파일 ID를 지정합니다. 라우터는 어떤 주체가 프로바이더 파일을 업로드했는지 기록하지 않으므로, 유출된 프로바이더 파일 ID는 다른 주체의 스토어에 첨부되어 검색으로 읽힐 수 있습니다. 서로의 파일을 볼 수 없어야 하는 테넌트끼리 하나의 프로바이더 자격 증명을 공유하지 마십시오.

이 경로는 인증, API 키 scope, 속도 제한, 사용량 집계를 적용하지만 요청 파라미터 정책, 가드레일, 응답 캐시, 모델별 생성 예산은 적용하지 않습니다. 각 호출은 토큰 0개의 비-completion 요청으로 기록됩니다. JSON 요청 본문은 1MiB로 제한됩니다. 첨부는 프로바이더 파일 ID를 지정하므로, 라우터 로컬 /v1/files ID는 프로바이더에 업로드되지 않습니다.

이미지 생성¶

이미지 생성·편집·변형 요청은 백엔드로 전달하기 전에 모델 capability를 검사합니다. 비어 있지 않은 capability 목록에 요청한 작업이 없으면, HTTP 400과 unsupported_model_capability, param: "model"을 반환합니다. 목록이 없거나 비어 있는 모델은 사용자 정의 이미지 편집 모델을 포함해 계속 사용할 수 있습니다. 백엔드별 capability 설정이 다르면 해당 작업을 지원하는 백엔드만 선택합니다.

OpenAI의 DALL-E, GPT Image 모델 또는 Google의 Nano Banana (Gemini) 모델을 사용하여 이미지를 생성합니다.

POST /v1/images/generations

요청 본문:

{
  "model": "dall-e-3",
  "prompt": "A serene Japanese garden with cherry blossoms",
  "n": 1,
  "size": "1024x1024",
  "quality": "standard",
  "response_format": "url"
}

파라미터:

모델별 제약 조건:

품질 파라미터 (GPT Image 모델):

GPT Image 모델에서 standard는 medium으로, hd는 high로 매핑됩니다.

출력 형식 옵션 (GPT Image 모델):

참고: 투명 배경 (background: "transparent")은 png 또는 webp 형식이 필요합니다.

Nano Banana (Gemini) 모델:

Nano Banana는 OpenAI 호환 인터페이스를 통해 Google의 Gemini 이미지 생성 기능에 대한 액세스를 제공합니다:

• nano-banana / nano-banana-2: Gemini 3.1 Flash Image(gemini-3.1-flash-image)에 매핑 - 최대 4K 해상도 및 선택적 Google Search 그라운딩(google_search: true)을 지원하는 빠른 범용 이미지 생성. Google이 2026-09-18에 gemini-2.5-flash-image를 기존 사용 프로젝트로 제한하기 전까지는 nano-banana가 그 모델에 매핑했으며 이 id를 직접 지정하면 지금도 그대로 전달됩니다.
• nano-banana-2-lite: Gemini 3.1 Flash Lite Image(gemini-3.1-flash-lite-image)에 매핑 - 경량 1K 이미지 생성.
• nano-banana-pro: Gemini 3 Pro Image(gemini-3-pro-image)에 매핑 - 고해상도(최대 4K) 및 선택적 Google Search 그라운딩(google_search: true)을 지원하는 고급 모델.

Nano Banana 요청은 선택된 백엔드의 키를 실어 Google의 Gemini API로 보내므로, type: gemini로 구성한 백엔드만 이 요청을 처리합니다. 다른 타입의 백엔드는 이름이나 URL과 관계없이 선택되지 않습니다. Google의 OpenAI 호환 엔드포인트(https://generativelanguage.googleapis.com/v1beta/openai)를 가리키는 type: openai 또는 generic 백엔드로 Nano Banana를 제공하려면 type: gemini로 바꿔야 합니다.

Nano Banana 크기 매핑:

라우터는 OpenAI 스타일 크기 파라미터를 Gemini의 aspectRatio 및 imageSize 형식으로 자동 변환합니다:

변환은 다음 Gemini API 구조를 전송합니다:

{
  "contents": [{"parts": [{"text": "Your prompt"}]}],
  "generationConfig": {
    "imageConfig": {
      "aspectRatio": "3:2",
      "imageSize": "1K"
    }
  }
}

Nano Banana 요청 예제:

{
  "model": "nano-banana",
  "prompt": "A white siamese cat with blue eyes, photorealistic",
  "n": 1,
  "size": "1024x1024",
  "response_format": "b64_json"
}

응답:

{
  "created": 1677652288,
  "data": [
    {
      "url": "https://oaidalleapiprodscus.blob.core.windows.net/...",
      "revised_prompt": "A tranquil Japanese garden featuring..."
    }
  ]
}

응답 (b64_json 포함):

{
  "created": 1677652288,
  "data": [
    {
      "b64_json": "/9j/4AAQSkZJRgABAQAA...",
      "revised_prompt": "A tranquil Japanese garden featuring..."
    }
  ]
}

Nano Banana 응답 참고 사항:

• Nano Banana에서 response_format: "url"을 사용할 때, Gemini의 네이티브 API가 인라인 base64 데이터를 반환하므로 이미지는 data URL (data:image/png;base64,...)로 반환됩니다
• revised_prompt 필드에는 생성된 이미지를 설명하는 Gemini의 텍스트 응답이 포함됩니다
• google_search: true (또는 tools: [{"google_search": {}}])를 사용할 때 Gemini가 반환한 groundingMetadata는 이미지 응답 최상위의 grounding_metadata 필드로 보존됩니다
• Gemini 백엔드에 대한 /v1/chat/completions 또는 /v1/responses 요청에 tools: [{"google_search": {}}], tools: [{"code_execution": {}}], modalities: ["text", "image"], cachedContent, 또는 gemini_context_cache.prefer_native_api: true가 포함되면 라우터는 자동으로 Gemini 네이티브 generateContent / streamGenerateContent 엔드포인트로 디스패치하고 응답의 annotations, grounding_metadata, code_execution, 인라인 images를 OpenAI 응답 형식으로 변환합니다

스트리밍 이미지 생성 (GPT Image 모델):

GPT Image 모델에 대해 stream: true가 지정되면 응답이 Server-Sent Events (SSE)로 스트리밍됩니다:

스트리밍 요청 예제:

{
  "model": "gpt-image-1",
  "prompt": "A beautiful sunset over mountains",
  "stream": true,
  "partial_images": 2,
  "response_format": "b64_json"
}

스트리밍 응답 형식:

data: {"type":"image_generation.partial_image","partial_image_index":0,"b64_json":"...","created":1702345678}

data: {"type":"image_generation.partial_image","partial_image_index":1,"b64_json":"...","created":1702345679}

data: {"type":"image_generation.complete","b64_json":"...","created":1702345680}

data: {"type":"image_generation.usage","usage":{"input_tokens":25,"output_tokens":1024}}

data: {"type":"done"}

SSE 이벤트 타입:

새 옵션이 포함된 GPT Image 요청 예제:

{
  "model": "gpt-image-1.5",
  "prompt": "A white cat with blue eyes, photorealistic",
  "size": "auto",
  "quality": "high",
  "output_format": "webp",
  "output_compression": 85,
  "background": "transparent",
  "response_format": "b64_json"
}

상태 코드:

• 200: 이미지가 성공적으로 생성됨
• 400: 유효하지 않은 요청 (예: 모델에 대해 유효하지 않은 크기, DALL-E 3에서 n > 1)
• 401: 유효하지 않은 API 키
• 429: 속도 제한 초과
• 500: 백엔드 오류
• 503: Gemini 백엔드 사용 불가 (Nano Banana 모델의 경우)

타임아웃 설정: 이미지 생성 요청은 설정 가능한 타임아웃을 사용합니다 (기본값: 3분). 설정의 timeouts.request.image_generation을 참조하세요.

이미지 편집 (인페인팅)¶

OpenAI의 인페인팅 기능 또는 Gemini의 자연어 기반 편집을 사용하여 기존 이미지를 편집합니다. 이 엔드포인트를 사용하면 텍스트 프롬프트와 선택적 마스크를 기반으로 하나 이상의 입력 이미지를 수정하거나 합성할 수 있습니다. GPT Image 모델, Nano Banana (Gemini) 모델, 그리고 DALL-E 2를 지원합니다.

POST /v1/images/edits
Content-Type: multipart/form-data

요청 파라미터 (multipart/form-data):

지원되는 모델, 크기 및 입력 이미지 제한:

참고: DALL-E 3는 이 엔드포인트를 통한 이미지 편집을 지원하지 않습니다. Nano Banana (nano-banana, nano-banana-2, nano-banana-2-lite, nano-banana-pro) 및 Gemini 이미지 모델은 자연어 기반 편집과 다중 이미지 합성(최대 14개 입력 이미지)을 지원합니다. Nano Banana 요청에 mask 필드가 포함되면 경고를 기록하고 무시하며 프롬프트 텍스트로 편집 영역을 결정합니다.

이미지 요구 사항:

• 필드 이름: image 또는 image[] (여러 입력 이미지를 보내려면 필드를 반복 지정)
• 크기: 이미지당 4MB 미만
• 개수 제한: gpt-image-* 최대 16개, nano-banana / nano-banana-2 / nano-banana-2-lite / nano-banana-pro / Gemini 이미지 모델 최대 14개, dall-e-2 1개
• 형식 및 해상도:
  • gpt-image-*: PNG, JPEG, WebP (비정사각형 허용)
  • nano-banana, nano-banana-2, nano-banana-2-lite, nano-banana-pro: PNG, JPEG, WebP, HEIC, HEIF (비정사각형 허용)
  • dall-e-2: PNG만 허용, 정사각형이어야 함 (가로 = 세로)

마스크 요구 사항:

• 형식: 알파 채널이 있는 PNG (RGBA)
• 크기: 첫 번째 소스 이미지(images[0])와 정확히 일치해야 함
• 투명 영역: 편집/생성할 영역을 나타냄
• 불투명 영역: 보존할 영역을 나타냄

요청 예제:

curl -X POST http://localhost:8080/v1/images/edits \
  -F "image=@source_image.png" \
  -F "mask=@mask.png" \
  -F "prompt=A sunlit indoor lounge area with a pool containing a flamingo" \
  -F "n=1" \
  -F "size=1024x1024" \
  -F "response_format=url"

요청 예제 (다중 입력 이미지):

curl -X POST http://localhost:8080/v1/images/edits \
  -F "model=gpt-image-2" \
  -F "image[]=@subject.png" \
  -F "image[]=@background.png" \
  -F "prompt=Place the subject from the first image into the background of the second image" \
  -F "n=1" \
  -F "size=1024x1024"

응답:

{
  "created": 1677652288,
  "data": [
    {
      "url": "https://oaidalleapiprodscus.blob.core.windows.net/..."
    }
  ]
}

응답 (b64_json 포함):

{
  "created": 1677652288,
  "data": [
    {
      "b64_json": "/9j/4AAQSkZJRgABAQAA..."
    }
  ]
}

상태 코드:

• 200: 이미지가 성공적으로 편집됨
• 400: 유효하지 않은 요청 (예: 정사각형이 아닌 이미지, 유효하지 않은 크기, 필수 필드 누락)
• 401: 유효하지 않은 API 키
• 503: OpenAI 백엔드 사용 불가

오류 예제:

정사각형이 아닌 이미지:

{
  "error": {
    "message": "Image must be square (800x600 is not square)",
    "type": "invalid_request_error",
    "param": "image",
    "code": "image_not_square"
  }
}

마스크 크기 불일치:

{
  "error": {
    "message": "Mask dimensions (256x256) do not match image dimensions (512x512)",
    "type": "invalid_request_error",
    "param": "mask",
    "code": "dimension_mismatch"
  }
}

지원되지 않는 모델:

{
  "error": {
    "message": "Model 'dall-e-3' does not support image editing. Supported models: gpt-image-2.5-sunburst, gpt-image-2.5-flare, gpt-image-2, gpt-image-1, gpt-image-1-mini, gpt-image-1.5, dall-e-2, nano-banana, nano-banana-2, nano-banana-2-lite, nano-banana-pro. Note: dall-e-3 does NOT support image editing.",
    "type": "invalid_request_error",
    "param": "model",
    "code": "unsupported_model"
  }
}

참고 사항:

• 지원되는 모델: gpt-image-2.5-sunburst, gpt-image-2.5-flare, gpt-image-2, gpt-image-1, gpt-image-1-mini, gpt-image-1.5, dall-e-2, nano-banana, nano-banana-2, nano-banana-2-lite, nano-banana-pro 및 해당 모델이나 Gemini 이미지 모델로 해석되는 메타데이터 별칭(alias)
• DALL-E 3는 API를 통한 이미지 편집을 지원하지 않습니다
• Nano Banana (nano-banana, nano-banana-2, nano-banana-2-lite, nano-banana-pro)는 자연어 편집을 사용하여 Gemini 네이티브 generateContent API로 라우팅됩니다 (mask가 제공되면 무시되며 n은 1이어야 합니다)
• 모델별 입력 한도(gpt-image-* 16개, nano-banana / nano-banana-2 / nano-banana-2-lite / nano-banana-pro 14개, dall-e-2 1개) 내에서 image 또는 image[] 필드를 반복하여 여러 입력 이미지를 업로드할 수 있습니다
• 마스크가 제공되지 않으면 전체 이미지가 수정될 수 있습니다
• 요청 타임아웃은 이미지 생성 타임아웃 설정을 사용합니다

이미지 변형¶

Nano Banana (Gemini) 또는 OpenAI의 DALL-E 2 모델을 사용하여 기존 이미지의 변형을 생성합니다.

POST /v1/images/variations
Content-Type: multipart/form-data

폼 필드:

요청 예제:

curl -X POST http://localhost:8080/v1/images/variations \
  -F "image=@source_image.png" \
  -F "model=dall-e-2" \
  -F "n=2" \
  -F "size=512x512" \
  -F "response_format=url"

응답:

{
  "created": 1677652288,
  "data": [
    {
      "url": "https://oaidalleapiprodscus.blob.core.windows.net/..."
    },
    {
      "url": "https://oaidalleapiprodscus.blob.core.windows.net/..."
    }
  ]
}