작업

작업은 Nodaro에서 생성의 한 단위입니다. 이미지 1장, 동영상 렌더링 1회, 음성 클립 1개가 각각 하나의 작업입니다. 노드를 실행하면 작업 ID가 반환되고, 워크플로를 실행하면 AI 노드마다 작업이 하나씩 만들어집니다. 작업 엔드포인트는 각 작업의 상태, 진행률, 결과, 크레딧을 알려 줍니다. 작업이 completed, failed, cancelled 중 하나가 될 때까지 폴링한 다음, output_data에서 결과를 읽으세요.

엔드포인트

OAuth 토큰으로 작업을 읽으려면 jobs:read 스코프가 필요합니다. 개인 API 토큰에는 스코프가 필요하지 않습니다. 폴링하는 대신 작업이 끝날 때 Nodaro가 서버에 알려 주게 하려면 Webhook 엔드포인트를 등록하세요.

작업 읽기

curl -s https://app.nodaro.ai/v1/jobs/0f1a9c2e-5b7d-4e8a-9c31-6d2f8b4a7e10/status \
  -H "Authorization: Bearer $NODARO_API_KEY"

{
  "data": {
    "id": "0f1a9c2e-5b7d-4e8a-9c31-6d2f8b4a7e10",
    "status": "completed",
    "progress": 100,
    "output_data": { "imageUrl": "https://…/0f1a9c2e.png" },
    "error_message": null,
    "error_hint": null,
    "credit_status": "committed"
  }
}

const { data } = await client.jobs.getStatus(jobId)
if (data.status === 'completed') console.log(data.output_data)

// The full record, with input_data and credits:
const { data: job } = await client.jobs.get(jobId)

nodaro jobs get 0f1a9c2e-5b7d-4e8a-9c31-6d2f8b4a7e10 --json

GET /v1/jobs/:id/status는 폴링 루프용으로 만들어졌습니다. input_data와 비용 필드를 생략하므로 GET /v1/jobs/:id보다 가볍습니다. 두 경로 모두 { "data": … }로 응답하며, 존재하지 않거나 내 것이 아닌 작업에는 404로 응답합니다. 작업 필드는 서버가 보내는 그대로 snake_case를 사용합니다.

input_data와 output_data는 공개용 보기입니다. 서버 내부에서만 쓰는 필드는 모든 호출자에게서 제거됩니다.

EDL 적용 작업의 output_data는 렌더가 무엇에서 잘렸는지 알려 줍니다. quality는 미리 보기면 "proxy", 최종본이면 "final"이고, 요청이 계획 클립을 보냈으면 clipKey가 그 클립을 가리킵니다. 오래된 EDL 적용 작업은 주문할 때의 품질로 읽힙니다.

이미지 작업의 이미지 크기

output_data에 imageUrl이 있는 모든 작업에는 이미지의 픽셀 크기도 담깁니다. 생성, 편집, 이미지 대 이미지 실행, 콜라주, 오버레이, 추출한 프레임 등이 해당합니다. 클라이언트는 이미지가 로드되기 전에 그리드를 배치하거나, 크기를 보여 주고 크기로 정렬할 수 있습니다.

{
  "imageUrl": "https://cdn.nodaro.ai/images/<jobId>.png",
  "imageUrls": ["https://cdn.nodaro.ai/images/<jobId>.png", "https://cdn.nodaro.ai/images/<jobId>-v1.png"],
  "width": 1024,
  "height": 1536,
  "images": [
    { "url": "https://cdn.nodaro.ai/images/<jobId>.png", "width": 1024, "height": 1536 },
    { "url": "https://cdn.nodaro.ai/images/<jobId>-v1.png", "width": 1024, "height": 1536 }
  ]
}

세 필드는 모두 선택 사항으로 다루세요. 크기가 기록되기 전에 완료된 작업에는 이 필드가 하나도 없으며, 서버가 읽을 수 없었던 크기는 추측하지 않고 빠집니다. 이 필드는 모든 작업 읽기에 있습니다: GET /v1/jobs, GET /v1/jobs/:id, GET /v1/jobs/:id/status. MCP 작업 도구인 get_job, wait_for_job, get_asset은 outputUrl 옆에 width와 height를 담습니다.

작업 상태

복구 중인 작업. 모델이 이미 결과를 전달한 뒤 워커가 멈추면, 플랫폼이 복구하는 동안 작업은 recovering: true와 함께 processing 상태로 남습니다. 그 뒤 작업은 스스로 완료되거나 환불됩니다. 느린 모델에서는 수십 분이 걸릴 수 있으며, 이는 SDK의 기본 대기 시간보다 깁니다. runAndWait의 JobTimeoutError는 작업을 취소하지 않으므로, 나중에 작업을 다시 가져오세요.

검토를 위해 보류된 작업. 검토 정책을 등록한 배포 환경에서는 작업이 pending_review 상태가 될 수 있습니다. 작업 자체는 끝났고, 보류되는 동안 크레딧은 계속 reserved 상태이며, 결과를 공개할지는 사람이 결정합니다. 그 뒤 작업은 completed(승인), policy-block 힌트가 있는 failed(거부) 또는 cancelled로 끝납니다. 보류된 작업은 진행 중인 다른 작업처럼 취소할 수 있습니다. 요청을 다시 실행하지 마세요. 중복 요청도 보류되기 때문입니다. 배포 환경이 검토 기한을 정한 경우, 기한 안에 아무도 검토하지 않은 작업은 거부됩니다. 이 작업은 failed로 끝나고, 예약은 환불되며, 보류된 결과는 삭제됩니다. 보류된 작업이 자동으로 승인되는 일은 없습니다. SDK의 runAndWait는 pending_review를 처음 확인한 폴링에서 JobHeldError를 던지고, CLI의 --watch는 코드 3으로 종료됩니다.

효율적인 폴링

• 2~5초마다 폴링하세요. 작업 상태는 밀리초가 아니라 초 단위로 바뀝니다.
• 상태 조회는 토큰의 요청 한도에 포함되지 않습니다. 개인 API 토큰의 분당 한도에는 워크플로 실행과 워크플로 목록 조회만 포함됩니다. 요청 한도를 참고하세요.
• 여러 작업을 한 번의 호출로 추적하세요. 작업마다 요청을 하나씩 보내지 말고 일괄 엔드포인트를 사용하세요.
• 클라이언트가 대신 기다리게 하세요. SDK의 client.nodes.runAndWait는 최대 15분 동안 2초마다 폴링하고, CLI의 --watch는 작업이 끝날 때까지 폴링합니다.

작업이 실패한 이유

오류의 오류 표는 작업을 만들지 못한 요청을 다룹니다. 나중에 실패한 작업에는 error_message가 있고, 두 종류의 실패에는 구조화된 error_hint도 함께 있습니다.

모델의 안전 필터가 요청을 차단한 경우:

{ "kind": "safety-block", "class": "safety", "retried": true, "suggestedProvider": "nano-banana-pro" }

• class는 copyright, likeness, safety 중 하나입니다. copyright나 likeness 차단은 최종 결과입니다. 같은 요청은 절대 통과하지 않습니다.
• 일부 모델에서는 safety 필터의 판정이 항상 일정하지는 않습니다. GPT Image 2, GPT Image 2.5 Flare, GPT Image 2.5 Sunburst에서는 Nodaro가 같은 요청을 추가 비용 없이 한 번 다시 시도합니다. retried는 그 재시도가 이미 실행되었는지 나타냅니다.
• suggestedProvider는 모델에 권장 대체 모델이 있을 때만 나타납니다. 실제 모델 ID이므로, 같은 프롬프트와 레퍼런스를 이 모델로 보내세요.

배포 환경의 정책이 작업을 거부한 경우:

{ "kind": "policy-block", "policyId": "brand-safety", "reason": "This image was not approved for release.", "hookPoint": "result" }

• reason은 배포 환경의 정책이 내 사용자를 위해 쓴 텍스트입니다. 그대로 보여 주세요.
• hookPoint는 작업이 실행되기 전에 거부되었으면 request이고, 실행 후 결과가 거부되었으면 result입니다. 검토자가 거부한 경우도 result입니다.
• 플랫폼은 정책 거부를 재시도하지 않으며 다른 모델을 제안하지 않습니다.

그 밖의 실패에는 error_hint가 없습니다. 설정이나 입력 미디어가 해당 모델에 유효하지 않아 모델이 요청 자체를 거부하면, error_message가 그렇게 알려 줍니다. 다시 실행하기 전에 설정이나 미디어를 바꾸세요. 모델 쪽 오류는 문구와 관계없이 다시 시도할 만합니다. error_hint는 error_message가 있는 모든 작업 페이로드에 나타납니다. 전체 작업, 상태 경로, 목록, 두 일괄 경로 모두 해당됩니다.

작업의 크레딧

credit_status는 작업의 크레딧 예약 상태를 따릅니다.

이 필드는 GET /v1/jobs, GET /v1/jobs/:id, GET /v1/jobs/:id/status, GET /v1/jobs/status에 나타나며, POST /v1/jobs/batch-status에는 나타나지 않습니다. 안전 차단이나 정책 차단으로 끝난 생성은 항상 환불됩니다. 드문 예외는 정책이 결과를 거부하기 전에 크레딧이 이미 정산된 작업입니다. 크레딧을 참고하세요.

작업의 credits는 작업이 접수될 때 예약한 금액이며, 바뀌지 않습니다. GET /v1/jobs와 GET /v1/jobs/:id에는 credits_charged도 있습니다. 예약이 정산된 뒤 작업에 든 비용이며, 같은 크레딧 기록에서 읽습니다.

• credits_charged는 credits보다 적을 수 있습니다. 일부 작업은 다시 렌더링할 가능성이나 실행 후에 측정되는 길이를 감안해 실제 사용량보다 많이 예약합니다. 나머지는 잔액으로 돌아갑니다.
• 예약이 환불되면 credits_charged는 0입니다.
• 작업이 아직 실행 중이거나(credit_status: "reserved"), 작업이 자체적으로 아무것도 예약하지 않았으면 credits_charged는 null입니다.

작업 비용의 합계를 내려면 credits가 아니라 credits_charged를 합산하세요. 예를 들어 888크레딧을 예약하고 444크레딧으로 정산된 작업은 credits: 888, credits_charged: 444, credit_status: "committed"로 표시됩니다.

내 작업 목록

GET /v1/jobs는 내 작업을 최신순으로 { data: Job[], next } 형식으로 반환합니다.

status와 type은 쉼표로 구분한 목록(status=failed,cancelled)이나 반복한 매개변수(type=a&type=b)를 받습니다. 모든 필터는 정확히 일치해야 하며, 필터끼리 함께 쓸 수 있습니다. 한 페이지에 limit보다 적은 행이 있거나 행이 하나도 없어도 next가 있을 수 있습니다. 행 수를 세지 말고, next가 있는 동안 계속 다음 페이지를 가져오세요.

const { data: runs, next } = await client.jobs.list({ type: 'llm-structured', origin: 'my-app' })

즐겨찾기와 평가

내 생성 결과에는 두 가지 표시를 남길 수 있습니다. 둘 다 모든 작업에서 읽을 수 있고 목록 필터로 쓸 수 있습니다.

• 즐겨찾기는 작업에 다는 북마크입니다. 상태와 관계없이 내 작업이거나, 갤러리에 있는 다른 사람의 공개된 완료 작업에 달 수 있습니다.
• 평가는 내 작업 하나에 대한 내 판단으로, good 또는 bad입니다.

• 모든 작업에는 favorited와 rating이 담깁니다. GET /v1/jobs와 GET /v1/jobs/:id에서입니다. 서버가 잠시 이 값을 읽을 수 없으면 작업은 그대로 응답하고 두 필드는 빠집니다. 빠진 필드는 false가 아니라 알 수 없는 값으로 다루세요. 알 수 없는 즐겨찾기를 전환하면 즐겨찾기가 제거될 수 있습니다.
• 평가는 작업마다 하나이며, 작업 소유자의 평가입니다. 다른 사람의 작업은 404 not_found로 응답합니다. good, bad, null 이외의 평가는 400 validation_error로 응답합니다.
• 다른 사람의 비공개 작업을 즐겨찾기하면 404 not_found로 응답하며, 아무것도 저장되지 않습니다. 즐겨찾기 제거는 항상 작동합니다.
• 범위: OAuth 앱 토큰은 두 쓰기 작업에 assets:write가 필요하고, 내 즐겨찾기를 나열하려면 assets:read 또는 jobs:read가 필요합니다. 작업 읽기는 계속 jobs:read입니다.
• 갤러리를 숨기는 배포 환경은 모든 /v1/gallery 라우트에서 404로 응답합니다.

# Rate a job good, favorite it, then list your good favorites that completed
curl -s -X PUT "https://app.nodaro.ai/v1/jobs/$JOB/rating" \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rating": "good"}'
curl -s -X POST "https://app.nodaro.ai/v1/gallery/favorite" \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"jobId\": \"$JOB\"}"
curl -s "https://app.nodaro.ai/v1/jobs?rating=good&favorited=true&status=completed" \
  -H "Authorization: Bearer $NODARO_API_KEY" | jq '.data[] | {id, favorited, rating}'

여러 작업을 한 번에 폴링

두 엔드포인트가 작업 최대 100개의 상태를 한 번의 왕복으로 반환합니다.

curl -s "https://app.nodaro.ai/v1/jobs/status?ids=$JOB_A,$JOB_B,$JOB_C" \
  -H "Authorization: Bearer $NODARO_API_KEY"

{
  "jobs": [
    { "id": "0f1a9c2e-…", "status": "completed", "output_data": { "imageUrl": "https://…/a.png" }, "error_message": null, "error_hint": null, "credit_status": "committed" },
    { "id": "7d3e5f60-…", "status": "processing", "output_data": null, "error_message": null, "error_hint": null, "credit_status": "reserved" }
  ]
}

curl -s -X POST https://app.nodaro.ai/v1/jobs/batch-status \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"jobIds\": [\"$JOB_A\", \"$JOB_B\", \"$JOB_C\"]}"

존재하지 않거나 다른 사람의 작업 ID는 오류 없이 제외됩니다. 응답을 내 ID 목록과 비교하세요.

작업 취소 또는 삭제

POST /v1/jobs/:id/cancel은 작업을 취소하고 작업이 예약한 크레딧을 해제합니다. 응답은 { "success": true, "cancelled": 1 }입니다. pending_review로 보류된 작업도 취소할 수 있습니다.

DELETE /v1/jobs/:id는 작업과 작업이 만든 비공개 미디어를 삭제하고 { "success": true }로 응답합니다. 작업 소유자만 삭제할 수 있습니다. 실행 중인 작업은 그 상태 그대로 삭제되므로, 작업을 멈춰야 한다면 먼저 취소하세요.

curl -s -X POST https://app.nodaro.ai/v1/jobs/$JOB_ID/cancel \
  -H "Authorization: Bearer $NODARO_API_KEY"

const { cancelled } = await client.jobs.cancel(jobId)
await client.jobs.delete(jobId)

nodaro jobs cancel 0f1a9c2e-5b7d-4e8a-9c31-6d2f8b4a7e10

워크플로 실행 전체를 멈추려면 그 실행을 취소하세요. 실행을 참고하세요.

컴포넌트 실행

POST /v1/component/execute는 저장된 컴포넌트를 백그라운드에서 실행하고 { jobId }와 함께 202로 응답합니다. 이 작업은 다른 작업처럼 폴링하세요. 서버는 컴포넌트 실행에 90분을 주고, 안에 긴 렌더링이 있으면 그 시간 예산을 더합니다. EDL 적용 노드의 최종 렌더링이 그런 예입니다.

자체 시간 제한이 있는 클라이언트는 서버가 얼마나 기다릴지 물어볼 수 있습니다.

curl -s https://app.nodaro.ai/v1/component/execute/$JOB_ID/wait-limit \
  -H "Authorization: Bearer $NODARO_API_KEY"

{ "data": { "budgetExcessMs": 0, "waitLimitMs": 5400000, "pendingBudgetedNodes": true } }

• waitLimitMs는 이 실행에 대한 서버의 대기 시간으로, 90분에 budgetExcessMs를 더한 값입니다.
• budgetExcessMs는 실행이 긴 렌더링을 시작할 때까지 0입니다.
• pendingBudgetedNodes는 긴 렌더링이 아직 시작되지 않은 동안, 그리고 실행 자체가 아직 시작되지 않은 동안 true입니다. 따라서 초과분이 0이라고 해서 안에 긴 렌더링이 없다는 뜻은 아직 아닙니다.

두 값 모두 실행이 진행되는 동안 바뀔 수 있으므로, waitLimitMs에 도달하면 다시 물어보세요. 이 경로는 실행 소유자에게만 응답하며, 다른 사람과 컴포넌트 실행이 아닌 작업에는 404로 응답합니다. 에디터도 이 규칙을 따릅니다. 안에 긴 렌더링이 없는 실행은 30분을 기다리고, 긴 렌더링이 시작되면 waitLimitMs만큼, pendingBudgetedNodes가 true인 동안에는 최소 90분을 기다린 뒤 다시 물어봅니다.

동영상 생성 Pro 실행

동영상 생성 Pro는 긴 동영상을 세그먼트 단위로 하나씩 만들고 세그먼트 사이마다 진행 상황을 저장하므로, 실행을 중지했다가 나중에 이어 갈 수 있습니다. Nodaro Cloud에서 실행되며, 셀프 호스팅 설치에서는 Nodaro Cloud 연결을 통해 실행됩니다.

실행 중지

POST /v1/generate-video-pro/:jobId/stop은 processing 상태의 실행을 안전하게 중지합니다.

• 생성 중이던 세그먼트는 버려지지만, 모델이 계속 렌더링하므로 요금은 청구됩니다.
• 남은 세그먼트는 건너뜁니다.
• 완성된 모든 세그먼트가 이어 붙여져 작업의 최종 동영상이 됩니다.
• 예약에서 사용하지 않은 부분은 환불됩니다.

응답은 { "jobId": "…", "stopping": true }입니다. 작업을 계속 폴링하세요. 작업은 output_data.pro.stopped가 true로 설정되고 stoppedAtSegment가 포함된 채로 completed로 끝납니다. 아직 pending 상태인 작업은 대신 취소되고 전액 환불됩니다.

실행 이어 가기

POST /v1/generate-video-pro/continue는 끝난 작업에서 새 작업을 시작합니다. 부모 작업의 계획과 fromSegment 이전에 전달된 모든 세그먼트를 재사용하고, 그 지점부터 다시 생성합니다.

{ "fromJobId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "fromSegment": 4 }

• fromSegment는 1부터 셉니다. 기본값은 전달되지 않은 첫 번째 세그먼트입니다.
• 부모 작업은 끝난 상태여야 합니다. 중지되었거나, 전달된 세그먼트가 하나 이상 있는 상태로 실패했거나, 완료된 작업이어야 합니다. 완료된 실행에 fromSegment를 명시하면 결말을 다시 생성합니다.
• 다시 생성한 세그먼트와 동영상 생성 Pro의 고정 요금만 지불합니다.
• 이 경로는 Idempotency-Key 헤더를 지원하므로, 재시도한 요청이 두 번째 작업을 시작하지 않습니다.

응답은 { jobId, continuedFromJobId, fromSegment, segmentCount }입니다. 새 jobId를 폴링하세요.

curl -s -X POST https://app.nodaro.ai/v1/generate-video-pro/$JOB_ID/stop \
  -H "Authorization: Bearer $NODARO_API_KEY"

curl -s -X POST https://app.nodaro.ai/v1/generate-video-pro/continue \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4c1f0a7e-2b3d-4e5f-8a9b-0c1d2e3f4a5b" \
  -d "{\"fromJobId\": \"$JOB_ID\", \"fromSegment\": 4}"

await client.videoPro.stop(jobId)
const { data } = await client.jobs.getStatus(jobId) // completes with a partial video

const { jobId: childId } = await client.videoPro.continueRun(jobId, { fromSegment: 4 })

nodaro video-pro stop 9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d
nodaro video-pro continue 9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d --from-segment 4 --watch

두 경로 모두 내 작업이 아니면 404로, 동영상 생성 Pro 실행이 아닌 작업이면 400으로 응답합니다.

실행 견적

POST /v1/credits/video-pro-estimate는 작업을 만들거나 크레딧을 예약하지 않고 동영상 생성 Pro 실행의 가격을 계산합니다.

{ "provider": "gemini-omni-flash", "resolution": "720p", "duration": 12, "renderMethod": "keyframes", "segmentMode": "short" }

한 예시 구성에서 응답은 { "data": { "credits": 760, "upperBound": true } }입니다. 현재 가격은 실제 응답에서 확인하세요.

• segmentMode가 short 또는 long이면, 실행은 먼저 원본의 구간에 동작을 통째로 배정합니다. upperBound: true는 이 수치가 계획 전의 예약 한도라는 뜻입니다. 최종 청구액은 실제 계획을 따릅니다.
• planOnly 견적은 계획 수수료만 포함하며 upperBound: false를 반환합니다. 응답의 sourceSegmentDurations와 planCheckpoint는 같은 모드와 설정으로 각각 sourceSegmentDurations와 seedPlan으로 다시 보낼 수 있습니다.

세그먼트 분할 방식과 각 설정의 역할은 동영상 생성 Pro를 읽어 보세요.