# 개요

> 키 하나와 base_url 하나로 글·그림·음성·임베딩까지 다섯 벤더를 씁니다.

> 원문: https://oneport.kr/docs

원포트 AI API 는 여러 벤더의 모델을 하나의 키와 하나의 주소로 묶어주는 게이트웨이예요. 쓰던 OpenAI SDK 나 Anthropic SDK 에서 base_url 만 바꾸면 그대로 돌아가요.

## 지금 부를 수 있는 것

글만 있는 게 아니에요. 그림·읽어주기·받아쓰기·임베딩·검열까지 같은 키로 부르실 수 있어요. 종류마다 부르는 주소가 다르고, 아래 표의 주소를 그대로 쓰시면 돼요.

지금 106개 모델을 5개 제공사에서 중계하고 있어요.

> **도구 호출(function calling)도 그대로 돼요**
>
> tools 를 같이 보내시면 벤더 형식으로 번역해 넘기고, 모델이 부른 도구를 OpenAI 형식으로 돌려드려요. 스트리밍도 같아요. MCP 를 쓰는 에이전트의 모델 자리에 그대로 넣으실 수 있어요 — MCP 서버는 그쪽에서 돌고 저희는 도구 호출을 중계해요. 다만 GPT-5.6·GPT-6 는 이 문에서 도구와 추론을 같이 못 써요 — 글 레퍼런스의 「GPT-5.6 · GPT-6 로 부를 때」를 보세요.

> **모델 단가는 벤더 공식가와 같아요**
>
> 크레딧이 각 벤더의 공식 단가 그대로 차감돼요. 우리 마진은 크레딧을 충전할 때 한 번만 붙고, 쓸 때는 붙지 않아요.

## 주소

| 형식 | base_url |
| --- | --- |
| OpenAI 호환 (Chat Completions) | https://oneport.kr/v1 |
| Anthropic 네이티브 (Messages) | https://oneport.kr |

OpenAI 형식으로 Claude 모델을 불러도 돼요. 게이트웨이가 요청과 응답을 번역해요 — 스트리밍도 포함이에요.

## 엔드포인트

| 메서드 | 경로 | 설명 |
| --- | --- | --- |
| POST | /v1/chat/completions | OpenAI 호환 채팅 |
| POST | /v1/messages | Anthropic 네이티브 Messages |
| POST | /v1/responses | OpenAI Responses — pro 등급은 이 문으로만 불려요 |
| POST | /v1/images/generations | 그림 만들기 |
| POST | /v1/images/edits | 있는 그림 고치기 |
| POST | /v1/audio/speech | 글을 소리로 (읽어주기) |
| POST | /v1/audio/transcriptions | 소리를 글로 (받아쓰기) |
| POST | /v1/embeddings | 검색·추천용 벡터 |
| POST | /v1/moderations | 부적절한 입력 걸러내기 (무료) |
| POST | /v1/videos | 영상 만들기 — 작업 id 가 바로 와요 |
| GET | /v1/videos/{id} | 영상이 끝났는지 · 얼마 들었는지 |
| GET | /v1/videos/{id}/content | 끝난 영상 mp4 받기 |
| GET | /v1/models | 쓸 수 있는 모델과 단가 |
| GET | /v1/credits | 남은 크레딧 |

## 왜 여기서 사나요

- 원화로 결제해요. 해외 결제 카드가 없어도 돼요.
- 세금계산서를 발행해요. 경비 처리가 되는 경로예요.
- 학교장터(S2B)로도 살 수 있어요.
- 한 경로가 막히면 자동으로 다른 경로로 재시도해요.
- 글·그림·음성은 프롬프트와 응답 본문을 저장하지 않아요. 사용량만 기록해요. 영상만 결과를 받으실 수 있게 요청 문장과 영상 파일을 7일 보관하고 지워요.

## 60초 만에 첫 호출

```bash
curl https://oneport.kr/v1/chat/completions \
  -H "Authorization: Bearer $ONEPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [{"role": "user", "content": "안녕하세요"}]
  }'
```

## 한도 — 분당 몇 건까지 되나요

「분당 몇 건」 제한을 두지 않아요. 수업 중에 서른 명이 한꺼번에 눌러도 저희 쪽에서 막지 않습니다. 대신 돈으로 막아요 — 키마다 이번 달 한도를 걸어두시면 그 키만 멈추고 나머지 분들은 그대로 쓰십니다.

- 402 — 계정 잔액이 모자랍니다. 부르기 전에 미리 나오니 요금이 붙지 않아요.
- 429 — 그 키의 이번 달 한도에 닿았어요. 대시보드에서 올리시면 바로 풀립니다.
- 429 (벤더가 낸 것) — 벤더가 잠시 조인 경우예요. 저희가 같은 모델의 다른 경로로 다시 걸어보고, 몇 번째에 됐는지 x-gateway-fallback-depth 헤더에 담아 드려요.

| 문 | 한 번에 기다리는 시간 | 보내실 수 있는 크기 |
| --- | --- | --- |
| 글 — /v1/chat/completions · /v1/messages · /v1/responses | 5분 | 요청 전체 4.5MB |
| 그림 — /v1/images/generations · /v1/images/edits | 2분 | 고칠 원본 4MB |
| 받아쓰기 — /v1/audio/transcriptions | 2분 | 오디오 4MB |
| 읽어주기 — /v1/audio/speech | 1분 | 요청 전체 4.5MB |
| 임베딩 — /v1/embeddings | 1분 | 요청 전체 4.5MB |
| 검열 — /v1/moderations | 30초 | 요청 전체 4.5MB |
| 영상 만들기·조회 — /v1/videos · /v1/videos/{id} | 1분 | 입력 그림 4MB |
| 영상 파일 — /v1/videos/{id}/content | 30초 | 본문 없음 |

> **⚠️ 시간을 넘기면 연결이 끊겨요**
>
> 표의 시간은 한 번의 호출이 응답을 다 받기까지 저희가 기다리는 시간이에요. 스트리밍도 같은 시계를 씁니다. 아주 긴 답이 필요하시면 stream 을 켜서 받는 대로 쓰시는 편이 안전해요.

> **⚠️ 요청 한 번은 4.5MB 까지예요**
>
> 모든 문이 같아요. 요청 몸통이 4.5MB 를 넘으면 저희 코드에 닿기 전에 서버가 413 으로 끊어요. 이때 오는 에러는 저희 JSON 형식이 아니라 영어 문장(FUNCTION_PAYLOAD_TOO_LARGE)이에요. 그림을 base64 로 여러 장 담으시거나 긴 녹음을 보내실 땐 나눠서 보내주세요.