Vision Event 생성

배포된 모델에서 관찰 결과를 기록하기 위해 HTTP API를 통해 단일 Vision Event를 기록합니다.

소개

하나의 비전 이벤트 는 배포된 컴퓨터 비전 모델이 관찰한 어떤 것에 대한 타임스탬프가 찍힌 기록입니다. 예를 들어 감지된 결함이나 재고 수량과 같으며, 선택적 이미지, 예측, 사용자 정의 메타데이터가 함께 포함됩니다. 이 페이지에서는 검색 및 필터링 가능한 운영 기록의 일부가 되도록 단일 이벤트를 기록하는 방법을 보여줍니다. 여러 이벤트를 한 번에 수집하려면 다음을 사용하세요 비전 이벤트 일괄 생성.

HTTP API

컴퓨터 비전 배포에서 관찰한 내용을 기록하기 위해 단일 비전 이벤트를 생성합니다.

필수 범위: vision-events:write 또는 device:update

Create a Vision Event

post

Create a single vision event.

Authorizations

AuthorizationstringRequired

Roboflow API key passed as a Bearer token.

Body

eventIdstring · max: 256Required

Globally unique identifier. Use a UUID (v4).

eventTypestring · enumRequiredPossible values:

useCaseIdstring · max: 256Required

The use case this event belongs to.

timestampstring · date-timeRequired

ISO 8601 timestamp. Must be between one year ago and tomorrow.

deviceIdstring · max: 256Optional

streamIdstring · max: 256Optional

workflowIdstring · max: 256Optional

workflowVersionstring · max: 64Optional

displayImagePositioninteger · max: 999Optional

eventDataobjectRequired

Type-specific event data. Structure depends on eventType.

Responses

201

Event created successfully.

application/json

eventIdstringOptional

createdbooleanOptional

deprecationsstring[]Optional

400

Validation error.

application/json

403

Insufficient permissions for this resource.

application/json

post/vision-events

POST /vision-events HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 720

{
  "eventId": "text",
  "eventType": "quality_check",
  "useCaseId": "text",
  "timestamp": "2026-08-10T01:46:00.188Z",
  "deviceId": "text",
  "streamId": "text",
  "workflowId": "text",
  "workflowVersion": "text",
  "images": [
    {
      "label": "text",
      "sourceId": "text",
      "inputSourceId": "text",
      "objectDetections": [
        {
          "class": "text",
          "x": 1,
          "y": 1,
          "width": 1,
          "height": 1,
          "confidence": 1
        }
      ],
      "classifications": [
        {
          "class": "text",
          "confidence": 1
        }
      ],
      "instanceSegmentations": [
        {
          "class": "text",
          "x": 1,
          "y": 1,
          "width": 1,
          "height": 1,
          "confidence": 1,
          "points": [
            [
              1
            ]
          ]
        }
      ],
      "keypoints": [
        {
          "class": "text",
          "x": 1,
          "y": 1,
          "width": 1,
          "height": 1,
          "confidence": 1,
          "keypoints": [
            {
              "id": 1,
              "x": 1,
              "y": 1,
              "occluded": true
            }
          ]
        }
      ]
    }
  ],
  "displayImagePosition": 1,
  "eventData": {},
  "customMetadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

{
  "eventId": "text",
  "created": true,
  "warnings": [
    {
      "type": "text",
      "path": "text",
      "value": "text",
      "valueType": "text"
    }
  ],
  "deprecations": [
    "text"
  ]
}

예시 요청

curl -X POST "https://api.roboflow.com/vision-events" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "eventType": "quality_check",
    "useCaseId": "a1b3c8e1",
    "timestamp": "2024-01-15T10:30:00Z",
    "eventData": {
      "result": "fail",
      "externalId": "batch-001"
    },
    "customMetadata": {
      "line": "A1",
      "operator": "John Doe",
      "temperature": 72.5
    }
  }'

요청 본문 매개변수

각 이벤트에는 전역적으로 고유한 eventId가 있어야 합니다. 충돌을 방지하려면 UUID(v4)를 사용하는 것이 좋습니다. 중복된 이벤트 ID는 이전에 수집된 이벤트를 덮어씁니다.

필수 필드:

eventId (문자열, 최대 256자): 이벤트의 전역 고유 식별자입니다. UUID(v4)를 사용하세요.
eventType (문자열): 다음 중 하나: quality_check, inventory_count, safety_alert, custom또는 operator_feedback.
useCaseId (문자열, 최대 256자): 이 이벤트가 속한 사용 사례입니다. 다음을 참조하세요: 사용 사례 사용 사례를 생성하고 관리하는 방법은.
timestamp (문자열, ISO 8601): 이벤트가 발생한 시점입니다. 1년 전부터 내일까지여야 합니다.
eventData (객체): 유형별 이벤트 데이터입니다. 필요한 구조는 아래의 이벤트 데이터 스키마 를 참조하세요.

선택적 필드:

deviceId (문자열, 최대 256자): 이벤트를 생성한 기기의 식별자입니다.
streamId (문자열, 최대 256자): 비디오 스트림의 식별자입니다.
workflowId (문자열, 최대 256자): 이벤트를 생성한 워크플로의 식별자입니다.
workflowVersion (문자열, 최대 64자): 워크플로 버전입니다.
images (배열, 최대 1000개): 주석이 포함된 이미지 객체 배열입니다. 아래의 이미지 객체 를 참조하세요.
displayImagePosition (숫자, 0-999): 주요 표시 이미지로 사용할 images 배열에서의 이미지 인덱스 위치입니다. 예를 들어 0 첫 번째 이미지에는 1 두 번째 이미지에는
customMetadata (객체, 최대 100개 키): 사용자 정의 메타데이터의 키-값 쌍입니다. 다음을 참조하세요: 사용자 정의 메타데이터 를 참조하세요.
comment (문자열, 최대 1000자): 이벤트에 대한 메모입니다. 다음과 함께 사용될 때 operator_feedback검토자의 메모를 담습니다.

이벤트 데이터 스키마

의 구조는 eventData 다음에 따라 달라집니다 eventType:

{
  "result": "pass",
  "externalId": "batch-001"
}

result (문자열, 선택 사항): "pass" 또는 "fail".
externalId (문자열, 최대 1000자, 선택 사항): 외부 참조 ID입니다.

{
  "location": "warehouse-a",
  "itemCount": 42,
  "itemType": "pallets",
  "externalId": "inv-2024-001"
}

location (문자열, 최대 1000자, 선택 사항): 개수를 측정한 위치입니다.
itemCount (정수, >= 0, 선택 사항): 집계된 항목 수입니다.
itemType (문자열, 최대 1000자, 선택 사항): 집계된 항목의 유형입니다.
externalId (문자열, 최대 1000자, 선택 사항): 외부 참조 ID입니다.

{
  "alertType": "no_hardhat",
  "severity": "high",
  "description": "Worker detected without required PPE in zone B3.",
  "externalId": "alert-2024-001"
}

alertType (문자열, 최대 256자, 선택 사항): 경보 유형(영숫자, 밑줄, 하이픈)입니다.
severity (문자열, 선택 사항): "low", "medium"또는 "high".
description (문자열, 최대 10000자, 선택 사항): 경보에 대한 설명입니다.
externalId (문자열, 최대 1000자, 선택 사항): 외부 참조 ID입니다.

{
  "value": "Custom event data as a string",
  "externalId": "custom-2024-001"
}

value (문자열, 최대 10000자, 선택 사항): 자유 형식 이벤트 데이터입니다.
externalId (문자열, 최대 1000자, 선택 사항): 외부 참조 ID입니다.

{
  "relatedEventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "feedback": "incorrect"
}

relatedEventId (문자열, 필수): 이 피드백이 설명하는 이벤트의 이벤트 ID(UUID)입니다.
feedback (문자열, 필수): "correct", "incorrect"또는 "inconclusive".

검토자의 메모는 최상위 comment 필드에 들어가며, 다음 안에 넣지 않습니다 eventData.

이미지 객체

이벤트에 이미지를 첨부하려면 먼저 다음을 사용하여 각 이미지를 업로드해야 합니다: 비전 이벤트 이미지 업로드 엔드포인트를 사용해 sourceId. 다음의 각 이미지 객체는 images 배열에서 주석이 달린(출력) 이미지를 나타냅니다. 원본 주석 없는(입력) 이미지도 연결하려면 별도로 업로드한 뒤 그 sourceId 을 다음으로 inputSourceId.

{
  "label": "inspection-photo",
  "sourceId": "img-source-123",
  "inputSourceId": "camera-1",
  "objectDetections": [
    {
      "class": "defect",
      "x": 100,
      "y": 200,
      "width": 50,
      "height": 30,
      "confidence": 0.95
    }
  ],
  "classifications": [
    {
      "class": "damaged",
      "confidence": 0.87
    }
  ],
  "instanceSegmentations": [
    {
      "class": "crack",
      "x": 100,
      "y": 200,
      "width": 50,
      "height": 30,
      "confidence": 0.92,
      "points": [[100, 200], [120, 210], [110, 230]]
    }
  ],
  "keypoints": [
    {
      "class": "joint",
      "x": 100,
      "y": 200,
      "width": 50,
      "height": 30,
      "confidence": 0.88,
      "keypoints": [
        { "id": 0, "x": 105, "y": 205, "occluded": false },
        { "id": 1, "x": 115, "y": 215 }
      ]
    }
  ]
}

이미지 필드:

label (문자열, 선택 사항): 이미지의 레이블입니다.
sourceId (문자열, 선택 사항): sourceId 에서 반환된 주석이 달린 이미지를 업로드했을 때.
inputSourceId (문자열, 선택 사항): sourceId 원본 주석 없는(입력) 이미지를 업로드했을 때 반환됩니다.
objectDetections (배열, 최대 1000개, 선택 사항): 다음이 포함된 바운딩 박스 검출 class, x, y, width, height와 confidence (0-1).
classifications (배열, 최대 1000개, 선택 사항): 다음이 포함된 분류 결과 class 와 confidence (0-1).
instanceSegmentations (배열, 최대 1000개, 선택 사항): 바운딩 박스 필드와 다음이 포함된 세분화 결과 points (다음으로 구성된 배열 [x, y] 쌍, 최소 3개).
keypoints (배열, 최대 1000개, 선택 사항): 바운딩 박스 필드와 다음이 포함된 키포인트 검출 keypoints (다음이 포함된 객체 배열 id, x, y와 선택적 occluded, 검출당 최소 1개의 키포인트).

사용자 정의 메타데이터

각 이벤트에 최대 100개의 사용자 정의 메타데이터 키-값 쌍을 첨부할 수 있습니다. 사용자 정의 메타데이터는 다음을 통해 조회할 수 있습니다: 비전 이벤트 조회 엔드포인트에서.

제약 사항:

키는 다음 패턴과 일치해야 합니다 [a-zA-Z0-9_ -]+ (문자, 숫자, 밑줄, 하이픈, 공백), 최대 100자.
문자열 값은 1000자로 제한됩니다.
숫자 값은 소수점 이하 최대 6자리까지 지원됩니다.
불리언 값이 지원됩니다.

{
  "customMetadata": {
    "production_line": "A1",
    "shift": "morning",
    "temperature": 72.5,
    "is_overtime": false
  }
}

예시 응답

{
  "eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created": true
}

{
  "error": "eventType is required"
}

{
  "error": "Insufficient permissions for this resource."
}

검증 및 경고

Vision Events API는 선제적 수집(eager ingestion)을 사용합니다. 네 가지 필수 필드(eventId, eventType, useCaseId, timestamp)만 엄격하게 검증됩니다. 이 항목들이 통과하면 다른 필드에 오류가 있어도 이벤트는 항상 수락되어 저장됩니다.

필수 항목이 아닌 필드의 문제는 다음으로 반환됩니다 경고 배열로 반환되며 거부를 초래하지 않습니다. 여기에는 다음이 포함됩니다:

다음 내부의 필수 필드 누락 eventData (예: relatedEventId 대상: operator_feedback)
다음에 대한 잘못된 값 eventData 필드(예: 다음에 대한 잘못된 열거형 값 severity)
스키마에 포함되지 않은 인식되지 않는 필드

경고가 있으면 잘못된 eventData 는 빈 객체로 저장됩니다 {}, 하지만 이벤트 자체는 여전히 생성됩니다.

{
  "eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created": true,
  "warnings": [
    {
      "type": "any.required",
      "path": "eventData.relatedEventId",
      "value": null,
      "valueType": "object"
    }
  ]
}

응답에는 다음도 포함될 수 있습니다: 사용 중단 항목 사용 중단된 필드 이름이 사용된 경우 배열이 포함됩니다.

Python SDK

컴퓨터 비전 배포에서 관찰한 내용을 기록하기 위해 단일 비전 이벤트를 생성합니다.

import roboflow

roboflow.login()

rf = roboflow.Roboflow()
ws = rf.workspace()

ws.write_vision_event({
    "eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "eventType": "quality_check",
    "useCaseId": "a1b3c8e1",
    "timestamp": "2024-01-15T10:30:00Z",
    "eventData": {
        "result": "fail",
        "externalId": "batch-001",
    },
    "customMetadata": {
        "line": "A1",
        "operator": "John Doe",
        "temperature": 72.5,
    },
})

이벤트 페이로드는 클라이언트 측 검증 없이 서버로 직접 전달되므로, 새로운 이벤트 유형과 필드는 SDK를 업데이트하지 않아도 작동합니다.

필수 필드:

eventId (문자열, 최대 256자): 전역적으로 고유한 식별자입니다. UUID(v4)를 사용하세요.
eventType (문자열): 다음 중 하나: quality_check, inventory_count, safety_alert, custom또는 operator_feedback.
useCaseId (문자열): 이 이벤트가 속한 사용 사례입니다.
timestamp (문자열, ISO 8601): 이벤트가 발생한 시점입니다.

선택적 필드:

eventData (딕셔너리): 유형별 이벤트 데이터입니다.
deviceId, streamId, workflowId (문자열): 컨텍스트 식별자입니다.
images (리스트): 주석이 포함된 이미지 객체입니다. 다음을 참조하세요: 비전 이벤트 이미지 업로드.
customMetadata (딕셔너리): 최대 100개의 사용자 정의 메타데이터 키-값 쌍입니다.
comment (문자열): 이벤트에 대한 메모로, 주로 다음과 함께 사용됩니다: operator_feedback.

전체 이벤트 스키마, 유형별 이벤트 데이터 구조, 이미지 주석 형식은 다음을 참조하세요: REST API 참고 문서.

이전Vision Event 일괄 생성 다음이벤트 삭제

마지막 업데이트 2일 전

도움이 되었나요?