API 문서
SW_DEV의 서비스를 외부 프로그램에서 API로 호출하는 방법을 안내합니다. Planet에서 발급한 API 키 하나로, 키의 범위에 넣은 서비스를 호출합니다.
사용할 수 있는 서비스
GatewayAI 모델 호출. OpenAI API와 같은 형식이라 OpenAI SDK의 주소만 바꿔 씁니다.
https://swdev.co.kr/api/llm/v1AgentGenAI에 배포한 에이전트를 실행하고 답을 받습니다.https://swdev.co.kr/api/agent/v1Access · Secret · Report 등 다른 서비스는 아직 API 키로 호출할 수 없습니다.
API 키 발급
- Planet의 Access > API 키에서 키 발급을 누릅니다. API 키 화면은 기본적으로 Planet의 Owner · Admin이 쓸 수 있습니다.
- 이름과 범위를 고릅니다. 범위는 이 키로 호출할 수 있는 서비스입니다(Gateway · Agent). 조회 권한이 없는 서비스는 범위로 고를 수 없습니다.
- 필요하면 만료일을 정합니다. 비워 두면 만료되지 않습니다.
- 발급된 키 원문(
swd_…)은 이때 한 번만 표시됩니다. 안전한 곳에 보관하고, 코드나 저장소에 그대로 넣지 마십시오.
키는 발급한 Planet에 속합니다. 키로 부르는 모델 · 에이전트와 사용량은 모두 그 Planet의 것입니다.
인증
요청마다 Authorization: Bearer 헤더나 x-api-key 헤더에 키를 넣습니다. 둘 중 하나만 있으면 됩니다.
curl
curl https://swdev.co.kr/api/llm/v1/models \
-H "Authorization: Bearer $SWDEV_API_KEY"키를 환경 변수로 두면 코드에 원문이 남지 않습니다.
셸
export SWDEV_API_KEY="swd_…"키 관리
- 수정: 이름 · 범위 · 만료일을 바꿉니다. 키 원문은 그대로입니다.
- 재발급: 새 원문을 발급하고, 이전 원문은 바로 쓸 수 없게 됩니다.
- 폐기: 키를 더 이상 쓸 수 없게 하고 목록에서 뺍니다. 되돌릴 수 없습니다.
- 확인 결과를 최대 60초 동안 저장해 두므로, 수정 · 재발급 · 폐기는 최대 60초 뒤에 반영됩니다. 만료는 만료 시각에 바로 반영됩니다.
공통 오류
오류 본문의 형식은 서비스마다 다릅니다. Gateway는 OpenAI SDK가 그대로 읽을 수 있는 OpenAI 형식, Agent는 SW_DEV 공통 형식입니다.
| HTTP | 언제 | 설명 |
|---|---|---|
401 | 키 없음 · 틀림 · 만료 · 폐기 | 키를 확인하십시오. 폐기 · 재발급한 키는 다시 쓸 수 없습니다. |
403 | 범위 없음 | 키의 범위에 그 서비스가 없습니다. Access > API 키에서 범위를 고치십시오. |
429 | 한도 초과 | 요청 한도나 사용 한도를 넘었습니다. retry-after 헤더가 있으면 그만큼 기다린 뒤 다시 보내십시오. |
503 | 키 확인 불가 | 잠시 키를 확인할 수 없습니다. 잠시 후 다시 보내십시오. |
Gateway 오류 (OpenAI 형식)
{
"error": {
"message": "이 API 키의 범위에 Gateway 가 없습니다 (Access > API 키)",
"type": "permission_error",
"param": null,
"code": "scope_not_allowed"
}
}Agent 오류 (SW_DEV 공통 형식)
{
"type": "about:blank",
"title": "Forbidden",
"status": 403,
"detail": "이 API 키의 범위에 Agent 가 없습니다. (Access > API 키)",
"code": "SCOPE_NOT_ALLOWED",
"instance": "/api/agent/v1/agents"
}