RunningHub Seedance 2.0 API 설정: 키, 자산, 첫 번째 호출

AI Overview

RunningHub Seedance 2.0 API를 가장 빠르게 설정하는 방법은 무엇인가요?

RunningHub API 키를 생성하고, 정확한 Seedance 2.0 AI 앱 또는 모델 경로를 선택한 후, 최소한의 요청 하나를 전송한 다음 그 응답의 taskId을 폴링(polling)하세요. 업로드, 웹훅(webhook), 프로덕션 환경용 재시도 기능은 이 첫 번째 호출이 성공한 후에만 추가하세요.

AI App API을 사용해야 하나요, 아니면 ComfyUI 워크플로우를 사용해야 하나요?

입력 계약(input contract)이 고정되어 있고 호스팅된 형태로 제공되어야 할 경우 AI App API을 사용하세요. 팀에서 노드 매핑(node mappings)을 명시적으로 확인하거나, 재사용 가능한 그래프, 자산 준비(asset preparation), 프로젝트 간 달라질 수 있는 모델 단계를 필요로 할 경우 ComfyUI OpenAPI 경로를 사용하세요.

RunningHub에서 Seedance 2.0 자산 ID는 어떻게 작동하나요?

자산 ID는 지원되는 Seedance 2.0 노드가 사전 준비된 참조를 재사용할 수 있도록 합니다. ComfyUI 통합은 일반 텍스트 ID, asset:// 형식 값, 쉼표로 구분된 목록, 또는 JSON 배열 문자열을 모두 수용하지만, 선택된 노드가 여전히 유효한 입력 슬롯을 결정합니다.

완료된 작업 URL을 즉시 복사해야 하는 이유는 무엇인가요?

RunningHub은 업로드 및 생성 결과에 대한 일시적 미디어 링크를 문서화합니다. 작업이 성공하면 승인된 모든 MP4 및 포스터 파일을 즉시 귀하의 영구 저장소로 이동시켜야 합니다. 저장된 작업 ID는 영구 미디어 보관소가 아닙니다.

첫 번째 호출 전에 반드시 준비해야 할 사항

신뢰할 수 있는 설정은 네 가지 알려진 값으로 시작합니다: API 리전(region), 유효한 키, 정확한 AI 앱 또는 모델 식별자, 그리고 귀하가 직접 제어하는 스토리지 목적지입니다. 관련 없는 튜토리얼에서 엔드포인트를 복사해 그 요청 본문(body)이 호환된다고 가정하지 마세요. RunningHub은 여러 호출 방식을 제공하며, 각 공개 API 상세 페이지는 해당 경로에 대한 공식 계약서(contract)입니다. 보다 포괄적인 Seedance 2.0 API 가이드에서는 일반적인 비동기 패턴을 설명합니다. 본 문서는 RunningHub에 집중합니다.

API 키는 소스 관리 시스템(SoC) 외부에 보관하세요. 공식 ComfyUI 통합의 경우, 문서화된 환경 변수 설정 패턴은 다음과 같습니다:

export RH_API_BASE_URL="https://www.runninghub.cn/openapi/v2"
export RH_API_KEY="replace-with-your-key"

귀하의 RunningHub 콘솔 및 현재 문서에 표시된 리전 기반 URL을 사용하세요. 소비자 키(consumer key)는 적격 멤버십을 요구할 수 있으며, 엔터프라이즈 키는 다른 접근 규칙을 가질 수 있습니다. 카탈로그에서 모델을 볼 수 있는 능력과, 귀하의 키로 해당 모델을 호출할 수 있는 능력은 별개의 두 가지 검사 항목입니다.

크레딧을 사용하기 전에 하나의 수용 기준(acceptance shot)을 정의하세요: 하나의 주체(subject), 하나의 동작(action), 하나의 카메라 이동(camera move), 하나의 지속 시간(duration), 하나의 출력 비율(delivery ratio). 프롬프트 자체의 타당성 여부가 불확실할 경우, 먼저 Seedance 2.0 모델 워크스페이스에서 창의적 브리프(creative brief)를 테스트하세요. 이를 통해 프롬프트 문제와 통합 문제를 분리할 수 있습니다.

첫 번째 호출에는 시각적으로 단순한 수용 프레임(acceptance frame)을 사용하세요. 이 신선한 제품 이미지는 실루엣, 반사, 물의 움직임, 배경 안정성을 쉽게 검사할 수 있도록 해주며, RunningHub 벤치마크가 아닙니다.

올바른 RunningHub 경로 선택

이 작업을 위해 RunningHub은 두 가지 실용적인 경로를 제공합니다. AI 앱 경로는 공급업체가 이미 Seedance 2.0을 이름이 지정된 입력을 갖춘 안정적인 애플리케이션으로 패키징한 경우 유용합니다. 해당 앱 ID로 제출하면 taskId을 수신합니다. 그래프 자체가 프로덕션 로직의 일부이거나 Seedance 2.0 자산 도우미(asset helpers)가 필요한 경우, ComfyUI OpenAPI 플러그인이 더 적합합니다.

첫 번째 테스트에서는 경로를 혼합하지 마세요. 최소한의 AI 앱 요청은 인증, 앱 식별자, 큐 제출, 결과 검색을 입증해야 합니다. 최소한의 ComfyUI 호출은 동적 nodeInfoList 오버라이드를 도입하기 전에 내보낸 워크플로우가 변경 없이 실행됨을 입증해야 합니다.

공식 RunningHub ComfyUI 플러그인은 설정 노드, 환경 변수, 또는 .env 파일에서 설정을 읽을 수 있으며, 노드 설정이 우선 적용됩니다. 키가 어느 계층에서 제공되었는지 기록하세요. 그렇지 않으면 팀원이 환경 비밀(environment secret)을 갱신했음에도 불구하고 오래된 노드 값이 계속해서 무시된 채 우선 적용될 수 있습니다.

참조 자료 중심의 촬영물은 인물, 의상, 동물, 날씨, 위치를 모두 명확히 식별 가능해야 합니다. 이 이미지는 새롭게 생성된 예시 출력이며, 공식 모델 비교 자료가 아닙니다.

RunningHub Seedance 2.0 API 설정 단계별 안내

서비스가 실제로 소유한 변수만 노출하는 요청 골격(skeleton)으로 시작하세요. RunningHub의 현재 AI 앱 문서는 /run/ai-app/{appId} 형태의 엔드포인트를 보여주며, QUEUED, RUNNING, SUCCESS, FAILED 등의 상태를 갖는 작업 객체(task object)를 반환합니다. 필드 이름의 진실의 원천(source of truth)은 정확한 API 상세 페이지에서 생성된 요청 예제입니다.

const response = await fetch(`${RUNNINGHUB_BASE}/run/ai-app/${APP_ID}`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.RH_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    nodeInfoList: inputMappings,
    webhookUrl: process.env.RH_WEBHOOK_URL
  })
});

if (!response.ok) throw new Error(`Submit failed: ${response.status}`);
const task = await response.json();
```ComfyUI 워크플로우의 경우, 일치하는 예시 중 하나를 가져오고, 환경 구성(environment configuration)을 사용하지 않는 경우에만 `RH OpenAPI Settings`를 연결한 후 정적 값으로 그래프를 실행합니다. 작동이 확인된 후에는 프롬프트, 참조 이미지/비디오, 지속 시간, 화면 비율 또는 출력 옵션 등 변경이 필요한 노드만 노출하고, 해당 노드 ID를 워크플로우 버전 옆에 저장합니다.

RunningHub의 Seedance 2.0 애셋 도구는 또 다른 선택지를 제공합니다. `real_person_mode=false`는 직접 업로드(direct-upload) 경로를 따릅니다. 활성화 시, 선택된 로컬 이미지 또는 비디오 슬롯이 모델 요청 이전에 애셋으로 변환됩니다. `conversion_slots`은 어느 슬롯이 이 과정에 참여할지를 제어합니다. 실패 원인을 명확히 파악하기 위해 먼저 단일 이미지로 테스트하세요. 9개 이미지와 3개 비디오로 구성된 페이로드는 어떤 매핑에서 오류가 발생했는지 식별하기 어렵습니다.

```official-video
src=https://r2.seedance.tv/blog/gpt-image-2-5-to-video-workflow/product-orbit-motion-v1.mp4
poster=https://r2.seedance.tv/blog/gpt-image-2-5-to-video-workflow/product-orbit-motion-poster-v1.jpg
label=검색된 API 결과 확인을 위한 수직 제품 오르빗 비디오

재생 가능한 이 Seedance 모션 출력은 검색 후 점검해야 할 요소를 보여줍니다: 안정적인 제품 기하학, 제어된 카메라 움직임, 깨끗한 프레임입니다. 이는 RunningHub 벤치마크로 제시되지 않습니다.

API 경계를 넘어 지속되는 입력 구축

API는 어떤 파일이 첫 번째 프레임인지, 마지막 프레임인지, 캐릭터 참조인지, 스타일 참조인지 추론할 수 없습니다. 제출 전에 입력 매니페스트(input manifest)를 작성하세요. 로컬 이름, 소스 체크섬, MIME 유형, 의도된 슬롯, 생성된 경우 애셋 ID, 그리고 이를 참조하는 프롬프트 라벨을 저장합니다. 이는 final-2.png처럼 단순히 이름만 붙인 파일 폴더보다 훨씬 유용합니다.

{
  "shot": "kitchen-01",
  "references": [
    {"role": "first_frame", "assetId": "asset-example-01"},
    {"role": "style", "url": "https://your-storage.example/style.jpg"}
  ],
  "prompt": "중간 추적 샷; 셰프가 요리를 담음; 김이 피어오름; 따뜻하고 실용적인 조명",
  "ratio": "16:9"
}

문서화된 ComfyUI 통합은 단일 애셋 ID, asset://<asset_ID> 형식 값, 쉼표 또는 줄바꿈으로 구분된 값, 또는 JSON 배열 문자열을 모두 허용합니다. 이 유연성은 편리하지만, 일관성이 더 안전합니다. 코드베이스 내에서는 하나의 표현 방식을 고정하고, 그래프 실행 전에 반드시 유효성을 검사하세요. 이미지-투-비디오의 경우, 통합은 first_frame 및 last_frame을 식별하며, 멀티모달 비디오 노드는 여러 개의 이미지 및 비디오 슬롯을 노출할 수 있습니다. 자동화하기 전에 참조 패키지를 다듬으려면 참조-투-비디오 워크스페이스를 사용하세요.

프롬프트는 실행 가능한 샷 지시문으로 작성하세요. 프레이밍, 주체, 동작, 환경, 조명, 음향을 분리하여 기술합니다. 첫 번째 호출이 창의적으로 실패할 경우, 엔드포인트, 애셋, 프롬프트, 워크플로우를 동시에 변경하기보다는 한 가지 채널만 단순화하세요. 이미지-투-비디오 프롬프트 워크플로우는 재사용 가능한 프롬프트 패턴을 제공합니다.

이 완성된 최신 프레임은 가독성 있는 손동작, 음식의 기하학적 형태, 김, 실용적인 조명 등 네 가지 세부 사항을 보여주며, 생성된 클립 전체에서 점검해야 할 핵심 항목입니다.

결과 폴링, 저장 및 검토

제출 후, 폴링을 시작하기 전에 반환된 taskId을 즉시 영구 저장합니다. 상한선이 있는 지수 백오프(exponential backoff)를 사용하고, 종료 실패 시 중단하며, 폴링을 멱등성(idempotent)으로 설계해 재시작된 워커가 동일한 작업을 계속 수행할 수 있도록 합니다. 경로가 웹훅을 지원하는 경우, 페이로드를 신뢰할 수 있다고 간주하기 전에 서명 또는 공유 비밀키를 반드시 검증하세요. 콜백은 기존 작업 기록을 업데이트해야 하며, 두 번째 생성을 만들면 안 됩니다.

SUCCESS 상태가 되면 MP4 파일을 즉시 복사하세요. RunningHub은 생성된 결과 링크 및 업로드 링크가 24시간 후에 만료될 수 있다고 명시합니다. 따라서 사람이 검토 화면을 열 때만 다운로드하는 것은 안전하지 않습니다. 파일, 체크섬, 프로바이더 작업 ID, 프롬프트 버전, 소스 매니페스트, 생성 타임스탬프를 함께 저장하세요. 이후 배포 스택에서 필요할 경우에만 포스터와 브라우저 재생 가능 프록시를 생성합니다.

미묘한 움직임 검토를 위한 커피와 김 클립

이 두 번째 실제 모션 출력은 억제된 손 움직임, 피어오르는 김, 햇빛을 활용해 제품 오르빗과는 다른 실패 요인을 검토자에게 제공합니다.

클립 전체를, 단지 첫 프레임만이 아니라 꼼꼼히 검토하세요. 정체성, 객체 기하학, 동작 연속성, 카메라 경로, 배경 안정성, 음향 적합성, 배포 안전성 등을 평가합니다. 기술적으로 성공한 작업이라도 실제로는 사용 불가능할 수 있습니다. 여러 모델 또는 프로바이더를 사용하는 캠페인의 경우, 멀티모델 AI 비디오 워크플로우는 다양한 경로에 걸쳐 하나의 검토 기준을 유지하는 방법을 설명합니다.

패브릭 방향, 손 모양, 발 접지, 수평선 안정성, 카메라 높이 등은 모션 중심 결과에 대한 간결한 승인 체크리스트를 구성합니다.

일반적인 RunningHub Seedance 2.0 API 오류 해결

오류는 생명주기 단계별로 대응하세요. 401 또는 403 응답은 키, 리전, 멤버십 또는 권한 문제를 가리키며, 프롬프트와는 무관합니다. taskId이 반환되기 전에 거부된 요청은 일반적으로 엔드포인트, 앱 ID, 콘텐츠 유형 또는 본문 구조 오류를 의미합니다. 큐에 대기 중인 작업이 전혀 진행되지 않으면 큐 또는 타임아웃 문제가 있습니다. 콘텐츠 검증 세부 정보와 함께 FAILED 상태가 된 작업은 더 안전한 프롬프트 또는 참조를 필요로 합니다. URL이 만료된 SUCCESS 작업은 스토리지 실패를 의미합니다.| 증상 | 우선 확인 사항 | 시정 조치 | |---|---|---| | 권한 없음 | 키 소스 및 기본 리전 | 오래된 노드 재정의 제거; 최소 호출을 기준으로 키를 갱신하고 재테스트 | | 잘못된 노드 매핑 | 워크플로우 버전 및 노드 ID | 현재 그래프 내보내기 후, 명명된 노드만 업데이트 | | 자산 변환 실패 | 슬롯 이름, 유형, 소스 접근 가능성 | 하나의 슬롯만 테스트; 공식 문서에 명시된 직접 업로드 대체 방식 사용 | | 작업이 대기 중 상태 유지 | 폴링 간격 및 계정 큐 | 요청 간격 확보; 중복 작업 자동 생성 금지 | | 결과 URL 만료 | 내구성 있는 저장소 이벤트 | 원본 파일이 복사되지 않은 경우에만 재실행 | | 클립 시각적 오류 | 프롬프트 및 소스 매니페스트 | API는 그대로 유지하고, 창의적 변수 하나만 수정 |

상태 코드, 공급업체 오류 코드, 작업 ID, 워크플로우 버전, 그리고 민감 정보가 제거된 필드 이름을 로그에 기록하세요. API 키나 전체 개인 미디어 URL은 절대 로그에 남기지 마세요. 공급업체 라우트가 멱등성 키(idempotency key)를 노출하지 않더라도, 자체 서비스 내에서 멱등성 키를 추가해야 합니다. 이를 통해 클라이언트 측 재시도로 인한 중복 과금을 방지할 수 있습니다.

통합이 기술적으로는 정상 작동하나 협업이 병목 현상을 일으키고 있다면, 참조 자료 정리, 간략한 요구사항을 샷 단위로 전환, 승인된 출력 비교, 실패한 단계만 재실행하기 위해 Seedance Agent를 활용하세요. 이는 운영 단계(production-layer) 선택지이며, 근본적인 API 이해를 대체하는 것이 아닙니다.

결론

내구성 있는 RunningHub Seedance 2.0 API 설정은 단일 성공적인 cURL 명령이 아니라 생명주기(lifecycle)입니다. 올바른 AI 앱 또는 ComfyUI 라우트를 선택하고, 키는 코드 외부에 보관하며, 최소 호출 하나를 검증하세요. 자산은 명시적으로 매핑하고, taskId을 지속적으로 저장하세요. 폴링 시 요청 간격을 확보하고, 임시 결과는 즉시 복사하세요. 전체 클립은 서면 승인 체크리스트와 비교하여 평가하세요. 이러한 경계가 안정화되면, 웹훅, 보다 광범위한 멀티모달 입력, 배치 예약, 인간 승인 등 기능을 추가할 수 있지만, 추가 자동화로 인해 실패를 은폐해서는 안 됩니다. 비용 발생 전에 참조 자료 및 샷을 계획하고, 승인된 작업을 검토 및 선택적 재실행을 거쳐 계속 진행하려면, 프로젝트를 Seedance Agent로 시작하세요.