워크플로우 관리

REST API와 Python SDK를 통해 워크스페이스의 워크플로우를 조회, 가져오기, 생성, 업데이트합니다.

소개

Roboflow 워크플로 는 웹 앱에서 만들고 호스팅 엔드포인트로 배포하는 시각적 컴퓨터 비전 파이프라인입니다. 이 페이지는 작업공간의 워크플로를 나열, 조회, 생성, 업데이트하는 관리 영역을 REST API와 Python SDK를 통해 다룹니다. 이미지나 비디오 스트림에 대해 워크플로를 실행하려면 다음을 참조하세요 Workflows 런타임 문서.

HTTP API

Roboflow 워크플로 는 웹 앱에서 만들고 호스팅 엔드포인트로 배포할 수 있는 시각적 컴퓨터 비전 파이프라인입니다. REST API는 관리 영역을 노출합니다. 이미지나 비디오 스트림에 대해 워크플로를 실행하려면 다음을 참조하세요 이미지에서 모델 실행 그리고 Workflows 런타임 문서.

API 키 는 쿼리 매개변수로 또는 요청 본문에 전달할 수 있습니다. 필요한 scope는 각 엔드포인트에 표시됩니다.

프로젝트 기본 워크플로

각 프로젝트에는 호스팅된 모델 엔드포인트를 뒷받침하는 기본 워크플로가 있습니다. 이 프로젝트 범위 작업을 사용해 해당 워크플로를 읽거나 모델 단계에서 사용할 모델을 선택하세요.

프로젝트 기본 워크플로 가져오기

GET /:workspace/:project/deploy

필수 scope: project:read

curl "https://api.roboflow.com/my-workspace/my-project/deploy?api_key=$ROBOFLOW_API_KEY"

프로젝트에 기본 워크플로가 없으면 이 요청이 하나를 생성합니다. 응답에는 프로젝트, 기본 워크플로, 선택된 모델, 배포 가능 여부, 활성 학습 상태가 표시됩니다:

{
  "project": {
    "id": "abc123",
    "url": "my-project",
    "name": "내 프로젝트",
    "owner": "my-workspace-id",
    "type": "object-detection",
    "classes": ["고양이", "개"],
    "multilabel": false
  },
  "workflow": {
    "id": "wf_xyz",
    "name": "내 프로젝트 기본 워크플로",
    "url": "my-project-base-workflow",
    "workspaceUrl": "my-workspace",
    "inferencePath": "/infer/workflows/my-workspace/my-project-base-workflow"
  },
  "model": {
    "id": "rfdetr-medium",
    "kind": "pretrained",
    "displayName": "RF-DETR Medium",
    "modelId": "rfdetr-medium"
  },
  "deployability": {
    "status": "배포 가능",
    "modelWasConfigured": false,
    "selectedModelId": null,
    "selectionReason": null
  },
  "activeLearning": {
    "enabled": false,
    "collectionLimits": {
      "dataPercentage": 100,
      "minutelyUsageLimit": 10,
      "hourlyUsageLimit": 100,
      "dailyUsageLimit": 1000,
      "labelingBatchesRecreationFrequency": "daily",
      "usageQuotaName": "upload_quota_active_learning",
      "imageCompressionLevel": 95,
      "maxImageHeight": 1080,
      "maxImageWidth": 1920,
      "persistPredictions": true
    },
    "filters": []
  },
  "baseWorkflowWasCreated": false
}

model 는 null 모델이 구성되지 않았을 때. deployability.status 는 "배포 불가" 워크플로가 추론을 제공할 수 없을 때. baseWorkflowWasCreated 이 요청이 기본 워크플로를 생성했는지 여부를 알려줍니다.

프로젝트 기본 워크플로 모델 선택

POST /:workspace/:project/deploy/model

필수 scope: project:update

설정 model.type 을 "model_id", "sam3", 또는 "clip":

curl -X POST "https://api.roboflow.com/my-workspace/my-project/deploy/model" \\
  -H "Content-Type: application/json" \\
  -d '{
    "api_key": "'$ROBOFLOW_API_KEY'",
    "model": {
      "type": "model_id",
      "modelId": "rfdetr-medium"
    }
  }'

다음의 경우 "model_id", modelId 필수입니다. displayName 및 taskType 는 선택 사항입니다. 다음의 경우 "sam3" 및 "clip", 비어 있지 않은 클래스 배열을 modelId:

{
  "api_key": "YOUR_API_KEY",
  "model": {
    "type": "sam3",
    "classes": ["고양이", "개"]
  }
}

응답의 형태는 프로젝트 기본 워크플로 가져오기다음과 같습니다. 400 응답은 model 값이 없거나 유효하지 않음을 의미합니다.

데이터 수집을 활성화하거나, 수집 한도를 설정하거나, 검토 대기열의 이미지를 나열하려면 활성 학습 HTTP API.

워크플로 나열

GET /:workspace/workflows

워크스페이스의 모든 워크플로를 나열합니다.

쿼리

이름	유형	설명	필수
API 키	string	워크스페이스의 API 키.

예제 요청

curl "https://api.roboflow.com/my-workspace/workflows?api_key=$ROBOFLOW_API_KEY"

응답

{
  "workflows": [
    {
      "id": "wf_abc123",
      "name": "느린 웹훅",
      "url": "slow-webhooks",
      "createdAt": "2026-04-12T17:05:33.000Z"
    }
  ],
  "status": "ok"
}

필수 scope: workflow:read.

워크플로 가져오기

GET /:workspace/workflows/:workflowUrl

워크플로의 사양, 메타데이터, 그리고(공개되지 않은 워크플로의 경우) 권한 상태를 반환합니다.

curl "https://api.roboflow.com/my-workspace/workflows/slow-webhooks?api_key=$ROBOFLOW_API_KEY"

공개 워크플로는 API 키없이 접근할 수 있습니다. 비공개 워크플로는 workflow:read scope가 필요합니다.

워크플로 버전 나열

GET /:workspace/workflows/:workflowUrl/versions

curl "https://api.roboflow.com/my-workspace/workflows/slow-webhooks/versions?api_key=$ROBOFLOW_API_KEY"

워크플로 사양의 버전별 스냅샷을 반환합니다.

워크플로 생성

POST /:workspace/createWorkflow

헤더

이름	값
Content-Type	application/json

본문

이름	유형	설명	필수
API 키	string	워크스페이스 API 키.
name	string	표시 이름.
url	string	워크플로의 URL 슬러그.
config	string	JSON으로 인코딩된 워크플로 사양(아래 참고).
template	string	JSON으로 인코딩된 템플릿 메타데이터. 없다면 "{}" 를 전달하세요.

다음에 대한 참고 사항 config: API는 저장된 형태 {"specification": {...}}를 기대합니다. bare specification을 전달하면 SDK 어댑터가 자동으로 감싸주지만, 직접 REST 호출을 할 경우 직접 감싸야 합니다.

예제 요청

curl -X POST "https://api.roboflow.com/my-workspace/createWorkflow" \\
  -H 'Content-Type: application/json' \\
  -d '{"api_key":"'$ROBOFLOW_API_KEY'","name":"내 워크플로","url":"my-workflow","config":"{\"specification\":{\"version\":\"1.0\",\"inputs\":[],\"steps\":[],\"outputs\":[]}}"}'

쿼리 매개변수로도 동일한 필드를 보낼 수 있지만, 그 경우 template 가 필요합니다. 긴 URL은 잘리므로 큰 사양은 본문을 사용하세요.

curl -X POST "https://api.roboflow.com/my-workspace/createWorkflow" \\
  --get \\
  --data-urlencode "api_key=$ROBOFLOW_API_KEY" \\
  --data-urlencode "name=내 워크플로" \\
  --data-urlencode "url=my-workflow" \\
  --data-urlencode 'config={"specification":{"version":"1.0","inputs":[],"steps":[],"outputs":[]}}' \\
  --data-urlencode 'template={}'

응답

{
  "workflows": { "id": "wf_xyz789", "url": "my-workflow" },
  "status": "ok"
}

필수 scope: workflow:create.

워크플로 업데이트

POST /:workspace/updateWorkflow

헤더

이름	값
Content-Type	application/json

본문

이름	유형	설명	필수
id	string	워크플로의 내부 ID.
name	string	표시 이름.
url	string	URL 슬러그.
config	string	JSON으로 인코딩된 워크플로 사양(Create의 참고 사항 참조).

curl -X POST "https://api.roboflow.com/my-workspace/updateWorkflow?api_key=$ROBOFLOW_API_KEY" \\
  -H 'Content-Type: application/json' \\
  -d '{"id":"wf_xyz789","name":"내 워크플로","url":"my-workflow","config":"{\"specification\":{\"version\":\"1.0\",\"steps\":[]}}"}'

필수 scope: workflow:update.

워크플로 포크

POST /:workspace/forkWorkflow

다른 워크스페이스의 워크플로를 이 워크스페이스로 복사합니다.

본문

이름	유형	설명	필수
source_workspace	string	원본 워크플로를 소유한 워크스페이스의 슬러그.
source_workflow	string	원본 워크플로의 URL 슬러그.
name	string	포크의 표시 이름. 기본값은 원본 이름입니다.
url	string	포크의 URL 슬러그. 생략하면 자동 생성됩니다.

curl -X POST "https://api.roboflow.com/my-workspace/forkWorkflow?api_key=$ROBOFLOW_API_KEY" \\
  -H 'Content-Type: application/json' \\
  -d '{"source_workspace":"other-workspace","source_workflow":"their-workflow","name":"내 포크","url":"my-fork"}'

필수 scope: workflow:create.

워크플로 토큰 생성

POST /:workspace/workflowToken

공개 클라이언트(예: 브라우저)에서 워크플로를 실행하는 데 적합한 단기 토큰을 생성합니다.

curl -X POST "https://api.roboflow.com/my-workspace/workflowToken?api_key=$ROBOFLOW_API_KEY"

워크플로 삭제(소프트 삭제)

DELETE /:workspace/workflows/:workflowUrl

워크플로를 휴지통으로 이동합니다. 다음을 참조하세요 휴지통 관리 응답 형태와 복원 흐름을 확인하세요.

워크플로 실행

워크플로 실행은 관리 API가 아니라 https://serverless.roboflow.com에 있습니다. 다음을 참조하세요 이미지에서 모델 실행 및 제품 문서의 워크플로 배포.

Python SDK

Roboflow 워크플로 는 시각적 컴퓨터 비전 파이프라인입니다. SDK는 list/get/create를 Workspace에서 직접 노출합니다. update, fork, delete는 저수준 rfapi 어댑터에 있습니다.

워크플로 나열

import roboflow

rf = roboflow.Roboflow(api_key="YOUR_API_KEY")
workspace = rf.workspace()

workflows = workspace.list_workflows()
for w in workflows:
    print(w["id"], w["name"], w["url"] )

워크플로 가져오기

workflow = workspace.get_workflow("slow-webhooks")
print(workflow["specification"] )

이 url 인수는 워크플로의 슬러그(웹 앱 URL 표시줄에 보이는 값)이며 Firestore id가 아닙니다.

워크플로 생성

workflow = workspace.create_workflow(
    name="내 워크플로",
    definition={
        "version": "1.0",
        "inputs": [...],
        "steps": [...],
        "outputs": [...],
    },
)
print(workflow["id"], workflow["url"] )

다음을 전달하세요 definition=None 나중에 웹 앱에서 편집할 빈 워크플로 껍데기를 생성하려면.

SDK는 bare specification dict({"version": ..., "steps": ...}) 또는 감싼 형태({"specification": {...}}); 둘 다 받아들이며, 필요하면 래핑을 정규화하고 UTF-8 BOM이 있으면 제거합니다.

워크플로 업데이트

Workspace 는 업데이트를 직접 노출하지 않습니다. 저수준 어댑터를 사용하세요:

from roboflow.adapters import rfapi

rfapi.update_workflow(
    api_key="YOUR_API_KEY",
    workspace_url=workspace.url,
    workflow_id=workflow["id"],
    workflow_name="내 워크플로",
    workflow_url="my-workflow",
    config={"version": "1.0", "steps": [...]},
)

워크플로 포크

다른 워크스페이스의 워크플로를 자신의 워크스페이스로 복사합니다. 공개 템플릿을 사용할 때 유용합니다:

from roboflow.adapters import rfapi

forked = rfapi.fork_workflow(
    api_key="YOUR_API_KEY",
    workspace_url=workspace.url,
    source_workspace="other-workspace",
    source_workflow="their-workflow",
    name="내 포크",       # 선택 사항; 기본값은 원본 이름
    url="my-fork",        # 선택 사항; 기본값은 자동 생성된 슬러그
)

워크플로 버전 나열

versions = rfapi.list_workflow_versions(
    api_key="YOUR_API_KEY",
    workspace_url=workspace.url,
    workflow_url="my-workflow",
)

워크플로 삭제(소프트 삭제)

rfapi.delete_workflow(api_key="YOUR_API_KEY", workspace_url=workspace.url, workflow_url="my-workflow")

이렇게 하면 워크플로가 워크스페이스의 휴지통 으로 이동하며, 30일 후 영구 정리됩니다. 다음을 통해 복원하세요 Workspace.restore_from_trash("workflow", id) - 다음을 참조하세요 삭제 및 복원.

워크플로 실행

워크플로 실행은 Inference SDK 그리고 Workflows 런타임에 있으며, roboflow 패키지에 있지 않습니다. Python에서는:

from inference_sdk import InferenceHTTPClient

client = InferenceHTTPClient(
    api_url="https://serverless.roboflow.com",
    api_key="YOUR_API_KEY",
)
result = client.run_workflow(
    workspace_name="my-workspace",
    workflow_id="my-workflow",
    images={"image": "photo.jpg"},
)

CLI

명령줄에서 워크플로를 나열, 생성, 업데이트, 포크하고 버전을 관리할 수 있습니다.

워크플로 나열

roboflow workflow list

roboflow workflow list --json

워크플로 상세 정보 가져오기

roboflow workflow get my-workflow

roboflow workflow get my-workflow --json

워크플로 생성

roboflow workflow create --name "내 워크플로"

JSON 정의 파일이 있는 경우:

roboflow workflow create --name "내 워크플로" --definition workflow.json

옵션

플래그	설명
--name	워크플로 이름(필수)
--definition	JSON 정의 파일 경로
--description	워크플로 설명

워크플로 업데이트

워크플로 정의 업데이트:

roboflow workflow update my-workflow --definition updated.json

워크플로 버전 나열

roboflow workflow version list my-workflow

roboflow workflow version list my-workflow --json

워크플로 포크

현재 워크스페이스의 워크플로를 포크하려면:

roboflow workflow fork my-workflow

다른 워크스페이스에서 포크하려면:

roboflow workflow fork other-workspace/their-workflow

JSON 출력

모든 워크플로 명령은 --json 형식의 출력을 지원합니다:

roboflow workflow list --json | jq '.[].name'
roboflow workflow create --name "Test" --json

종료 코드: 0 = 성공, 1 = 오류, 2 = 인증 오류, 3 = 찾을 수 없음.