AIGateway API
AI Agent용 안내: 이 페이지의 Markdown 버전은 https://ankole.agentbull.com/ko-KR/docs/ai-gateway/index.md, 전체 문서 색인은 https://ankole.agentbull.com/ko-KR/llms.txt에 있습니다.
AIGateway는 Ankole 배포 인스턴스의 통합 AI 호출 경계입니다. 외부 애플리케이션, 사내 시스템, SDK는 OpenResponses 호환 API로 AIGateway를 직접 호출하며, 내부 Agent 역시 모델 추론 턴을 실행할 때 동일한 인터페이스를 사용합니다. 모든 요청은 운영자가 구성한 provider 바인딩을 통해 모델 셀렉터를 해석하며, 업스트림 자격 증명은 컨트롤 플레인 외부로 절대 노출되지 않습니다.
이 문서에서는 실제 라우트와 요청 형식, 그리고 stateless 호출과 stateful 호출의 경계를 안내합니다. 정확한 세부 사양의 기준(source of truth)은 컨트롤 플레인 라우터와 Ankole.AIGateway 모듈이며, 이 문서는 전체 흐름을 파악하기 위한 안내 지도입니다.
위치
AIGateway는 호출자와 업스트림 provider 사이에 위치합니다. 외부 연동 시스템, OIDC로 인증된 사용자(Human), Worker 측 Agent 모델 루프는 HTTP, SSE, WebSocket으로 bearer 토큰과 함께 요청을 보내며, Ankole.Brain이나 Function Runtime 같은 컨트롤 플레인 내부 서브시스템은 내장 system Principal(ankole_brain, system) 명의로 프로세스 안에서 직접 Ankole.AIGateway를 호출합니다. 모든 호출에서 AIGateway가 모델 셀렉터를 해석해 요청을 조립한 뒤 연결된 provider로 전달하고 단일 JSON 본문이나 스트림을 반환합니다. LLM, 임베딩, 리랭크, 웹 검색, 웹 페이지 읽기 기능이 모두 이 경계를 거칩니다. 또한 응답 턴에서 programmatic_tool_calling을 사용하는 경우, AIGateway는 Ankole.FunctionRuntime.ProgramRunner를 통해 ankole-function-runtime의 stateless isolate에서 각 programmatic_tool_call의 TypeScript 프로그램을 실행합니다.
핵심 원칙은 명확합니다. 컨트롤 플레인이 자격 증명과 라우팅 정책을 전담 관리하므로 호출자는 업스트림 provider 자격 증명을 볼 수 없으며, 오직 자신의 호출 주체와 모델 셀렉터만 다룹니다.
인증
/api/v1/ai-gateway 하위 HTTP 및 WebSocket 엔드포인트는 모두 :ai_gateway_api 파이프라인과 RequireAIGatewayAccessToken 플러그를 거칩니다. 네트워크 호출자는 Authorization 헤더에 bearer 토큰을 담아 보내야 하며, 다음 두 종류의 토큰만 허용됩니다.
- Agent token — 활성 Agent Principal을 주체(subject)로 하는 AIGateway API 키입니다. 호출 범위는 해당 Agent의 유효 모델 프로필과 셀렉터로 제한되며
subject_type = "agent"로 동작합니다. - OIDC Human token —
ai_gateway.write권한을 가진 OIDC Client가 활성 사용자(Human)에게 발급한 토큰입니다. 해당 Client에 설정된 모델 별칭(model alias)만 호출할 수 있으며subject_type = "oidc_human"으로 동작합니다.
컨트롤 플레인의 퍼스트파티 서비스(Company Brain 작업을 수행하는 ankole_brain 등)는 외부 bearer 토큰을 발급하지 않고 BEAM 프로세스 내부에서 직접 Ankole.AIGateway를 호출하며, 사용량은 각 system Principal UID로 집계됩니다.
OIDC Human 토큰을 사용하려면 먼저 Console에서 ai_gateway.write 스코프를 가진 OIDC Client를 생성하고 허용할 그룹과 모델 별칭을 지정합니다. 이후 사용자는 PKCE를 적용한 Authorization Code 흐름으로 로그인하며, 장기 세션이 필요하면 offline_access를 요청해 순환 갱신되는(rotating) Refresh Token을 사용합니다. 사용자는 반드시 허용된 그룹에 속해 있어야 하며 해당 Client에 등록된 모델 별칭만 지정할 수 있고, 원시 provider_id/model 형식의 셀렉터는 직접 사용할 수 없습니다.
토큰이 누락되었거나 검증에 실패하면 code: "invalid_token"과 함께 401 응답을 반환하며, 익명 호출 경로는 지원하지 않습니다.
curl https://ankole.example.com/api/v1/ai-gateway/responses \
-H "Authorization: Bearer $AIGATEWAY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"model":"primary","input":"Summarize the open incidents."}'
엔드포인트
모든 라우트는 /api/v1/ai-gateway 아래에 열려 있습니다. 각 엔드포인트의 전송 방식(Transport)은 단순한 권장 사항이 아니라 API 계약의 일부입니다.
| 메서드 | 경로 | Transport | 용도 |
|---|---|---|---|
GET |
/models |
HTTP | 현재 주체(subject)가 사용할 수 있는 모델 셀렉터 목록 조회 |
POST |
/responses |
HTTP 또는 SSE | 응답 생성("stream": true 지정 시 스트리밍 전환) |
GET |
/responses |
WebSocket | 상태 보존형(stateful) 스트리밍 응답 |
GET |
/responses/:response_id |
HTTP | 저장된 stateful 응답(resp_{uuid}) 단건 조회 |
POST |
/embeddings |
HTTP | 임베딩 벡터 생성 |
POST |
/rerank |
HTTP | 문서 재정렬(rerank) |
POST |
/web_search |
HTTP | 웹 검색 |
POST |
/web_fetch |
HTTP | 웹 페이지 본문 가져오기 |
POST |
/decisions |
HTTP | 상태에 대한 유형 지정 질문에 확률과 함께 답변 |
POST |
/images |
HTTP | 이미지 한 장 생성 또는 편집 |
POST |
/audio/speech |
HTTP | 텍스트를 음성으로 변환 |
POST |
/audio/transcriptions |
HTTP | 오디오를 텍스트로 변환 |
POST |
/ocr |
HTTP | PDF 또는 문서 이미지를 Markdown으로 읽기 |
POST |
/videos |
HTTP | 동영상 생성 시작. GET /videos/:id로 작업을, GET /videos/:id/content로 파일을 읽기 |
POST |
/audio/music |
HTTP | 음악 생성 시작. GET /audio/music/:id로 작업을, GET /audio/music/:id/content로 파일을 읽기 |
GET/POST/DELETE |
/files, /files/:id, /files/:id/content |
HTTP | 파일 업로드, 조회, 다운로드, 삭제 |
이 인터페이스의 중심은 POST /responses입니다. 실제 모델 턴을 수행하며, 전송 프로토콜과 상태 보존 여부에 따라 동작이 분기하는 유일한 경로입니다.
HTTP와 SSE의 stateless 응답
stateless 호출은 단일 요청-단일 응답으로 완결됩니다. 호출자가 전체 input을 담아 보내면 AIGateway가 셀렉터를 해석하고 업스트림 provider를 호출한 뒤 완성된 JSON 본문을 반환합니다. 요청에 "stream": true를 지정하면 동일한 엔드포인트가 Server-Sent Events(SSE) 모드로 전환되어 event: <type>\ndata: <json>\n\n 형식의 이벤트를 순차 전송하고 마지막에 data: [DONE]으로 스트림을 닫습니다.
curl -N https://ankole.example.com/api/v1/ai-gateway/responses \
-H "Authorization: Bearer $AIGATEWAY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"model":"primary","input":"Draft a release note.","stream":true}'
stateless HTTP와 SSE는 previous_response_id, conversation, false 이외의 store 값을 거부합니다. store는 생략하거나 store: false로 지정할 수 있습니다. 여러 턴에 걸쳐 대화를 이어 가려면 WebSocket을 사용하세요. 금지된 필드를 HTTP나 SSE로 보내면 해당 필드 이름과 code: "stateful_responses_require_websocket"을 담은 400 응답을 반환합니다.
WebSocket의 stateful 응답
상태 보존형(stateful) 응답은 GET /responses 요청을 WebSocket으로 업그레이드하여 사용합니다. 업그레이드가 성립하면 컨트롤 플레인은 호출 주체의 identity, 30분 유휴 타임아웃(idle timeout), 프레임 압축, 128 MiB 최대 프레임 크기 제한을 적용해 연결을 AIGatewayResponsesSocket으로 인계합니다. 클라이언트는 모델 응답을 기다리는 동안 별도의 프레임을 보내지 않으므로, 이 30분 유휴 타임아웃이 단일 응답에 허용되는 최대 대기 시간이자 업스트림 모델의 첫 바이트 및 유휴 제한 시간과 동일하게 동작합니다. 이 WebSocket 연결에서는 store: true를 설정하고 previous_response_id나 conversation을 지정해 이전 대화를 그대로 이어 갈 수 있습니다.
대화 상태의 영구 수명 주기는 모두 이 경로에서 관리됩니다. 저장된 각 응답에는 resp_{uuid} 형식의 ID가 부여되며, 후속 턴에서는 previous_response_id로 직전 응답을 가리키거나 conversation으로 저장된 대화 스레드를 참조합니다. 연속성 검증, 영구 전사 기록, 컨텍스트 압축(compaction), 응답 투영, 장애 복구는 전적으로 컨트롤 플레인이 처리하므로 호출자가 직접 구현할 필요가 없습니다.
저장된 응답은 나중에 일반 HTTP 요청으로도 조회할 수 있습니다.
curl https://ankole.example.com/api/v1/ai-gateway/responses/resp_4f3c... \
-H "Authorization: Bearer $AIGATEWAY_TOKEN"
긴 대화 이력을 맥락 손실 없이 짧은 요약 상태로 압축할 때는 별도의 전용 엔드포인트 대신 compaction 기능을 사용합니다. 요청 input에 {"type": "compaction_trigger"} 항목을 넣어 보내면 AIGateway가 compaction 타입의 출력 항목 하나를 반환합니다. 이 기능은 모든 전송 방식에서 동일하게 작동하여 일반 POST /responses에서는 JSON 본문으로, "stream": true에서는 SSE 이벤트로, WebSocket에서는 소켓 이벤트로 결과를 돌려줍니다. 트리거만 단독으로 보내면 previous_response_id나 conversation이 가리키는 저장된 대화를 압축하고 다음 턴에서 이어 쓸 체크포인트 ID를 반환하며, 대화 이력을 input에 함께 담아 보내면 전달된 이력 자체를 압축합니다.
Provider 라우팅
AIGateway는 업스트림 API를 호출하기 전에 Console → Model Profiles에서 구성하는 3계층 희소 모델 프로필(Model Profile) 상속 체인(Site -> Pod -> Agent/System)에 따라 모델 셀렉터를 해석합니다.
- **Site, Pod 및
systemPrincipal(ankole_brain,system)**은 14개의 고정 슬롯을 제공합니다. 4개는 언어 모델 슬롯(primary,light,heavy,vision_fallback)이고 10개는 전용 capability 슬롯(web_search,web_fetch,image_generate,rerank,decision,speech,transcription,ocr,video,music)입니다. - Agent는
rerank,decision,speech,transcription,ocr,video,music을 제외한 7개 기본 슬롯과 사용자 지정 언어 모델 별칭을 제공하며, 비워 둔 슬롯은 Pod와 Site 기본값을 자동으로 상속합니다. - 슬롯 간 폴백은
heavy -> primary및light -> primary순서로 해석되므로 Site나 Pod에primary만 구성해도 Agent, Background Agent Job, Brain이 바로 동작하며, 필요한 경우에만 Pod·Agent·systemPrincipal 단위로 개별 재정의할 수 있습니다.
권한이 허용된 관리자와 내부 호출자는 명시적 provider_id/model 셀렉터도 직접 지정할 수 있습니다. GET /models를 호출하면 현재 주체가 사용할 수 있는 셀렉터 목록이 반환되며, OpenRouter 스타일의 검색 필터(q, context, min_price, max_price, sort, 모달리티 필터)를 선택적으로 전달할 수 있습니다.
각 provider 행은 자체 자격 증명 풀(credential pool)을 보유하며, 풀에 속한 모든 자격 증명은 동일한 provider 종류, 기본 URL, 헤더, 공통 설정, 지원 capability 선언을 공유합니다. 모델 프로필은 특정 풀 항목이 아니라 provider 행 자체를 가리키며, 런타임에 AIGateway가 설정된 분배 전략(fill_first, round_robin, least_used, random)에 따라 정상 상태인 자격 증명을 선택합니다. Console 화면에서는 이 전략 이름을 현재 UI 언어로 번역해 보여 주지만, API와 데이터베이스는 정규 영문 키를 그대로 사용합니다. stateful 대화 스레드는 가능한 한 처음 선택된 자격 증명을 계속 유지합니다.
호출 도중 특정 자격 증명에 귀속되는 429, 5xx, 또는 전송 오류가 발생하면 AIGateway는 해당 자격 증명에만 쿨다운을 걸고, 풀에서 다른 정상 자격 증명을 골라 요청을 다시 조립한 뒤 지수 백오프와 지터(jitter)를 적용해 정해진 횟수 안에서 재시도합니다. 이때 Rust 커널은 한 번에 단일 전송만 수행합니다. 만약 풀 안의 가용 자격 증명이 모두 소진되면 임의로 다른 provider로 우회(fallback)하지 않고 오류를 반환합니다.
chatgpt_subscription 역시 동일한 구조의 일반 provider 종류입니다. OAuth 자격 증명은 컨트롤 플레인 내부에만 보관되며 토큰 갱신은 데이터베이스 행 잠금(row lock) 아래에서 안전하게 수행되므로, Agent Computer나 외부 호출자에게 원본 토큰이 전달되지 않습니다.
agentbull_cloud(AgentBull Cloud, 기본 base URL https://cloudapis.agentbull.com)는 단일 API 키로 언어 모델, 임베딩, 리랭크, web_search, web_fetch, image_generate 기능을 모두 제공하는 내장 통합 provider입니다. 이 자격 증명 또한 컨트롤 플레인에만 보관되며, 외부 플랫폼 연결과 개인 OAuth 토큰, Skill이 선언한 원격 MCP 인증 헤더는 컨트롤 플레인의 Ankole.Connectors MCP 게이트웨이가 PostgreSQL에서 통합 관리합니다(WorkerEnv는 Agent Computer 내부의 사용자 지정 CLI 및 스크립트 환경 변수에 사용합니다).
셀렉터 해석 단계에서 발생할 수 있는 대표적인 구성 오류는 다음 두 가지입니다.
422 unknown_model_selector— 요청한 셀렉터가 현재 주체(subject)에 바인딩되어 있지 않습니다.422 model_binding_not_configured— 기능 이름과 프로필은 존재하지만 연결된 provider 바인딩 구성이 불완전합니다.
연결된 provider가 요청한 기능을 지원하지 않으면 422 unsupported_capability가 반환되고, 운영자가 비활성화해 둔 provider를 가리키면 422 provider_disabled가 반환됩니다. 이러한 422 응답은 일시적인 네트워크 장애가 아니라 설정 문제이므로, 설정을 수정하지 않은 채 재시도해도 결과는 바뀌지 않습니다.
오류 형태
모든 오류 응답은 {"error": {"code": "...", "message": "..."}} 형태의 OpenAI 호환 봉투(envelope) 형식을 따르며, 실패 유형에 맞는 HTTP 상태 코드를 반환합니다. 클라이언트 구현 시 대비해야 할 주요 상태 코드는 다음과 같습니다.
400— 요청 본문 검증 실패입니다.model또는input누락, 잘못된limit이나top_n값, 일반 HTTP 요청에 포함된 stateful 필드, 형식이 잘못된 compaction 입력 등이 해당하며code에서 원인 필드를 알려 줍니다.401— bearer 토큰이 없거나 유효성을 검증할 수 없습니다.429— 선택한 provider의 자격 증명 풀이 모두 소진되었습니다. 오류 코드는credential_pool_exhausted이며, 가장 빠른 쿨다운 해제 시점을 알 수 있는 경우retry_at시각이 함께 제공됩니다.404— 요청 주체 범위 안에서 지정한 저장 응답, 대화, Agent, 또는 파일을 찾을 수 없습니다.422— 요청 문법은 올바르지만 알 수 없는 셀렉터, 미완성 바인딩, 미지원 capability, 비활성 provider 등의 구성 문제로 컨트롤 플레인이 실행할 수 없습니다.502/504— 업스트림 provider 호출 실패입니다.502는 전송 오류나 비정상 응답(upstream_transport_failed,invalid_upstream_response,ai_gateway_request_failed)을 나타내고,504는 업스트림 응답 지연(upstream_timeout)을 나타냅니다. 업스트림 provider가 반환한 클라이언트 측4xx오류는 해당 상태 코드 그대로 전달됩니다.
업스트림 응답에 error.message가 들어 있으면 AIGateway가 그 메시지를 그대로 전달하고, 없으면 업스트림 HTTP 상태 정보를 반환합니다.
프로그래밍 방식 도구 호출 및 이미지 생성
/responses 요청에서 programmatic_tool_calling 도구를 선언하면 AIGateway는 대상 도구 명세들을 묶어 합성된 program 도구를 노출합니다. 모델이 programmatic_tool_call을 호출하면 AIGateway는 Ankole.FunctionRuntime.ProgramRunner를 통해 ankole-function-runtime의 stateless isolate에서 결정론적 TypeScript 프로그램을 실행하며, 중첩된 개별 도구 호출 경계에서 일시 중단했다가 재개하면서 실행 기록, 순서 보장, 취소를 직접 관리합니다.
공용 Responses 도구인 image_generation은 두 가지 경로로 실행됩니다. 주 언어 모델 provider가 Responses 형식에서 네이티브 이미지 생성을 지원하면 image_generate 프로필을 해석하지 않고 해당 provider에 도구를 전달합니다. 지원하지 않으면 호출 주체의 image_generate 프로필을 사용하며, 두 경로 모두 사용할 수 없으면 요청 준비 단계에서 오류를 반환합니다.
어느 경로로 실행되든 동일한 공용 스트림 이벤트가 발행되고 생성된 이미지가 영구 저장되며, 모델 토큰 사용량과 이미지 생성 사용량은 각각 실제로 호출된 자격 증명에 정확히 귀속됩니다.
Web tool, 파일, 그 밖의 capability
동일한 주체와 bearer 토큰으로 보조 AI 엔드포인트들도 호출할 수 있습니다. POST /web_search는 길이 제한이 있는 query를 받아 검색 결과를 반환하고, POST /web_fetch는 1~5개의 공개 HTTPS URL을 받아 본문 콘텐츠를 추출해 반환합니다. 두 엔드포인트에서는 web_search.default와 web_fetch.default 셀렉터를 지정할 수 있으며, 이 경우 AIGateway가 호출한 Agent의 현재 프로필 설정을 자동으로 찾아 연결합니다.
POST /embeddings는 문자열, 토큰 배열, 구조화된 입력 블록을 받아 임베딩을 생성하며 명시적인 provider_id/model 셀렉터를 요구합니다(예컨대 Ankole.Brain은 임베딩 생성 시 AppConfigure의 사이트 단위 설정 brain.embedding_model을 읽습니다). POST /rerank는 비어 있지 않은 문서 배열과 양의 정수 top_n을 받아 재정렬 결과를 반환하며, 명시적 provider_id/model 셀렉터 또는 default / rerank.default를 허용합니다(ankole_brain은 자신의 유효 rerank 모델 프로필을 해석하고, Agent 및 Human 호출은 Pod/Site rerank 프로필을 해석합니다. 검색 파이프라인의 상세 동작은 Brain을 참조하세요). 한편 Pod Applet의 ctx.ai 호출은 Ankole.Pod.Applets.Gateway를 통해 선택된 실행 Principal 명의로 무상태 실행됩니다. 언어 모델 프로필(primary, light, heavy, vision_fallback)을 해석할 때 Human은 유효한 Pod/Site 기본값을, Agent는 해당 Agent의 유효한 설정을 사용합니다. 사용량은 실행 Principal에 기록되며 대화형 Agent의 토큰 할당량을 소모하지 않습니다.
POST /web_search는 1,024자 이하의 query와 선택 항목인 limit(1100, 기본값 5)를 받아 64개의 items와 metadata를 반환합니다. 각 결과에는 url, title, description이 들어 있으며, Provider가 제공하면 published_at과 score도 함께 담깁니다. metadata에는 query, 게이트웨이에서 걸린 시간 latency_ms, HTTP 요청의 request_id가 들어 있습니다. POST /decisions는 주어진 state에 대해 유형이 지정된 질문에 답합니다. 요청 하나에 1questions를 담을 수 있고, 각 질문은 noul(예/아니요), choice(2255개의 이름 있는 선택지 중 하나), 10단계의 순서 있는 등급) 중 하나이며, 이미지는 장당 4 MiB 이하로 최대 4장까지 첨부할 수 있습니다. 응답은 질문마다 확률이 포함된 답과 함께 답한 score(2model, 토큰 usage를 반환합니다. default / decision.default 셀렉터는 Pod/Site의 decision 프로필로 해석됩니다. 이 프로필이 설정되어 있지 않으면 호출자의 light 언어 모델이 대신 답하며, 언어 모델이 내놓는 값은 스스로 보고한 확신도이므로 이 확률은 보정되지 않습니다. 또한 언어 모델이 답할 때는 요청 하나에 선택지와 등급을 합쳐 500개까지만 담을 수 있습니다.
decision 프로필에서는 TypeSafe(typesafe, 기본 URL https://api.typesafe.ai/v1), Microsoft Foundry를 사용하는 Azure OpenAI(azure_openai), OpenRouter(openrouter), OpenAI(openai), Google AI Studio(google_ai_studio_openai), Cloudflare(cloudflare)를 선택할 수 있습니다. TypeSafe의 base_url에는 다른 SystemOne 호환 엔드포인트도 지정할 수 있습니다. Azure Foundry는 구성한 배포 이름으로 <resource-root>/providers/microsoft/v1/systemone을 호출하고, OpenAI는 gpt-6-luna로 /decisions를, Google AI Studio는 gemini-decision-1로 /v1beta/decisions를 호출합니다. TypeSafe, Azure Foundry, OpenRouter가 사용하는 SystemOne 프로토콜은 PNG와 JPEG 자산만 받아들이며 WebP는 지원하지 않습니다. Microsoft-Decision-1은 이미지를 받아들이지 않습니다. OpenAI Decisions와 Google AI Studio Decisions는 PNG, JPEG, WebP를 지원합니다. OpenAI가 질문 하나라도 거부하거나 Google이 안전 필터(prompt_feedback.block_reason)로 프롬프트를 차단하면 AIGateway는 부분 답변을 반환하지 않고 전체 요청을 422 upstream_decision_refusal로 거부합니다.
POST /images는 대화 밖에서 이미지 한 장을 생성하거나 편집합니다. 요청에는 model(image_generate.default, default 또는 명시적인 provider_id/model), prompt, 선택 항목인 참조 이미지 images와 mask, 그리고 size, quality, output_format 같은 image_generation 도구 옵션을 담습니다. 요청은 선택한 이미지 Provider로 바로 전달됩니다. OpenRouter와 AgentBull Cloud는 각자의 카탈로그에 있는 이미지 모델을, Cloudflare는 FLUX.1 [schnell]과 Black Forest Labs 모델을 제공합니다. 응답은 created, 이미지를 b64_json과 media_type으로 담은 data 한 건, 그리고 Provider의 usage를 반환합니다. AIGateway는 생성한 이미지와 결정 모델 호출을 한 건씩 사용량 원장에 기록하며, Agent 토큰 할당량은 언어 모델 라운드만 집계합니다. Console의 모델 사용량 페이지는 이 토큰을 보여 주고, 그 밖의 기능은 호출 횟수, 수량, Provider가 보고한 비용을 별도의 표로 보여 줍니다.
POST /audio/speech는 input 텍스트를 음성으로 변환합니다. 요청에는 model(speech.default, default 또는 명시적인 provider_id/model)을 담고, 필요하면 voice, response_format(mp3, pcm, 또는 wav), speed, 말투를 지시하는 instructions를 함께 지정할 수 있습니다. 응답 본문은 오디오 자체입니다. 콘텐츠 유형은 Provider가 알려 준 오디오 유형을 따르며, Provider가 알려 주지 않으면 mp3는 audio/mpeg, pcm은 audio/pcm, wav는 audio/wav가 됩니다. OpenRouter는 카탈로그에 있는 음성 합성 모델을, Cloudflare는 Deepgram Aura 모델을 제공합니다. Deepgram Aura 모델은 MP3를 반환하며 pcm, wav, speed, instructions를 받지 않습니다. amazon-ai-providers Plugin을 활성화하면 Amazon Web Services Provider가 Amazon Polly를 제공합니다. 모델 이름은 neural 같은 Polly 엔진이며, 요청에 voice가 없으면 프로필에 설정한 음성을 사용합니다. china-market-ai-providers Plugin을 활성화하면 Alibaba Cloud DashScope(alibaba_cn, qwen3-tts-flash나 qwen3-tts-instruct-flash로 WAV 출력), Volcengine Doubao Speech(volcengine_speech, voice 필수 지정 후 MP3 또는 PCM 출력), DeepSeek(deepseek, /chat/completions 언어 모델과 함께 /v1/tools/tts로 WAV 또는 PCM 출력)도 음성 합성을 제공합니다. POST /audio/transcriptions는 오디오를 텍스트로 변환합니다. 요청에는 model(transcription.default, default 또는 명시적인 provider_id/model)과 input_audio를 담습니다. input_audio에는 base64로 인코딩한, 디코딩 후 25 MiB 이하의 data와 그 format이 들어가며, 필요하면 language, vad_filter 플래그, response_format(json 또는 verbose_json, 기본값 json)을 추가할 수 있습니다. 응답은 model, text, 그리고 오디오 길이를 seconds로 담은 usage를 반환하며, verbose_json을 지정하면 language, duration, 시간 정보가 붙은 segments가 추가됩니다. OpenRouter는 카탈로그에 있는 음성 인식 모델을, Cloudflare는 @cf/openai/whisper-large-v3-turbo처럼 base64 오디오를 받는 Workers AI 모델을 제공하며, china-market-ai-providers를 활성화하면 Alibaba Cloud DashScope(alibaba_cn, qwen3-asr-flash), Volcengine Doubao Speech(volcengine_speech), DeepSeek(deepseek)도 사용할 수 있습니다. 두 엔드포인트 모두 폴백이 없으므로, 해당 프로필을 바인딩하기 전까지 요청은 model_profile_not_configured로 실패합니다. AIGateway는 음성 합성 호출을 글자 수와 함께, 음성 인식 호출을 오디오 초 수와 함께 한 건씩 사용량 원장에 기록합니다.
POST /ocr는 PDF 또는 문서 이미지를 페이지별로 Markdown으로 읽어 냅니다. 요청에는 document를 담습니다. document는 PDF 또는 PNG, JPEG, WebP 이미지 한 장이며, base64 data URL로 보내거나 content_type과 base64를 가진 객체로 보냅니다. AIGateway는 50 MiB 이하의 PDF와 20 MiB 이하의 이미지를 받으며, 두 상한 모두 디코딩 후 크기를 기준으로 합니다. OCR 모델이 받는 크기는 이보다 작을 수 있습니다. PDF라면 pages에 0부터 시작하는 페이지 인덱스를 중복 없이 1~100개 지정할 수 있습니다. 요청에서 pages를 생략하면 AIGateway는 OCR 모델에 페이지 인덱스를 보내지 않습니다. 응답은 model, pages, 그리고 usage를 반환하며, usage에는 읽은 페이지 수가 pages로 담깁니다. pages의 각 항목에는 Provider가 보고한 index와 그 페이지의 markdown이 담기고, 텍스트가 없는 페이지는 markdown이 비어 있습니다. AIGateway는 페이지를 index 순으로 정렬합니다. default / ocr.default 셀렉터는 Pod/Site의 ocr 프로필로 해석되며, 이 프로필의 OCR 모델은 Mistral Provider가 제공합니다. amazon-ai-providers Plugin을 활성화하면 Amazon Web Services Provider가 Amazon Textract를 제공합니다. Textract는 PNG 또는 JPEG 이미지나 한 페이지짜리 PDF를 읽으며 pages는 받지 않습니다. china-market-ai-providers Plugin을 활성화하면 Alibaba Cloud DashScope(alibaba_cn, qwen-vl-ocr나 qwen3.5-ocr로 PNG, JPEG, WebP 이미지 인식), Volcengine Visual(volcengine_visual, 이미지는 OCRNormal, PDF는 OCRPdf로 인식), DeepSeek(deepseek, /v1/tools/ocr로 이미지와 PDF 인식)도 pages 없이 POST /ocr를 제공합니다. 이 프로필이 설정되어 있지 않으면 이미지 입력을 지원하는 언어 모델이 대신 문서를 읽습니다. 호출자의 vision_fallback 프로필을 사용하고, 그 프로필도 설정되어 있지 않으면 primary를 사용합니다. 언어 모델은 이미지 한 장만 읽을 수 있으므로 PDF를 보내면 unsupported_value로 실패합니다. 또한 언어 모델이 읽은 요청은 일반 언어 모델 요청으로 집계됩니다. AIGateway는 OCR 모델 호출을 페이지 수와 함께 한 건씩 사용량 원장에 기록합니다.
POST /videos와 POST /audio/music이 시작한 생성은 Provider가 나중에 끝내므로, 두 엔드포인트는 202와 함께 미디어 작업을 반환합니다. 작업에는 id, status, model, created_at, expires_at이 들어 있습니다. 요청에는 model(video.default 또는 music.default, default, 혹은 명시적인 provider_id/model)과 prompt를 담습니다. 동영상 요청에는 초 단위의 duration, resolution, aspect_ratio, size, generate_audio, seed와 함께 first_frame, last_frame도 지정할 수 있으며, 각 프레임은 https URL이거나 10 MiB 이하 이미지의 base64 데이터 URL입니다. 음악 요청에는 lyrics, instrumental, 초 단위의 duration을 지정할 수 있습니다. status가 completed 또는 failed가 될 때까지 GET /videos/:id 또는 GET /audio/music/:id로 작업을 읽으세요. 완료된 작업에는 파일의 content_type과 size가, 실패한 작업에는 error가 들어 있습니다. 그다음 GET /videos/:id/content와 GET /audio/music/:id/content가 파일을 보내며 Range 헤더도 지원합니다. AIGateway는 작업과 파일을 7일 동안 보관합니다. video 프로필에는 OpenRouter(openrouter)의 동영상 모델을, music 프로필에는 minimax/music-2.6이나 elevenlabs/music-v2 같은 Cloudflare(cloudflare) Workers AI 파트너 모델을 선택할 수 있습니다. 두 프로필 모두 언어 모델 폴백이 없습니다.
파일 관리 역시 일급 API로 제공됩니다. POST /files로 업로드하고, GET /files로 목록을 조회하며, GET /files/:id와 GET /files/:id/content로 메타데이터와 파일 바이트를 읽고, DELETE /files/:id로 삭제합니다. 모든 파일 작업은 호출 주체(subject) 범위로 격리됩니다.
AIGateway가 아닌 것
AIGateway는 인증 없이 열려 있는 공개 프록시가 아니며, 클라이언트가 직접 업스트림 API 키를 실어 보내는 패스스루 게이트웨이도 아닙니다. 모든 업스트림 자격 증명은 컨트롤 플레인 내부에 머뭅니다. 여러 단계에 걸친 Agent 작업은 Sessions와 Background Agent Jobs가 담당합니다. AIGateway는 모델과 미디어 호출을 관리하며, 나중에 폴링하도록 202를 반환하는 비동기 미디어 작업도 처리합니다. 셀렉터 해석과 provider 자격 증명 보관은 control plane에서 수행합니다.
다음 단계
- 전체 시스템 안에서 AIGateway의 위치를 파악하려면 아키텍처 개요를 참조하세요.
- 이 엔드포인트를 호스팅하는 서버 구동 방법은 빠른 시작의 deployment 섹션을 참조하세요.
- 첫 Provider 등록과 모델 프로필 구성은 빠른 시작을 참조하세요.