본문으로 건너뛰기
원포트 AI

curl

가장 단순한 확인 방법.

AI 에게 넘기기ChatGPT 에서 열기 (새 창)Claude 에서 열기 (새 창)원문 열기
논스트리밍
curl https://oneport.kr/v1/chat/completions \
  -H "Authorization: Bearer $ONEPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-haiku-5-5",
    "max_tokens": 2000,
    "messages": [{"role": "user", "content": "안녕하세요"}]
  }'

이 장 예의 모델 id(claude-haiku-5-5 · claude-sonnet-5 · gpt-5.6-terra · claude-opus-5 · gpt-5-nano)는 모두 GET /v1/models 에 있는 이름이에요(10월 기준) — 바꾸실 땐 거기서 고르세요. 답은 choices[0].message.content 예요. finish_reason 이 stop 이면 끝까지 온 것이고, length 면 길이 상한에서 잘린 거예요. 쓴 양은 usage 의 prompt_tokens · completion_tokens 예요. 출력 상한은 max_tokens 로 적으면 돼요 — max_completion_tokens 만 받는 GPT 모델이면 저희가 옮겨 보내고 응답 머리글 x-gateway-mapped-params 에 적어요. 안 적으면 미리 잡아 두는 몫(예약)을 출력 8,192 토큰으로 셈해요. GPT-5 이후 · o 계열 같은 생각하는 GPT(GET /v1/models 의 supports_effort 가 true — 아래 「싼 공식 GPT 하나 고르기」로 고른 모델도 대개 그래요)는 생각한 토큰도 이 상한에 들어가요(벤더 동작) — max_tokens 를 수백으로 줄이면 답이 비고 finish_reason 이 length 로 끝날 수 있어요. 짧게 받으려면 reasoning_effort 를 "low"(GPT-5 · 5-mini · 5-nano 는 "minimal" 도)로 같이 보내거나 상한을 넉넉히 두세요. supports_effort 가 false 인 GPT · Claude 에 reasoning_effort 를 실어 보내셔도 오류는 안 나요 — 저희가 그 칸을 빼고 보내고 응답 머리글 x-gateway-ignored-params 에 적어요. 그래서 모델을 목록에서 바꿔 끼우는 스크립트도 이 칸을 늘 실어 두셔도 돼요.

스트리밍
curl -N https://oneport.kr/v1/chat/completions \
  -H "Authorization: Bearer $ONEPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [{"role": "user", "content": "안녕하세요"}],
    "stream": true
  }'

줄은 data: {…} 꼴로 와요. 글은 choices[0].delta.content 에 있고, 끝에 choices 가 빈 배열인 usage 조각이 오고(그 usage 의 cost_credits 가 이 호출에 쓴 값 · 정산이 2초 안에 안 끝나면 없어요), 마지막 줄은 data: [DONE] 이에요. 도중에 실패하면 data: {"error": {"type", "code", "message"}} 조각이 와요(「에러」 장). 글만 이어 찍으려면 curl -sN … | sed -un 's/^data: //p' | jq -Rrj --unbuffered 'fromjson? | .choices[0]?.delta.content // empty' 처럼 받으세요. stream: true 로 보냈어도 시작 전에 막히면(401 · 402 · 404 · 429 · 벤더 거절) data: 줄이 아니라 JSON 오류 몸통이 그 상태 코드로 와요 — 상태가 200 이 아니면 몸통을 JSON 으로 읽으세요(-D headers.txt 로 머리글을 파일에 받으면 상태를 볼 수 있어요 · curl 동작). 200 으로 시작한 뒤엔 상태 코드 · x-should-retry 머리글이 다시 오지 않아요. stream: true 여도 모델 회사로 보낸 뒤 첫 응답 전에 시간이 끝나거나 연결이 끊기면 data: 줄이 아니라 422 upstream_execution_unconfirmed JSON 몸통(x-should-retry: false)이 와요. 이 응답엔 요금이 안 붙지만 모델 회사에서 이미 실행됐을 수 있어서 자동 재전송하지 마세요. Idempotency-Key 를 실어 보낸 요청이면 받은 x-gateway-status-url 을 같은 API 키로 GET 조회하세요. Idempotency-Key 없이 보낸 요청엔 조회 주소가 안 오고 요청 ID 로 만든 주소로는 조회가 안 돼요 — 요청 ID 와 부른 시각을 admin@schoolorder.kr 로 알려 주세요. 200 뒤에 저희 시간 제한이나 연결 끊김으로 닫히면 마지막 줄이 data: {"error": {"type": "upstream_error", …}} 조각이에요 — Claude 밖 모델은 usage 조각 없이 이 조각 하나로 끝나고, Claude 는 그 앞에 그때까지의 usage 조각이 와요. error 조각이 오거나 finish_reason 없이 닫히면 그때까지 쓴 몫은 이미 사용됐으니, 처음부터 다시 보내지 말고 받은 글로 이어 받으세요(「에러」 장 「잘린 답 이어 받기」).

Anthropic 네이티브
curl https://oneport.kr/v1/messages \
  -H "x-api-key: $ONEPORT_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "안녕하세요"}]
  }'

답은 Anthropic 꼴 그대로예요 — 글은 content[] 가운데 type 이 text 인 것의 text 이고(jq -r '[.content[] | select(.type=="text") | .text] | join("")'), 잘렸으면 stop_reason 이 max_tokens, 쓴 양은 usage.input_tokens · output_tokens 예요.

그림 한 장 붙여 묻기#

그림을 data: 주소로 실어 보내기
IMG=photo.jpg
base64 < "$IMG" | tr -d '\n' > img.b64
jq -n --rawfile b img.b64 '{
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{role: "user", content: [
    {type: "text", text: "이 그림에서 무엇이 보여요?"},
    {type: "image_url", image_url: {url: ("data:image/jpeg;base64," + $b)}}
  ]}]
}' > body.json
curl -s https://oneport.kr/v1/chat/completions \
  -H "Authorization: Bearer $ONEPORT_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @body.json | jq -r '.choices[0].message.content'

그림은 content 를 배열로 보내고 image_url 조각에 data: 주소나 https 주소를 넣어요. Claude 로 갈 땐 저희가 Claude 그림 형식으로 옮기고, 다른 모델엔 그대로 넘겨요. base64 는 길어서 jq --arg 로 넘기면 명령줄 길이 한도에 걸리니 --rawfile 로 파일째 넘기세요(셸 동작). /v1/models 엔 그림을 보는지 알려 주는 칸이 없어요 — 글만 받는 모델이면 벤더가 거절할 수 있어요(4xx upstream_error).

요청 한 번은 4.5MB 까지예요. base64 는 원본보다 3분의 4배(약 1.33배)쯤 커지니 원본은 3MB 아래로 줄이세요. 넘으면 저희 코드에 닿기 전에 413 이 와요 — 몸통이 JSON 이 아닌 글자(FUNCTION_PAYLOAD_TOO_LARGE)라 error.type 이 없으니 상태 코드 413 으로 가르세요. 미리 잡는 몫은 그림 한 장을 바이트가 아니라 정해진 토큰 수까지만 셈해요(Claude 는 한 장에 4,800 토큰).

도구 호출#

tools 를 실어 보내기
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": "서울 날씨 알려줘"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "도시의 지금 날씨",
        "parameters": {
          "type": "object",
          "properties": { "city": { "type": "string" } },
          "required": ["city"]
        }
      }
    }]
  }'

그 밖의 문#

임베딩 · 검열 · 읽어주기
# 임베딩
curl https://oneport.kr/v1/embeddings \
  -H "Authorization: Bearer $ONEPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "text-embedding-3-small", "input": "3학년 분수 단원" }'

# 검열 (무료)
curl https://oneport.kr/v1/moderations \
  -H "Authorization: Bearer $ONEPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "input": "검사할 문장" }'

# 읽어주기 (오디오가 그대로 와요)
curl https://oneport.kr/v1/audio/speech \
  -H "Authorization: Bearer $ONEPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "tts-1", "input": "오늘 급식은 김치찌개입니다.", "voice": "alloy" }' \
  --output speech.mp3

Windows PowerShell#

Windows PowerShell 에서는 curl 대신 curl.exe 로 적어요(5.1 의 curl 은 Invoke-WebRequest 별칭이에요 · OS 동작). 위 예처럼 작은따옴표 JSON 을 -d 로 넘기면 PowerShell 5.1 이 안쪽 큰따옴표를 지워서 400 「JSON 본문을 읽을 수 없어요.」가 나요(PowerShell 동작). 몸통은 UTF-8 파일로 써서 --data-binary "@body.json" 으로 보내세요 — 저희는 보낸 몸통을 늘 UTF-8 로 읽어서 Content-Type 에 charset 을 붙이든 안 붙이든 같아요. BOM 이 붙어도 괜찮아요 — Set-Content -Encoding UTF8 로 쓰셔도 되고, [IO.File]::WriteAllText("$PWD\body.json", $json) 처럼 쓰면 BOM 없이 써져요. 키는 $env:ONEPORT_API_KEY 로 읽어요. 응답도 늘 UTF-8 이고 모든 /v1 JSON 응답이 Content-Type 에 charset=utf-8 을 달아서, 받은 답의 한글은 Invoke-RestMethod · Invoke-WebRequest 에서도 안 깨져요. 보낼 때는 curl.exe 와 파일이 가장 확실해요 — Invoke-RestMethod 로 보내시려면 -Body 에 [Text.Encoding]::UTF8.GetBytes($json) 처럼 바이트를 넘기세요(PowerShell 동작). 받은 글이 그래도 깨지면 curl.exe -o out.json 으로 받아 [IO.File]::ReadAllText("$PWD\out.json", [Text.Encoding]::UTF8) 로 읽으세요 — .NET 은 cd 로 옮긴 폴더를 모르니 경로를 끝까지 적어요(PowerShell 동작). 한글이 든 .ps1 은 「UTF-8(BOM)」으로 저장하세요 — PowerShell 5.1 은 BOM 없는 스크립트를 한국어 ANSI 로 읽어 안의 한글이 깨져요(PowerShell 동작).

Windows PowerShell 5.1 — 파일로 보내고 파일로 읽기
$json = '{"model": "gpt-5-nano", "messages": [{"role": "user", "content": "안녕하세요"}], "max_tokens": 2000, "reasoning_effort": "minimal"}'
[IO.File]::WriteAllText("$PWD\body.json", $json)
$code = curl.exe -sS -D headers.txt -o out.json -w "%{http_code}" https://oneport.kr/v1/chat/completions -H "Authorization: Bearer $env:ONEPORT_API_KEY" -H "Content-Type: application/json" --data-binary "@body.json"
$r = if ($code -ne "000") { Get-Content out.json -Raw -Encoding UTF8 | ConvertFrom-Json }
if ($code -eq "000") { "응답 없음 — 위에 curl 이 찍은 이유를 보세요" } elseif ($code -eq "200") { $r.choices[0].message.content; "finish_reason: $($r.choices[0].finish_reason) · cost_credits: $($r.usage.cost_credits)" } else { "$code $($r.error.type) $($r.error.reason)"; $r.error.message; "request_id: $($r.error.request_id)" }

상태가 000 이 아니면 다시 보내기 전에 Select-String -Path headers.txt -Pattern 'x-should-retry|retry-after' 로 머리글을 보세요(PowerShell 동작). -s 만 쓰면 연결 오류 문장까지 숨어요 — -sS 면 저희 응답을 못 받았을 때 curl 이 이유를 한 줄 찍고 %{http_code} 는 000 이에요(curl 동작). 그 이유가 Could not resolve host · Failed to connect · SSL(schannel) 오류처럼 보내기 전 실패면 저희에게 닿지 못한 거라 학교 · 회사망 차단이나 프록시를 먼저 봐 주세요. 보내고 기다리다 끊긴 000(Operation timed out · Connection reset · Empty reply from server)은 실행 불명이라 아래 「curl 로 다시 보낼 때」대로 해요.

확인용 세 줄#

요금 없이 키 · 잔액 · 모델 보기
# 키가 살아 있는지 · 이번 달(month) · 오늘(day) 남은 몫 (틀린 키면 401 과 이유)
curl https://oneport.kr/v1/key -H "Authorization: Bearer $ONEPORT_API_KEY"

# 지갑 잔액 (balance_credits)
curl https://oneport.kr/v1/credits -H "Authorization: Bearer $ONEPORT_API_KEY"

# 이 키로 부를 수 있는 모델 — 키를 빼면 전체 목록이 와서 못 부르는 모델도 섞여요
curl https://oneport.kr/v1/models -H "Authorization: Bearer $ONEPORT_API_KEY"
같은 확인 — Windows PowerShell
$env:ONEPORT_API_KEY = (Read-Host "sk-so- 키").Trim()
curl.exe -sS -o key.json https://oneport.kr/v1/key -H "Authorization: Bearer $env:ONEPORT_API_KEY"
curl.exe -sS -o credits.json https://oneport.kr/v1/credits -H "Authorization: Bearer $env:ONEPORT_API_KEY"
$k = Get-Content key.json -Raw -Encoding UTF8 | ConvertFrom-Json
$c = Get-Content credits.json -Raw -Encoding UTF8 | ConvertFrom-Json
if ($k.error) { "$($k.error.reason) $($k.error.message)" } else { "잔액 $($c.balance_credits) · 이번 달 남은 몫 $($k.month.remaining_credits) · 오늘 남은 몫 $($k.day.remaining_credits)" }

month · day 안의 remaining_credits 가 남은 몫이에요. 한도를 안 건 키면 null 이고(PowerShell 에선 빈칸으로 찍혀요) 그땐 지갑 잔액까지 써요. $env: 로 넣은 키는 그 창에서만 있어요 — 새 창에서도 쓰려면 [Environment]::SetEnvironmentVariable("ONEPORT_API_KEY", $env:ONEPORT_API_KEY, "User") 로 저장하고 창을 새로 여세요(PowerShell 동작). 키가 틀리면 세 줄 다 401 과 이유가 와요(키를 잠깐 못 읽었으면 503 — 아래 문단).

cron 처럼 키를 파일에 두실 땐 printf 'Authorization: Bearer %s\n' "$(cat 키파일)" > auth.h 로 머리글 파일을 한 번 만들고(chmod 600 auth.h) curl -H @auth.h … 로 보내세요 — 키가 명령줄(ps)에 안 남아요(curl 7.55 이상 · curl 동작). auth.h 에 키 전체가 들어 있어서 이 파일이 곧 비밀이에요 — 만든 뒤 원래 키 파일은 지워도 되고, umask 077; read -rs k; printf 'Authorization: Bearer %s\n' "$k" > auth.h 로 키 파일 없이 만들어도 돼요(bash 동작). 키 파일을 root 만 읽게 두셨으면 그 cron 도 root 로 돌려야 해요 — 못 읽으면 빈 키가 실려 401 「API 키가 없어요.」가 와요. 머리글은 Authorization: Bearer 나 x-api-key 둘 다 받아요.

두 조회 문(/v1/key · /v1/credits)의 답은 200 · 401(갈래는 error.reason) · 503 api_error(키나 잔액을 잠깐 못 읽음 · Retry-After: 2) 셋이에요. 한도에 닿은 키나 잔액이 0 인 지갑도 조회는 200 이고 429 · 402 는 안 와요. 조회 문은 요금도 부작용도 없어서 연결 오류(상태 000)나 503 이면 그대로 다시 불러도 돼요 — 아래 「알 수 없는 5xx 는 자동 재시도하지 마세요」는 모델을 부르는 문 얘기예요.

응답은 이렇게 와요 — /v1/credits 는 {"object": "credit_balance", "balance_credits": 1234, "purchased_credits": …, "used_credits": …, "key_prefix": …, "wallet_id": "wal_…"}, /v1/key 는 {"object": "key", "key_prefix": …, "wallet_id": "wal_…", …, "month": {"limit_credits": null, "used_credits": 12, "remaining_credits": null, "resets_at": "2026-10-31T15:00:00.000Z"}, "day": {…}, "group": null} 예요. resets_at 은 UTC ISO 시각이에요(이 값은 한국 시간 11월 1일 0시). 밀리초(.000Z)가 붙어 있어서 jq 의 fromdate 는 그대로 못 읽어요 — jq '.month.resets_at | sub("\\.[0-9]+Z$"; "Z") | fromdate' 처럼 떼고 읽어요(jq 1.7 동작). /v1/credits 의 used_credits 는 지갑이 지금까지 쓴 몫의 합이라 보통 늘기만 하지만, 쓴 몫을 돌려받으면(환불) 그만큼 줄어요 — 하루 쓴 양을 앞뒤 차이로 셀 땐 음수를 0 으로 보세요. 두 문의 wallet_id 는 이 키가 속한 지갑의 식별자라, 키 여러 개가 같은 지갑인지는 이 값이 같은지로 봐요. 칸 뜻은 「크레딧」 · 「남은 한도」 장에 있어요. 오류 몸통은 /v1/chat/completions 등 OpenAI 꼴이면 {"error": {"type": "authentication_error", "message": "…", "code": "authentication_error", "reason": "key_revoked"}}, /v1/messages 면 {"type": "error", "error": {"type": "authentication_error", "message": "…", "reason": "key_revoked"}} 예요 — 둘 다 jq -r '.error.type, .error.reason, .error.message' 로 읽혀요. 갈래는 reason 으로 가르고, message 는 사람에게 보여요 — missing_key · unset_key · malformed_key · foreign_key · management_key · key_not_found 는 키 파일 · 머리글을 고치고, key_revoked 는 지금 쓰는 키로 바꾸고, key_expired 는 지갑 주인이 기한을 늘리고, account_inactive 는 admin@schoolorder.kr 로 알려 주세요(뜻은 「인증」 장 「키가 안 열릴 때」 표). 1 크레딧 = 2원(부가세 포함)이라 1,000 크레딧은 2,000원이에요. 호출 응답에 usage.cost_credits 가 왔으면 정산이 끝난 것이라 /v1/credits 잔액에도 이미 반영돼 있어요. 그 칸이 없으면 정산이 2초 안에 안 끝난 거라 잔액이 조금 뒤에 바뀌어요 — 따로 기다리는 시간은 정해 두지 않아도 돼요.

키가 많으면 키마다 /v1/key 를 부르지 말고, 지갑 주인이 만든 관리 키(sk-som-)로 GET https://oneport.kr/v1/keys 를 한 번 불러요(요금 없음). 응답은 {"object": "list", "data": [{"id", "name", "key_prefix", "monthly_limit_credits", "month_used_credits", "daily_limit_credits", "day_used_credits", …}], "total", "has_more", "room", "cap", "wallet_id"} 이에요. 한 번에 100줄까지라 has_more 가 true 면 ?offset= 으로 이어 읽어요(?limit= 는 최대 500). 스페이스 강좌 키는 이 목록에 없어서 그 키는 /v1/key 로 봐요. 잔액은 관리 키로 못 봐요(GET /v1/credits 가 401 management_key) — 같은 지갑의 sk-so- 키로 불러요. 목록엔 이번 달 · 오늘 몫만 와요 — 지난 기간 키별 값은 대시보드 「정산 원장 받기 (CSV)」에 있어요(「크레딧」 장). 칸 · 오류(관리 키 401 의 갈래 포함) 전부는 「키 관리」 장이에요.

GET /v1/models 응답 (한 줄만)
{
  "object": "list",
  "credit_scope": { "state": "packs", "providers": ["anthropic", "openai"], "label": "제미나이를 뺀 모든 모델" },
  "data": [
    {
      "id": "gpt-5-pro",
      "object": "model",
      "owned_by": "openai",
      "display_name": "GPT-5 pro",
      "kind": "responses",
      "endpoint": "POST /v1/responses",
      "context_window": 400000,
      "supports_streaming": true,
      "supports_effort": true,
      "retirement": null,
      "pricing": {
        "input_credits_per_mtok": 13797.04,
        "output_credits_per_mtok": 110376.29,
        "rates": [
          { "dimension": "input_text", "unit": "mtok", "unit_label": "1M tokens", "credits": 13797.04 },
          { "dimension": "output", "unit": "mtok", "unit_label": "1M tokens", "credits": 110376.29 }
        ]
      }
    }
  ]
}

credit_scope 는 키를 실어 불렀고 그 키가 열릴 때만 와요 — 그때 data 는 이 키로 부를 수 있는 모델만이에요. 모델을 부를 땐 id 를, 부를 문은 endpoint 를 그대로 쓰세요.

owned_by 는 만든 회사예요. id 에 / 가 든 모델(openai/… · google/… 처럼)은 공개 모델이라, owned_by 가 openai · google 이어도 GPT · Gemini 공식 모델이 아니에요. retirement 는 null 이거나 {"date": "YYYY-MM-DD", "successors": […]} 예요 — 그 날짜에 내려가는 모델이고, successors 가 바꿔 넣을 id 예요. Claude 줄의 endpoint 도 POST /v1/chat/completions 로 와요 — Claude 는 /v1/messages 로도 불러요.

아래는 출력 단가(pricing.output_credits_per_mtok)가 가장 낮은 줄을 골라요. 모델을 부를 땐 그 id 를 그대로 쓰세요.

싼 공식 GPT 하나 고르기 (Claude 는 owned_by 를 anthropic 으로)
curl -s https://oneport.kr/v1/models -H "Authorization: Bearer $ONEPORT_API_KEY" | jq -r '
  [.data[] | select(.owned_by == "openai" and .endpoint == "POST /v1/chat/completions"
     and (.id | contains("/") | not) and .retirement == null)]
  | sort_by(.pricing.output_credits_per_mtok) | .[0].id'
같은 고르기 — Windows PowerShell
$m = curl.exe -s https://oneport.kr/v1/models -H "Authorization: Bearer $env:ONEPORT_API_KEY" | ConvertFrom-Json
($m.data | ? { $_.owned_by -eq "openai" -and $_.endpoint -eq "POST /v1/chat/completions" -and -not $_.id.Contains("/") -and $null -eq $_.retirement } |
  sort { $_.pricing.output_credits_per_mtok } | select -First 1).id

이 예처럼 curl.exe 출력을 | ConvertFrom-Json 으로 바로 넘기면 PowerShell 5.1 이 콘솔 코드 페이지(한국어 Windows 는 949)로 풀어서 한글 칸(credit_scope.label · error.message)이 깨져요 — id 처럼 영문만 읽는 이 예는 괜찮고, 한글을 읽을 땐 위처럼 -o 로 파일에 받아 Get-Content -Encoding UTF8 로 읽으세요(PowerShell 동작).

이렇게 고른 모델은 대개 생각하는 GPT 라(supports_effort 가 true) 짧게 받으려면 몸통에 "reasoning_effort": "low"(gpt-5-nano 면 "minimal" 도)를 같이 보내거나 max_tokens 를 2,000 넘게 두세요.