개요
키 하나와 base_url 하나로 여러 회사의 글·그림·음성·임베딩 모델을 씁니다.
원포트 AI API 는 여러 벤더의 모델을 하나의 키와 하나의 주소로 묶어주는 게이트웨이예요. 쓰던 OpenAI SDK 나 Anthropic SDK 에서 base_url 만 바꾸면 그대로 돌아가요.
지금 부를 수 있는 것#
글만 있는 게 아니에요. 그림·읽어주기·받아쓰기·임베딩·검열까지 같은 키로 부르실 수 있어요. 종류마다 부르는 주소가 다르고, 아래 표의 주소를 그대로 쓰시면 돼요.
| 종류 | 모델 | 부르는 주소 |
|---|---|---|
| 글 | 81개 | POST /v1/chat/completions |
| 그림 | 11개 | POST /v1/images/generations |
| 임베딩 | 5개 | POST /v1/embeddings |
| 검열 | 2개 | POST /v1/moderations |
| 읽어주기 | 2개 | POST /v1/audio/speech |
| 받아쓰기 | 7개 | POST /v1/audio/transcriptions |
| Responses 전용 | 6개 | POST /v1/responses |
| 영상 | 7개 | POST /v1/videos |
| 판정 | 1개 | POST /v1/decisions |
모두 합쳐 122개예요. 지금 부를 수 없는 모델은 아예 목록에 넣지 않아요 — 목록에 있는데 부르면 안 되는 게 제일 나쁘거든요. 찾는 모델이 없으면 도입 문의로 알려 주세요.
주소#
| 형식 | 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/messages/count_tokens | Claude 요청의 입력 토큰 미리 세기 (무료) |
| 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/decisions | 질문에 답과 확률만 받는 판정 (출력 값 없음) |
| POST | /v1/videos | 영상 만들기 — 작업 id 가 바로 와요 |
| GET | /v1/videos | 만든 영상 목록 |
| GET | /v1/videos/{id} | 영상이 끝났는지 · 얼마 들었는지 |
| DELETE | /v1/videos/{id} | 영상 지우기 |
| GET | /v1/videos/{id}/content | 끝난 영상 mp4 받기 |
| POST | /v1/tasks | 작업 맡기기 — 진행과 정산은 작업 id 로 봐요 |
| GET · DELETE | /v1/tasks/{id} | 작업 상태 보기 · 취소 |
| GET | /v1/tasks/{id}/events | 작업 진행 기록 |
| GET | /v1/tasks/{id}/files/{fileId} | 작업 결과 파일 받기 |
| GET | /v1/models | 쓸 수 있는 모델과 단가 |
| GET | /v1/models/{id} | 모델 하나 — 이 키로 부를 수 있을 때만 |
| GET | /v1/credits | 남은 크레딧 |
| GET | /v1/key | 이 키의 오늘 · 이번 달 남은 한도와 기한 |
| GET · POST | /v1/keys | 관리 키로 API 키 목록 보기 · 만들기 |
| GET · PATCH · DELETE | /v1/keys/{id} | 관리 키로 API 키 하나 보기 · 고치기 · 끄기 |
왜 여기서 사나요#
- 원화로 결제해요. 해외 결제 카드가 없어도 돼요.
- 세금계산서를 발행해요. 경비 처리가 되는 경로예요.
- 학교장터(S2B)로도 살 수 있어요.
- 실행 전 거절이 확인된 경로만 다른 경로로 넘겨요. 모델 회사로 보낸 뒤 실행 여부가 불명하면 멈춰요.
- 일반 생성 API의 글·그림·음성은 프롬프트와 응답 본문을 저장하지 않고 사용량만 기록해요. 모델 회사가 요청을 거절하면 그 회사가 준 이유 문장을 200자 안으로 줄여 같이 남겨요(그 문장에 보내신 값이 일부 들어 있을 수 있어요). 영상은 요청 문장과 파일을 7일 보관해요. 작업 API는 맡긴 글·진행 기록·결과 답과 파일을 저장해요.
60초 만에 첫 호출#
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": "안녕하세요"}]
}'GPT 는 model 만 바꾸면 돼요(예: gpt-5.4-mini). GPT-5.6 · GPT-6 은 gpt-5.6-sol · gpt-6-sol 처럼 등급이 붙은 id 예요. 이름은 GET /v1/models 의 id 를 그대로 쓰세요. 키는 크레딧을 산 곳(스쿨오더 · 오피스오더) 대시보드의 AI API 화면에서 만들어요.
한도 — 분당 몇 건까지 되나요#
「분당 몇 건」 제한을 두지 않아요. 수업 중에 서른 명이 한꺼번에 눌러도 저희 쪽에서 막지 않습니다. 대신 돈으로 막아요 — 키마다 이번 달 한도나 하루 한도를 걸어두시면 그 키만 멈추고 나머지 분들은 그대로 쓰십니다. 하루 한도는 한국 시간 0시에, 월 한도는 1일에 다시 열려요. 하루 한도는 그날 쓴 것이 한도에 닿으면 막기 때문에 그날 마지막 한 번과 그 순간 동시에 보낸 호출만큼 넘을 수 있어요.
- 402 insufficient_credit — 잔액이 이 요청이 최대로 쓸 몫보다 적어요. 부르기 전에 나오니 요금이 붙지 않아요. max_tokens 를 줄이면 통과할 수 있어요.
- 429 key_limit_exceeded — 그 키의 이번 달 한도나 오늘 한도에 닿았어요. 이번 달 한도는 「쓴 몫 + 이 키로 아직 끝나지 않은 몫 + 이 요청이 최대로 쓸 몫」으로, 오늘 한도는 이미 쓴 몫만으로 재요. 대시보드에서 올리시면 바로 풀립니다. 바로 다시 보내면 같아요 — 다만 error.reason 이 held_by_others 면 같은 키로 아직 끝나지 않은 호출 몫 때문이라 Retry-After(5초) 뒤 그대로 보내면 돼요(「에러」 장).
- 429 rate_limit_error — 벤더가 조였어요. 글 문은 같은 모델의 다른 경로까지 다시 걸어 봤는데도 막힌 거라 잠시 뒤 다시 보내 주세요. 몇 번째에 됐는지는 x-gateway-fallback-depth 헤더에 담아 드려요.
| 문 | 한 번에 기다리는 시간 | 보내실 수 있는 크기 |
|---|---|---|
| 글 — /v1/chat/completions · /v1/messages · /v1/responses | 13분 20초 | 요청 전체 4.5MB |
| 그림 — /v1/images/generations · /v1/images/edits | 2분 | 고칠 원본 4MB |
| 받아쓰기 — /v1/audio/transcriptions | 2분 | 오디오 4MB |
| 읽어주기 — /v1/audio/speech | 5분 | 요청 전체 4.5MB |
| 임베딩 — /v1/embeddings | 1분 | 요청 전체 4.5MB |
| 검열 — /v1/moderations | 30초 | 요청 전체 4.5MB |
| 판정 — /v1/decisions | 1분 30초 | 요청 전체 4.5MB |
| 영상 만들기·조회 — /v1/videos · /v1/videos/{id} | 1분 | 입력 그림 4MB |
| 영상 파일 — /v1/videos/{id}/content | 2분 | 본문 없음 |
| 작업 생성 — /v1/tasks | 5분 | JSON 0.1MB |
| 작업 조회·취소·이벤트 — /v1/tasks/{id} · /v1/tasks/{id}/events | 5분 | 본문 없음 |
| 작업 결과 파일 — /v1/tasks/{id}/files/{fileId} | 1분 | 본문 없음 |