REST API 개요

Nodaro REST API는 Nodaro의 HTTP 인터페이스입니다. 워크플로와 단일 노드를 실행하고, 작업 상태를 알려 주고, 내 미디어를 저장하고, 캐릭터, 프리셋, 워크스페이스를 관리합니다. 요청과 응답은 HTTPS를 통한 JSON이며, 모든 요청에 Bearer 토큰이 들어갑니다. 같은 API가 Nodaro Cloud와 셀프 호스팅 설치에서 작동하며, TypeScript SDK와 CLI는 이 API의 얇은 클라이언트입니다.

기본 URL

모든 경로는 /v1/로 시작합니다. 예: https://app.nodaro.ai/v1/nodes. 크레딧과 조직처럼 Nodaro Cloud에만 있는 엔드포인트는 다른 에디션에서 404를 반환합니다. 엔드포인트가 제한되는 경우 각 페이지에 적혀 있습니다.

인증

모든 요청에 Authorization: Bearer <token>을 보내세요. 내 계정에는 설정 › API 토큰에서 만든 개인 API 토큰(ndr_…)을, 내 제품이 다른 Nodaro 사용자를 대신해 작동할 때는 OAuth 액세스 토큰(ndr_app_…)을, Community Edition 설치에서는 세션 JWT를 사용하세요. GET /v1/nodes, GET /v1/models 같은 일부 탐색 엔드포인트에는 토큰이 전혀 필요하지 않습니다. 토큰을 만들려면 인증을 읽어 보세요.

첫 번째 호출

이 예제는 노드 하나로 이미지를 생성하고 결과를 읽습니다. 생성은 비동기식입니다. 첫 호출은 작업 id를 반환하고, 작업이 완료될 때까지 폴링합니다.

export NODARO_API_KEY="ndr_..."

# 1. Start the job
curl -s -X POST https://app.nodaro.ai/v1/generate-image \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "prompt": "a snow leopard on a mountain ridge at dawn",
        "provider": "nano-banana-pro",
        "aspectRatio": "16:9"
      }'
# {"jobId":"0f1a9c2e-5b7d-4e8a-9c31-6d2f8b4a7e10"}

# 2. Poll the job until its status is "completed"
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
  }
}

import { createClient, StaticTokenAuth } from '@nodaro/sdk'

const client = createClient({
  baseUrl: 'https://app.nodaro.ai',
  auth: new StaticTokenAuth(process.env.NODARO_API_KEY!),
})

// Starts the job and polls it until it finishes.
const output = await client.nodes.runAndWait('generate-image', {
  prompt: 'a snow leopard on a mountain ridge at dawn',
  provider: 'nano-banana-pro',
  aspectRatio: '16:9',
})
console.log(output.imageUrl)

nodaro nodes run generate-image \
  --param prompt="a snow leopard on a mountain ridge at dawn" \
  --param provider=nano-banana-pro \
  --param aspectRatio=16:9 \
  --watch --json | jq -r '.output_data.imageUrl'

모든 생성 노드가 같은 패턴으로 실행됩니다. 노드 설정을 담아 POST /v1/<node-type>을 보낸 다음 작업을 폴링하세요. 단일 노드 실행을 참조하세요.

요청과 응답 규칙

• JSON으로 보내고 JSON으로 받습니다. 본문은 Content-Type: application/json과 함께 JSON으로 보내세요. 파일 업로드는 예외로 multipart/form-data를 사용합니다.
• id는 UUID입니다. 형식이 잘못된 id는 400 validation_error를 반환합니다.
• 대부분의 응답은 data로 감싸져 있습니다. 읽기는 { "data": … }를 반환하고, 삭제나 취소는 { "success": true }를 반환합니다. /v1/api/ 아래의 레거시 워크플로 엔드포인트는 페이로드를 그대로 반환합니다.
• 생성은 작업 id를 반환합니다. POST /v1/<node-type>은 { "jobId": "…" }로 응답하며, 그 옆에 adjustments나 warnings가 함께 올 때도 있습니다.
• 목록은 커서를 사용합니다. 목록은 커서를 반환하며, 대개 nextCursor입니다(GET /v1/jobs에서는 next). 다음 페이지를 가져오려면 이 값을 ?cursor=로 다시 보내세요. 커서가 null이면 더 이상 행이 없습니다. 커서는 불투명한 값이므로 파싱하거나 직접 만들지 마세요.
• 필드 형식은 두 가지입니다. 작업 객체는 output_data, created_at처럼 snake_case를 사용합니다. 워크플로, 실행, 그 밖의 대부분의 리소스는 camelCase를 사용합니다.
• 응답은 늘어납니다. 시간이 지나면서 새 필드가 추가됩니다. 모르는 필드 때문에 실패하지 말고 무시하세요.
• 오류의 형태는 하나입니다. 실패한 호출은 HTTP 상태와 { "error": { "code": "…", "message": "…" } }를 반환합니다. code로 분기하세요. 오류를 참조하세요.

선택 사항인 두 헤더로 요청 처리 방식을 바꿀 수 있습니다.

동기와 비동기

Nodaro에서 하는 일은 대부분 몇 초에서 몇 분이 걸리므로 API는 비동기식입니다. 생성 라우트는 즉시 jobId로 응답하고, 워크플로 실행은 executionId와 함께 202 Accepted로 응답합니다. 그런 다음 최종 상태가 될 때까지 작업이나 실행을 2~5초마다 폴링합니다. 1분 안에 끝날 것으로 예상되는 워크플로라면, POST /v1/api/run?wait=true가 최대 600초 동안 연결을 유지한 뒤 결과를 반환합니다. 인라인 텍스트 노드, 무료 미디어 처리, 구조화 LLM 호출처럼 동기식으로 응답하는 라우트도 일부 있습니다. 자세한 내용은 동기 또는 비동기를 읽어 보세요. 작업을 폴링하지 않으려면 Webhook 엔드포인트를 등록하세요. 그러면 내 작업 하나가 완료되거나 실패할 때마다 Nodaro가 서버로 서명된 이벤트를 보냅니다.

영역별 엔드포인트

실행하기

리소스

계정

레퍼런스

한도와 오류

개인 API 토큰은 워크플로 실행과 워크플로 목록 엔드포인트에서 기본적으로 분당 30회, 최대 120회까지 요청할 수 있으며, 일부 라우트에는 자체 한도가 있습니다. 상태 폴링은 토큰 한도에 포함되지 않습니다. 429는 속도를 늦추고 백오프로 재시도하라는 뜻이고, 4xx는 재시도하기 전에 요청을 고치라는 뜻이며, 5xx는 대개 일시적입니다. 요청 한도와 오류를 읽어 보세요.

언어별 클라이언트

• TypeScript와 JavaScript: npm install @nodaro/sdk. SDK는 타입, 타입이 지정된 오류, 폴링 도우미로 이 엔드포인트를 감쌉니다.
• 터미널과 CI: npm install -g @nodaro/cli. CLI는 --watch, --json과 함께 워크플로, 앱, 단일 노드를 실행합니다.
• 그 밖의 언어: OpenAPI 사양으로 클라이언트를 생성하거나, 일반 HTTPS 요청을 보내세요.
• AI 어시스턴트: 코드를 작성하는 대신 MCP 서버를 연결하세요.