API 키#

Ultralytics Platform API 키를 사용하면 원격 학습, 추론 및 자동화를 위한 안전한 프로그래밍 방식 액세스가 가능합니다. 다양한 사용 사례에 맞춰 이름이 지정된 키를 만들고 AES-256-GCM 암호화를 적용하세요.

API 키 만들기#

새 API 키를 만들려면 다음을 수행하세요:

1. 설정 > API 키로 이동합니다
2. 키 추가를 클릭하고 제공업체로 Ultralytics를 선택합니다
3. 키 이름을 입력합니다(예: "Training Server")
4. 키 만들기를 클릭합니다

키 이름#

키의 용도를 알 수 있는 이름을 지정하세요:

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

키 표시#

키를 만든 후 확인 대화 상자에 키가 표시됩니다:

에이전트 및 어노테이션용 제공업체 키#

같은 설정 > API 키 탭에는 에이전트와 클래스 프롬프트 기반 어노테이션의 유료 모델에서 사용하는 외부 모델 제공업체 키도 저장됩니다. 어노테이션은 데이터셋의 워크스페이스에 저장된 키를 읽습니다. 워크스페이스 소유자만 이러한 키를 추가, 교체 또는 제거할 수 있으며, 팀 구성원은 연결된 제공업체를 확인할 수 있습니다. 연결되지 않은 제공업체가 필요하면 소유자에게 연결을 요청하세요. 소유자로서 제공업체를 연결하려면 다음을 수행하세요:

1. 키 추가를 클릭합니다.
2. 워크플로에서 사용할 언어 모델 또는 비전-언어 모델이나 실행하려는 어노테이션 모델에 해당하는 제공업체를 선택합니다.
3. 해당 제공업체의 API 키를 API 키에 붙여넣은 다음 키 저장을 클릭합니다. 대화 상자의 API 키 가져오기 링크를 클릭하면 제공업체의 키 페이지가 열립니다.

Ultralytics 키는 외부 모델 제공업체 인증에 사용할 수 없습니다. 제공업체 사용 요금은 저장된 키와 연결된 제공업체 계정으로 청구됩니다. 제공업체 키를 교체하려면 해당 키 행의 수정 컨트롤을 사용하세요.

키 형식#

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

ul_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4

• 접두사: ul_은 Ultralytics 키를 식별합니다
• 본문: 임의의 16진수 문자 40개
• 전체 길이: 43자

키 보안#

• 키는 AES-256-GCM 암호화를 적용해 저장되며, 일반 텍스트로 저장되지 않습니다
• 처음 11자(ul_과 16진수 문자 8개)는 표시용 접두사로 사용되므로 키를 노출하지 않고도 키를 식별할 수 있습니다

API 키 사용#

환경 변수#

키를 환경 변수로 설정합니다:

export ULTRALYTICS_API_KEY="YOUR_API_KEY"

YOLO CLI#

Python>=3.11에서 YOLO CLI를 사용해 키를 검증하고 저장합니다:

yolo login YOUR_API_KEY

yolo logout으로 저장된 키를 제거합니다.

HTTP 헤더#

API 요청에 키를 포함합니다:

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

또는 Python SDK(pip install "ultralytics-platform>=0.1.45")에 키를 전달할 수 있습니다. Python SDK는 api_key이 생략된 경우 ULTRALYTICS_API_KEY 또는 yolo login로 저장된 키를 읽습니다:

from ultralytics_platform import Platform

client = Platform(api_key="YOUR_API_KEY")

사용 가능한 모든 엔드포인트는 REST API 참조를 참조하세요.

원격 학습#

키를 사용하여 메트릭 스트리밍을 활성화합니다.

시작하기 전에 Python>=3.11에 Ultralytics 패키지를 설치하거나 업데이트합니다:

pip install -U ultralytics

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

전체 원격 학습 가이드는 클라우드 학습을 참조하세요.

키 관리#

키 보기#

모든 키는 Settings > API Keys 탭에 표시됩니다:

각 키 행에는 키 이름, 키 접두사, 생성 날짜, 전체 키를 복사하는 버튼, 제거(휴지통) 버튼이 표시됩니다.

키 취소#

키가 유출되었거나 더 이상 필요하지 않은 경우 키를 취소합니다:

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

키 재생성#

키가 유출된 경우:

1. 같은 이름으로 새 키를 만듭니다
2. 애플리케이션을 업데이트합니다
3. 이전 키를 취소합니다

워크스페이스 API 키#

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

• 개인 워크스페이스: 키는 개인 계정으로 인증됩니다
• 팀 워크스페이스: 키는 팀 워크스페이스 소유자 권한으로 인증되며 해당 워크스페이스에서 모든 소유자 권한을 가집니다

사이드바에서 워크스페이스를 전환하면 API 키 섹션에 해당 워크스페이스의 키가 표시됩니다. 워크스페이스 키에는 소유자 권한이 부여되므로 워크스페이스 소유자만 키를 만들거나 확인하거나 취소할 수 있습니다. 역할에 대한 자세한 내용은 팀을 참조하세요.

온프레미스 작업자 키#

온프레미스 호스트를 연결하면 별도의 작업자 키가 생성됩니다. 작업자 키는 이 탭이 아니라 온프레미스 통합에서 관리하며, API 키 목록에 함께 표시되지 않습니다. 호스트 연결을 해제하면 작업자 키가 취소되고 해당 호스트에서 대기 중이거나 실행 중인 작업도 취소됩니다.

보안 모범 사례#

권장 사항#

• 키를 환경 변수에 저장합니다
• 환경별로 별도의 키를 사용합니다
• 사용하지 않는 키는 신속하게 취소합니다
• 키를 주기적으로 교체합니다
• 키의 용도를 식별할 수 있도록 설명이 포함된 이름을 사용합니다

하지 마세요#

• 버전 관리 시스템에 키를 커밋하지 마세요
• 애플리케이션 간에 키를 공유하지 마세요
• 애플리케이션 출력에 키를 기록하지 마세요
• 클라이언트 측 코드에 키를 삽입하지 마세요

키 로테이션#

보안을 위해 주기적으로 키를 로테이션하세요:

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

문제 해결#

잘못된 키 오류#

Error: Invalid API key

해결 방법:

1. 키가 올바르게 복사되었는지 확인합니다(ul_ 접두사 포함).
2. 키가 폐기되지 않았는지 확인합니다
3. 환경 변수가 설정되었는지 확인합니다
4. Python>=3.11 및 ultralytics>=8.4.120을 사용하고 있는지 확인합니다

권한 거부됨#

Error: Permission denied for this operation

해결 방법:

1. 리소스 소유자인지 또는 적절한 워크스페이스 액세스 권한이 있는지 확인합니다
2. 키가 올바른 워크스페이스에 속하는지 확인합니다
3. 팀 워크스페이스에서 키를 관리하는 경우, 워크스페이스 소유자인지 확인합니다. 다른 역할에는 Workspace owner access required이 적용됩니다.
4. 필요한 경우 새 키를 생성합니다

요청 제한에 도달함#

Error: Rate limit exceeded

해결 방법:

1. 요청 빈도를 낮추세요. 카테고리별 제한은 요청 제한 표를 참조하세요.
2. Retry-After 헤더를 사용하여 지수형 백오프를 구현합니다
3. 격리된 추론 용량이 필요한 경우 전용 엔드포인트를 사용하세요

자주 묻는 질문#