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

이 탭에는 Roboflow 및 Weights & Biases 가져오기에 사용할 키도 저장됩니다. 워크스페이스 소유자가 키를 사용해 가져오기를 연결하면 Platform은 해당 키를 여기에 저장하고 이전에 저장된 키가 있으면 이를 대체합니다. 이후 워크스페이스에서 이루어지는 가져오기는 해당 키로 자동 연결됩니다. 다른 팀원이 입력한 키는 해당 가져오기에만 사용됩니다. 저장된 키의 사용을 중단하려면 키 행을 삭제하세요.

키 형식#

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. 격리된 추론 용량이 필요한 경우 전용 엔드포인트를 사용하세요

자주 묻는 질문#