API Keys

Ultralytics Platform API 키는 원격 학습, 추론 및 자동화를 위한 보안 프로그래밍 방식의 액세스를 활성화합니다. 다양한 사용 사례에 맞춰 AES-256-GCM 암호화가 적용된 이름 지정된 키를 생성하십시오.

API 키 생성

새 API 키 생성:

1. **설정 > API 키(Settings > API Keys)**로 이동합니다.
2. **키 생성(Create Key)**을 클릭합니다.
3. 키 이름 입력 (예: "Training Server")
4. **키 생성(Create Key)**을 클릭합니다.

키 이름

키에 설명적인 이름을 지정하십시오:

• training-server - 원격 학습 머신용
• ci-pipeline - CI/CD 통합용
• local-dev - 로컬 개발용

키 표시

생성 후 키가 한 번 표시됩니다:

키 형식

API 키는 다음 형식을 따릅니다:

• 접두사(Prefix): ul_은 Ultralytics 키임을 식별합니다.
• 본문(Body): 40개의 임의 16진수 문자
• 총 길이: 43자

키 보안

• 키는 AES-256-GCM 암호화로 저장됩니다.
• 인증은 빠른 접두사 조회 및 해시 비교를 위해 SHA-256 해시를 사용합니다.
• 전체 키 값은 일반 텍스트로 절대 저장되지 않습니다.

API 키 사용

환경 변수

키를 환경 변수로 설정하십시오:

export ULTRALYTICS_API_KEY="YOUR_API_KEY"

YOLO CLI

YOLO CLI를 사용하여 키를 설정하십시오:

yolo settings api_key="YOUR_API_KEY"

코드 내에서

Python 스크립트에서 키를 사용하십시오:

import os

# From environment (recommended)
api_key = os.environ.get("ULTRALYTICS_API_KEY")

# Or directly (not recommended for production)
api_key = "YOUR_API_KEY"

HTTP 헤더

API 요청에 키를 포함하십시오:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://platform.ultralytics.com/api/...

사용 가능한 모든 엔드포인트는 REST API 참조를 확인하십시오.

원격 학습

키를 사용하여 메트릭 스트리밍을 활성화하십시오.

pip install "ultralytics>=8.4.35"

export ULTRALYTICS_API_KEY="YOUR_API_KEY"
yolo train model=yolo26n.pt data=coco.yaml project=username/project name=exp1

전체 원격 학습 가이드는 클라우드 학습(Cloud Training)을 확인하십시오.

키 관리

키 보기

All keys are listed on the Settings > API Keys tab:

각 키 카드에는 키 이름, 전체 복호화된 키 값(복사 가능), 상대적 생성 시간 및 취소 버튼이 표시됩니다.

키 취소

손상되었거나 더 이상 필요하지 않은 키를 취소하십시오:

1. API 키 섹션에서 해당 키를 찾습니다.
2. 취소(Revoke) (휴지통) 버튼을 클릭합니다.
3. 취소 확인

키 재생성

키가 손상된 경우:

1. 같은 이름으로 새 키를 생성하십시오.
2. 애플리케이션을 업데이트하십시오.
3. 이전 키를 취소하십시오.

워크스페이스 API 키

API 키는 현재 활성화된 워크스페이스에 범위가 지정됩니다:

• 개인 워크스페이스(Personal workspace): 키는 귀하의 개인 계정으로 인증됩니다.
• 팀 워크스페이스(Team workspace): 키는 팀 컨텍스트 내에서 인증됩니다.

사이드바에서 워크스페이스를 전환하면 API 키 섹션에 해당 워크스페이스의 키가 표시됩니다. 워크스페이스 API 키를 관리하려면 편집자(Editor) 이상의 역할이 필요합니다. 역할에 대한 자세한 내용은 팀(Teams)을 참조하십시오.

보안 모범 사례

권장 사항(Do)

• 키를 환경 변수에 저장하십시오.
• 서로 다른 환경에 대해 별도의 키를 사용하십시오.
• 사용하지 않는 키는 즉시 취소하십시오.
• 주기적으로 키를 교체하십시오.
• 설명적인 이름을 사용하여 키의 목적을 식별하십시오.

주의 사항(Don't)

• 버전 관리 시스템에 키를 커밋하지 마십시오.
• 애플리케이션 간에 키를 공유하지 마십시오.
• 애플리케이션 로그에 키를 기록하지 마십시오.
• 클라이언트 측 코드에 키를 포함하지 마십시오.

키 교체(Key Rotation)

보안을 위해 주기적으로 키를 교체하십시오:

1. 같은 이름으로 새 키 생성
2. 새 키를 사용하도록 애플리케이션 업데이트
3. 애플리케이션이 올바르게 작동하는지 확인
4. 이전 키 취소

문제 해결

키 무효 오류

해결 방법:

1. 키가 올바르게 복사되었는지 확인하십시오 (ul_ 접두사 포함)
2. 키가 취소되지 않았는지 확인하십시오.
3. 환경 변수가 설정되었는지 확인하십시오.
4. ultralytics>=8.4.35를 사용 중인지 확인하십시오.

권한 거부(Permission Denied)

해결 방법:

1. 리소스 소유자인지 또는 적절한 워크스페이스 액세스 권한이 있는지 확인하십시오.
2. 키가 올바른 워크스페이스에 속해 있는지 확인하십시오.
3. 필요한 경우 새 키를 생성하십시오.

속도 제한(Rate Limited)

해결 방법:

1. 요청 빈도를 줄이십시오 — 엔드포인트별 제한은 속도 제한 표를 참조하십시오.
2. Retry-After 헤더를 사용하여 지수 백오프(exponential backoff)를 구현하십시오.
3. 무제한 추론 처리량을 위해 전용 엔드포인트를 사용하십시오.

FAQ

키를 몇 개까지 생성할 수 있습니까?

API 키 생성에는 엄격한 제한이 없습니다. 다양한 애플리케이션과 환경에 필요한 만큼 생성하십시오.

키가 만료됩니까?

키는 자동으로 만료되지 않습니다. 취소되기 전까지 유효합니다. 보안을 위해 주기적인 키 교체를 고려하십시오.

생성 후 내 키를 확인할 수 있습니까?

네, 전체 키 값은 Settings > API Keys의 키 목록에서 볼 수 있습니다. 플랫폼이 키를 복호화하여 표시하므로 언제든지 복사할 수 있습니다.

키가 리전별로 지정되어 있습니까?

키는 모든 리전에서 작동하지만, 계정이 속한 리전의 데이터에만 액세스합니다.

팀원들과 키를 공유할 수 있습니까?

권장 사항: 각 팀원이 직접 키를 생성하도록 하십시오. 팀 워크스페이스의 경우, Editor 역할 이상의 각 구성원이 해당 워크스페이스에 한정된 키를 생성할 수 있습니다.