Warp 라우터

warp/auto — 자동 라우팅

model: "warp/auto"로 요청하면 매 요청을 평가해 알맞은 모델로 보냅니다. 쉬운 요청은 가벼운 모델이, 어려운 요청은 상위 모델이 맡습니다. 평가는 게이트웨이 안에서 수 밀리초 안에 끝나며 별도 LLM 호출이 없어, 라우팅 자체가 지연이나 비용을 더하지 않습니다.

어떤 모델이 서빙했는지는 응답 메타의 model과 x-warp-model 헤더로, 얼마나 아꼈는지는 saved_usd로 매 요청 확인할 수 있습니다.

인텐트 다이얼

워크로드마다 원하는 트레이드오프가 다릅니다. warp.dial(요청 단위) 또는 키의 라우팅 정책(routing.dial)으로 4가지 중 하나를 고릅니다. 적용된 다이얼은 응답 메타 dial과 x-warp-dial 헤더로 확인합니다.

자동 라우터 — 셋

셋뿐이고, 위의 warp/auto도 그중 하나입니다. 셋 다 자동으로 라우팅하며, 무엇을 대상으로 고르는지가 다릅니다. 라우터 id를 모델 문자열로 지정할 수 있습니다. 전부 가상 모델 id라 어떤 OpenAI SDK에서도 model 문자열 하나만 바꾸면 적용됩니다.

지정 라우팅 — 쓰던 모델을 기준으로

warp/auto에 모델 선택을 통째로 맡기는 게 부담스럽다면, 반대 방향으로 쓸 수 있습니다. 지금 쓰는 모델을 warp.anchor로 지정하면 그 모델이 품질 상한이 됩니다 — 어려운 요청은 반드시 그 모델이 답하고, 쉬운 요청만 아래 티어로 내려갑니다. 정할 것은 두 가지뿐입니다.

dial을 생략하면 balanced입니다. 즉 최소 형태는 앵커 한 줄입니다.

{
  "model": "warp/auto",
  "messages": [{ "role": "user", "content": "이번 분기 지표를 요약해줘" }],
  "warp": {
    "anchor": "anthropic/claude-fable-5"
  }
}

나머지는 라우터가 정합니다

어떤 경량 모델을 붙일지, 언제 내려보낼지는 고르지 않아도 됩니다. 후보는 티어별로 선별된 체인이고, 벤치마크 성적을 참고해 저희가 갱신합니다 — 직접 고르거나 관리하지 않아도 됩니다. 특정 모델이나 벤더를 쓰지 않게 하려면 고르는 대신 모델 정책으로 제외하세요.

요청 본문을 못 보내는 도구

Claude Code·Cursor처럼 고정된 형식으로만 말하는 도구는 요청에 warp 객체를 넣을 자리가 없습니다. 이런 도구는 키에 저장된 라우팅 기본값을 씁니다 — 적용 순서는 요청 > 키 > 조직이라, 키에 앵커를 저장해두면 그 키로 들어오는 warp/auto 요청 전부에 적용됩니다. 도구별 설정은 도구 연동을 참고하세요.

curl -X PATCH https://api.warp.inc/v1/org/keys/key_abc123 \
  -H "Authorization: Bearer $WARP_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routing": {
      "anchorModel": "anthropic/claude-fable-5",
      "dial": "balanced"
    }
  }'

동적 가격 추적

카탈로그에 표시된 가격은 스냅샷입니다. 실제 과금 단가는 LiteLLM·OpenRouter 가격 피드에서 주기적으로 동기화되며(기본 6시간), 변경 이력은 model_pricing 이력 테이블에 기록됩니다. 현재 단가는 GET /admin/pricing으로 조회하고, POST /admin/pricing/refresh로 즉시 재동기화하거나, PUT /admin/pricing/override로 특정 모델의 단가를 수동 고정할 수 있습니다.

명시적 모델 지정

카탈로그 id는 vendor/model 형식입니다 — 예: anthropic/claude-fable-5, openai/gpt-5.2, deepseek/deepseek-v3.2. 전체 목록은 GET /v1/models로 조회합니다. 모델을 명시하면 라우팅을 거치지 않고 그대로 전달되며(classifier_score: null), 카탈로그에 없는 id는 404 model_not_found로 거부됩니다. 다만 warp.tier는 명시 모델에도 지출 상한으로 적용됩니다 — 상한을 넘는 모델을 지목하면 그 요청은 강제된 티어의 라우팅을 다시 타고, 예산 하향이 모델 이름을 하드코딩한 클라이언트만 비껴가지 않게 합니다.

요청별 warp 옵션

요청 본문의 warp 객체로 라우팅·캐시 동작을 요청 단위로 제어할 수 있습니다. 모든 필드는 선택 사항입니다.

{
  "model": "warp/auto",
  "messages": [{ "role": "user", "content": "핵심 API를 설계해줘" }],
  "warp": {
    "dial": "strict-quality",
    "anchor": "anthropic/claude-fable-5",
    "session_id": "conv_8f2a91",
    "context_compression": true,
    "no_cache": true
  }
}

Fallback 체인의 동작

• 재시도 조건 — 업스트림이 429, 5xx, 또는 인증·한도 오류(401·402·403)를 반환하거나 네트워크/타임아웃 오류가 나면 다음 후보로 자동 전환합니다 — 한 프로바이더의 키가 만료되거나 잔액이 떨어졌다고 요청 전체가 실패할 이유는 없기 때문입니다. 그 외 4xx(잘못된 요청 등)는 즉시 실패합니다 — 다만 잔액 소진·엔진 과부하처럼 “이 호스트가 못 한다”는 벤더 코드가 실려 오면 429처럼 다음 후보로 넘어갑니다.
• 전환 순서 — 같은 모델의 대체 프로바이더(altProviders, 예: DeepInfra → Novita)를 먼저 시도한 뒤, 다음 후보 모델로 넘어갑니다.
• 추적 — 시도한 경로는 응답 메타의 attempts 배열과 x-warp-attempts 헤더에 기록됩니다.
• 전부 실패 시 — 502 upstream_unavailable로 응답합니다.
• 예산 다운그레이드 — 키 또는 그 팀이 예산을 넘고 정책이 downgrade이면, 그 키의 모든 요청이 Tier 3로 강제됩니다 — 자동 라우팅도, 직접 지정한 모델도, warp/nitro도 같습니다. 거버넌스 참조.

응답 메타데이터

모든 응답에는 라우팅 결과가 본문 warp 필드와 x-warp-* 헤더로 붙습니다.

{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "model": "moonshot/kimi-k2.7-code",
  "choices": [ … ],
  "usage": { "prompt_tokens": 21, "completion_tokens": 96, "total_tokens": 117 },
  "warp": {
    "model": "moonshot/kimi-k2.7-code",
    "provider": "moonshot",
    "tier": 2,
    "classifier_score": 0.41,
    "cache_hit": null,
    "cost_usd": 0.000122,
    "saved_usd": 0.003886,
    "latency_ms": 842,
    "pii_masked": 0,
    "attempts": [],
    "dial": "balanced",
    "sticky": true,
    "pipeline": ["difficulty:0.41→tier2", "context:fit=3/3", "sticky:applied"],
    "guardrails": { "mode": "mask", "findings": 0, "blocked": false }
  }
}

스트리밍에서는 비용을 미리 알 수 없으므로 시작 시 x-warp-model · x-warp-tier · x-warp-dial · x-warp-strategy · x-warp-sticky · x-warp-attempts · x-warp-shadow · x-warp-guardrail-findings가 헤더로 나가고, 스트림의 마지막 데이터 청크(choices: [])에 usage와 warp 메타 전체가 담긴 뒤 data: [DONE]이 옵니다.