개발자 문서

MCP · AI 에이전트

MCP 도구 레퍼런스

로컬 CLI와 원격 MCP의 도구 123개입니다. 실제 이름·입력은 aimz tools로도 조회할 수 있습니다. 연결 방식에 따라 사용 가능한 도구가 다르며, 로그인한 사용자의 계정과 권한으로 동작합니다.

참고
결과는 JSON 으로 돌아옵니다. 응답이 매우 크면(6만 자 이상) 잘라서 truncated: true 와 함께 돌려주므로, limit·query 로 범위를 줄여 다시 부르세요.

ComfyUI 도구를 처음 쓴다면 대시보드 워크플로우 선택부터 실행·결과 확인까지 순서대로 볼 수 있습니다.

참고
확정 장면을 다중 참고 모델로 수정할 때는 원본 장면을 첫 이미지, 캐릭터 정체성 참고를 두 번째로 두고 역할을 설명하세요. 소품만 바꾼다면 변경 지시를 짧게 쓰고 캐릭터·구도·팔레트·재질을 유지합니다. 모델마다 결과가 다르므로 대표 한 장의 실제 비율과 그림체를 검수한 뒤 나머지를 진행하세요.

예제 영상의 두 에이전트 경로 확인

앞으로 만드는 모든 예제 영상은 외부 공개 MCP/CLI 연결 에이전트와 내부 Labs 워크스페이스 채팅 에이전트에서 각각 실제로 확인합니다.
같은 요구·확정 참고 원본과 역할·순서·스타일·모델·길이·비율·음향 기준을 사용하고 필요한 차이는 실행 전에 기록합니다.

경로실제 확인할 실행대신할 수 없는 근거
외부 연결 에이전트공개 배포된 MCP 또는 설치된 CLI의 문서화된 기능으로 요청부터 결과·수정·복구까지 실행개발자 소스 import, SSH, 비공개 helper, 직접 DB/API 우회
내부 워크스페이스 채팅실제 채팅 요청과 에이전트가 선택·실행한 작업, 보드·라이브러리 결과 확인수동 캔버스 실행, 외부 에이전트의 성공 기록, 도구 목록만 확인
  1. 각 경로에서 기능·워크플로우 발견, 실제 입력·참고 연결, 견적·권한·승인, 실행·대기 상태, 결과의 노드 연결과 라이브러리 조회를 확인합니다.
  2. 부분 수정으로 원본·이력이 보존되는지, 재연결 후 같은 요청 ID로 작업을 복구하는지 확인합니다.
    다른 사용자의 작업을 중단하거나 실행 중인 작업을 고의로 실패시키지 않습니다.
  3. 클라이언트/서버 버전·시각, 비밀값을 뺀 대화·요청·도구/작업 ID, 참고 지문, 견적·승인 상한·누적 표준 비용·실제 차감을 남깁니다.
    일반 크레딧과 Comfy 크레딧을 구분하고 두 경로·재시도 비용을 기존 승인 범위에 합산합니다.
  4. 결과 URL·SHA·라이브러리 항목, 수정 전후·복구 근거와 실제 시각·음향·최종 전달 검수를 경로별로 기록합니다.
    참고 재사용은 가능하지만 한쪽 실행을 다른 쪽의 실행으로 세지 않으며, 생성 결과의 픽셀 동일성을 요구하는 것은 아닙니다.
주의
각 단계의 실제 관찰된 통과·실패와 미검증·차단 사유를 구분하세요.
도구 목록·모의 검사·과거 성공은 현재 두 경로의 동등성 검증이 아니며, 이 안내도 기존 검증 완료를 뜻하지 않습니다.
필요한 기능이 없으면 해당 제품 경로에 구현한 뒤 다시 검증해야 합니다.
실제 청취 등 미확인 항목이 남은 영상은 한계를 밝힌 검토본으로 전달하고 전체 완료·품질 승인으로 표시하지 않습니다.

단계별 승인과 범위 안 자동 진행

내부 채팅의 이전 대화 포함은 새 요청에 보낼 대화 범위를 선택합니다. 기본은 포함입니다.
끄면 이전 대화나 그 요약을 보내지 않으며, 질문 카드에 답할 때는 선택한 질문만 함께 보냅니다.
화면의 대화·보드 제작 기준·예산·미확정 요청은 지워지지 않습니다. 진행 중에는 선택을 바꾸지 못하며 다음 새 요청부터 적용합니다.

외부 MCP/CLI의 production_control과 내부 채팅의 진행 설정은 보드별 허용 범위를 사용합니다.
먼저 현재 도구 목록·입력 규격과 production_control(action="status")를 읽고, 사용자가 선택한 범위를 설정하세요.
모델이 승인 토큰을 만들거나 설정을 바꿔 범위를 넓힐 수는 없습니다.

모드허용 범위
plan · 기획만조회 단계만 수행합니다. 보드 저장·생성·후처리 등 변경은 실행하지 않습니다.
confirm · 단계별 승인변경마다 해당 도구·입력·견적을 보여 주고 사용자 확인 후 실행합니다.
bounded · 범위 안 자동사용자가 설정한 보드·종료 단계·예산·횟수 안에서 허용 도구를 진행합니다. 별도 확인이 필요한 자산·3D 변경과 허용되지 않은 도구까지 승인하지 않습니다.

end_stage는 plan → reference → generate → review → edit → delivery 중 마지막 허용 변경 단계입니다.
이미지·오디오 참고 생성은 reference, 영상 생성은 generate, 품질 검수 기록은 review, 수정·후처리·합본은 edit입니다.
CLI 0.4.46과 호환 서버에서는 미디어 검사·프레임 보기·음향 샘플과 청취를 reference부터 사용할 수 있습니다. 참고 원본 관찰과 품질 승인은 별개입니다.
delivery는 전달 준비 확인이며 공개 게시나 품질 자동 승인이 아닙니다.
max_steps(1~200)는 기록되는 도구 단계 수, max_retries(0~50)는 노드별 반복 생성 한도입니다.

configure 입력 예시 · 실제 승인 예산과 현재 revision으로 변경
{
  "board_id":1, "action":"configure", "expected_updated_at":"현재 보드 updated_at",
  "config":{"mode":"confirm","end_stage":"review",
    "limits":{"general_credits":200,"comfy_credits":30,"max_steps":40,"max_retries":1}}
}

반환된 automation_id를 보관하고 production_step에 도구명·인자·단계를 전달합니다.
일반 생성은 production_run, Comfy 생성은 workspace_comfy_run을 이 경로로 호출해야 해당 자동화의 누적 예산에 들어갑니다.
직접 생성 도구로 우회하거나 새 보드·설정으로 기존 지출을 숨기지 마세요.

상태에서 읽을 값의미
usage.reserved_general_credits / reserved_comfy_credits서로 다른 단위의 누적 예약액. 일반·Comfy를 더하지 않으며 실패·적은 실제 차감·설정 변경으로 자동화 예약을 되돌리지 않습니다.
usage.actual_general_credits / actual_comfy_credits확인된 실제 차감 합계. actual_general_pending / actual_comfy_pending이 남으면 전체 정산이 끝난 값이 아닙니다.
remaining / pending남은 단계·크레딧 한도와 결과가 미확정인 요청. 무제한 일반 계정의 실제 0 차감도 표준 예약은 남습니다.

이 한도는 해당 자동화에 기록되는 미디어 도구 실행의 범위입니다.
채팅 모델의 대화 요금까지 포함하는 전체 요금 상한으로 해석하지 말고 대화 견적도 별도로 확인하세요.

  1. 단계 request_id를 실행 전에 보관하고, 내부 생성 요청의 ID·plan_hash 또는 plan_id도 따로 보관합니다.
  2. 응답 유실은 같은 단계 ID로 기록을 확인합니다.
    결과가 미확정이면 원래 생성 ID로 작업을 조회하며 새 UUID로 재접수하지 않습니다.
  3. 비용 예약이 없는 비생성 단계의 응답을 끝내 복구하지 못하면 사용자가 현재 보드·라이브러리를 확인한 뒤 acknowledge에 원래 단계 ID와 확인 내용을 남길 수 있습니다.
    이는 자동 대기만 끝내며 결과는 outcome_unverified=true로 남습니다.
    서버 작업 취소·재실행·예약 환급·성공 판정은 하지 않고 생성 요청에는 사용할 수 없습니다.
  4. pause는 다음 변경을 막습니다.
    이미 접수한 생성은 취소하지 않으므로 같은 ID로 상태·결과를 확인합니다.
    resume은 최신 revision과 사용자 승인이 필요하며 누적 예산·횟수는 유지합니다.
  5. 충돌이나 한도 초과는 최신 보드·상태를 다시 읽고 해결합니다.
    생성 완료·자동 진행 종료는 시각·음향 검수 통과가 아니며, 실제 듣지 못한 음향은 uncertain으로 남깁니다.

한 편의 영상을 만드는 순서

CLI 0.4.45와 호환 서버에서는 production_commands(section="index")에서 필요한 항목을 고릅니다.
보드 전체를 반복해서 읽는 대신 production_inspect(section="nodes")로 대상 ID를 찾고, section="node_details"에 node_id와 필요한 fields를 보냅니다.
노드 상세 응답은 JSON 텍스트 기준 최대 6,000 UTF-16 단위이며, 긴 값은 encoding="json-fragment"로 나뉩니다. 반환된 next의 원본 지문·선택 항목 SHA·offset을 그대로 사용해 모든 조각을 순서대로 모은 뒤 해석하세요.
원본이나 선택 항목이 바뀌면 다음 페이지는 거절됩니다. 보드 장부 저장만으로 revision이 바뀐 경우에는 같은 원본 조각을 이어 읽을 수 있습니다. 반환된 URL은 저장된 보드 값이며 라이브러리 소유권이나 실제 미디어 검수의 증거는 아닙니다.

연결된 에이전트와 터미널은 같은 도구를 사용합니다. aimz tools production으로 실제 입력 Schema를 읽고, aimz call TOOL --data '@request.json'으로 호출합니다. JSON 결과는 result에 있습니다. 이미지·소리는 --out 새폴더에 저장할 수 있고 기존 파일은 덮어쓰지 않습니다. --yes는 이미 사용자가 승인한 범위의 확인에만 붙입니다.

  1. whoami → list_models → model_info로 권한·모델 입력을 읽습니다. 새 요청은 workspace_flow_plan(flow_id="custom") → workspace_flow_create로 설계합니다. 컷별 spec.shot_durations, 전체 길이·비율·소리, 사용자가 지정한 spec.video_model을 유지합니다. 최대36컷·300초 안에서 동작에 맞는 길이를 쓰며 상한을 채우려고 늘리지 않습니다.
  2. production_inspect → production_update(contract)에 brief·주체별 style·캐릭터/공간/소품 reference_roles·sound·표준 예산을 기록합니다. 시트는 참고 역할을 구분하고, 시작 이미지는 동작 직전 상태로 만듭니다. 확정 장면의 부분 합성은 장면을 첫 참고로 두고 변경만 짧게 지시합니다. 보호할 캐릭터 밖의 소품만 바꾸려면 workspace_mask_edit를 사용할 수 있습니다.
  3. R2V로 여러 참고와 장면 전환을 처리할 수 있는지 먼저 검토하고 I2V 시작 이미지 방식과 비교할 실제 노드2~6개를 준비합니다. production_compare는 요청·견적·지원 필드를 보여 줍니다. 프롬프트 장면 전환과 모델의 구조화된 멀티샷은 다릅니다. 같은 조건의 실제 통제 비교가 없으면 품질 우열을 단정하지 않고 decision.controlled_comparison=false와 선택 이유를 남깁니다.
  4. production_update(decision) → production_plan의 blockers를 해결한 뒤 승인된 범위에서 production_run을 한 노드씩 실행합니다. 표준 비용 예약은 보드에 먼저 저장되고 재시도에도 누적됩니다. 무제한 계정의 실제 차감0과는 다릅니다. 진행 중·응답 유실에는 같은 request_id·plan_hash와 recovery_only:true로 기존 작업을 조회·연결합니다.
    이 모드는 404여도 새 생성이나 영역 합성 후처리를 접수하지 않습니다.
    postprocessing_required이면 원본·라이브러리를 보존하고 필요한 후처리를 별도로 판단합니다.
  5. production_media_inspect → production_media_job → production_media_view로 실제 시작·중간·끝 프레임을 보고 승인한 캐릭터·공간과 비교합니다. 중요한 동작 전후는 times로 추가합니다. production_audio_sample → production_media_job → production_audio_listen으로 실제 구간 소리를 받습니다.
  6. production_update(review)에 현재 fingerprint와 visual/audio/technical의 status·observed·evidence를 적습니다. SHA·검사 job·시간 구간·실제 관찰과 한계를 남기며, 생성 done을 품질 승인으로 바꾸지 않습니다. 수정은 production_update(edit)의 dry_run으로 먼저 확인합니다. 필요한 changes 또는 regenerate 목록만 적용하면 원본·이력을 보존하고 후속 결과가 stale이 됩니다.
  7. 완성본 노드를 계획·실행한 뒤 실제 순서·길이·컷 경계·마지막 프레임·소리를 검사합니다. production_media_finish로 정확한 크기와 선택적 iris를 만들고 검증한 결과를 production_attach_finish로 연결합니다. 새 결과를 다시 검수하고 production_delivery의 ready를 확인합니다. 이 과정은 공개 게시나 공유 설정을 변경하지 않습니다.
주의
음량·피크·LUFS 수치는 음성·음악·효과음 판정이 아닙니다. 실제 청취를 지원하지 않는 에이전트는 audio 검수를 uncertain, observed:false로 기록하고 승인하지 않습니다. 이미지 표본도 모든 프레임의 동일성을 증명하지 않습니다. 이전 검토 기록을 새로 직접 관찰한 것처럼 이관하지 마세요.

CLI 0.4.46은 Comfy 접수 뒤 단계 기록 저장만 실패한 경우 같은 바깥 production_step ID 재조회 또는 production_step 안에서 원래 실행 ID의 workspace_comfy_job 호출로 진행 기록을 복구합니다. 일반 작업 조회만으로는 바깥 단계가 복구되지 않으며, 현재 입력·계획·한도와 일치하는 본인 작업의 queued/running 영수증이 필요합니다. 예약액·단계 수·미정산 상태를 유지하며 재접수하거나 생성 작업을 acknowledge하지 않습니다. 다음 독립 컷도 현재 여유 슬롯과 참고·의존성 검사를 통과해야 합니다.

음향 검토를 기다리는 합본

CLI 0.4.38 이상과 호환 원격 MCP의 production_preview로 사용자가 검토할 합본을 만들 수 있습니다. 실제 완료된 현재 컷마다 visual·technical 검사가 passed여야 하며, technical evidence에는 해당 원본의 완료된 production_media_inspect 작업 job_id와 sha256를 넣습니다. 음향 미청취는 uncertain으로 유지합니다. 거절·실패·미완료·stale 컷은 허용하지 않습니다.

기존 sequence 노드에 이전 결과를 보존하며 저장하고 원본 컷 오디오만 사용합니다(clip_audio:true). 추가 내레이션·음악 입력이나 모델 생성 없이 0크레딧으로 처리합니다. 합본의 음량 조정·AAC 재인코딩은 적용될 수 있습니다. 결과는 review_pending:true, quality_approved:false, ready:false이며 공개 설정을 바꾸지 않습니다. 입력 변경을 뜻하는 stale와 검토 대기는 별개입니다. 검토본의 production_attach_finish는 차단되므로 필요한 원본 컷 후처리·검수를 먼저 진행합니다.

검토용 합본 · 같은 request_id로 진행 상태 확인
aimz call production_preview --data '@preview.json'
preview.json · 실제 보드와 sequence ID로 바꿉니다
{"board_id":1,"node_id":"final","request_id":"review-preview-01","timeout_sec":5}

접수 응답에서 job_id를 받지 못했어도 같은 request_id로 호출하면 본인 요청 키의 기존 합본을 조회합니다.
합본 작업은 약1시간의 임시 메모리에 있으므로 재시작·만료 후 404는 미접수나 실패의 증명이 아닙니다.
자동 재접수하지 말고 저장된 시도·라이브러리·원본을 확인하며 미확정 상태를 유지하세요.

URL을 전달할 때 검토 대기 중임을 표시합니다. 실제 사용자 또는 청취 가능한 도구의 검수 후 관찰자·원본·구간·한계를 기록하고 각 컷의 review를 갱신합니다. production_update(edit)에 regenerate:[최종노드ID]와 재합본 이유를 기록한 뒤 정상 production_plan/run으로 최종 합본을 만들고 실제 결과를 검수한 뒤 production_delivery를 확인합니다. 검토본 생성만으로 품질 승인을 만들지 않습니다.

검수: 파일 안의 URL·작업 ID는 현재 응답으로 채웁니다
aimz tools production
aimz call production_commands
aimz call production_media_inspect --data '@inspect.json'
aimz call production_media_job --data '@job.json'
aimz call production_media_view --data '@frame.json' --out ./review-start
aimz call production_audio_sample --data '@audio-sample.json'
aimz call production_media_job --data '@audio-job.json'
aimz call production_audio_listen --data '@audio-job.json' --out ./review-audio
inspect.json · 실제 4초 영상의 검사 입력 예
{"url":"내 생성 결과 URL","request_id":"inspect-01","times":[0.1,2,3.9]}
finish.json · 마지막 3초 타원 암전과 1280×720 패딩
{
  "url":"내 최종 결과 URL", "width":1280, "height":720, "request_id":"finish-01",
  "iris":{"duration":3,"cx":0.5,"cy":0.5,"width":0.38,
          "roundness":0.68,"shape":"ellipse","black_seconds":0.4}
}

iris를 생략하면 비율만 맞춥니다. duration은 1~10초, cx/cy는 정규화 중심 .05~.95, width는 출력 가로 대비 .1~.9, roundness는 세로/가로 반지름 비 .3~1.2, black_seconds는 .1~2초이면서 duration의 절반 미만입니다. shape는 ellipse/cat이며 cat은 ear_height(.05~.4), ear_spread(.5~.85)도 받습니다. 얼굴을 자동 추적하지 않으므로 실제 위치·모양을 검수하세요. iris가 소리를 만들거나 시각에 맞춰 이동하지는 않습니다.

검사·후처리는 0크레딧입니다. finish는 SAR 1:1의 영상(최대 300초·210MB)을 받고 각 변 64~1920의 짝수 크기로 패딩합니다. 지원되는 단일 MP4 오디오 스트림은 codec-copy 후 패킷 SHA를 비교하고 무음도 지원합니다. iris는 실제 0초 시작·일정한 1~60fps만 허용합니다. 결과의 source/derived SHA·decode·duration·SAR·암전 근거와 실제 화면을 확인하세요. 미디어 접수 응답에서 job_id를 잃었으면 production_media_job에 원래 request_id, operation, arguments 전체를 넣어 GET으로 복구합니다.
단계 자동화에서는 같은 바깥 production_step.request_id와 원래 도구·인자로 다시 조회하면 소유자·입력 서명이 일치하는 종료 영수증만 단계 장부에 반영합니다. 실패는 실패로 남고 품질 검수·승인을 대신하지 않습니다.
미디어 job은 약 1시간 메모리 상태입니다. 404는 미접수·만료·재시작을 구별할 수 없으므로 미확정을 유지하고 자동 재접수하거나 acknowledge하지 않습니다. 제작 예약은 이와 달리 보드에 남습니다. 긴 제작 기록은 section·offset·limit과 next_offset으로 끝까지 읽으세요.

제작 판단·검수·부분 수정

production_control

보드의 단계별 허용 범위·누적 사용량을 조회·설정·일시정지·재개합니다. 설정·재개·미확정 대기 종료는 사용자 승인이 필요하며 이전 예약을 지우지 않습니다.

인자형식설명
board_idinteger · 필수내 보드
actionstring = statusstatus · configure · pause · resume · acknowledge
configobjectconfigure: mode, end_stage, limits; 아래 단계별 진행 예시
automation_idstringpause/resume/acknowledge: 서버가 발급한 현재 ID
expected_updated_atstring변경 시 최신 보드 revision
confirm_tokenstring실제 사용자 승인 뒤에만 반환된 값 사용
request_idstringacknowledge: 미확정인 원래 단계 ID
notestringacknowledge: 사용자가 현재 결과를 확인한 내용

production_step

설정된 범위에서 실제 도구 하나를 실행하고 단계·예약·복구 기록을 남깁니다. 같은 단계 ID는 저장된 결과를 반환하며 생성·검수 승인을 대신하지 않습니다.

인자형식설명
board_idinteger · 필수설정한 보드
automation_idstring · 필수서버 발급 ID
request_idstring · 필수호출 전에 보관한 단계 UUID
namestring · 필수현재 도구 목록의 허용 도구명
argumentsobject · 필수해당 도구의 실제 입력; 내부 생성 request_id도 별도로 보관
stagestring · 필수plan · reference · generate · review · edit · delivery
confirm_tokenstring실제 사용자 승인 뒤에만

production_commands

제작 입력 예시를 필요한 항목만 읽습니다. 먼저 index에서 항목명을 찾고 그 section을 조회하세요. 모델과 ID는 현재 카탈로그·보드의 값으로 채웁니다.

인자형식설명
sectionstring = allindex는 목차, 목차의 이름은 해당 항목. all 또는 생략은 기존 전체 안내

workspace_monitor

소유 제작 현황 URL·참고·프롬프트·실행 종료 비율을 읽습니다. ETA 미확인은 null, 품질/납품 승인은 별도입니다.

인자형식설명
board_idintegerjob_ids와 하나만
job_idsstring[]소유 일반 작업1~20개
comfy_request_id / kindstringOwned Labs Comfy UUID; image|video|audio|auto
offset / limitinteger행 페이지, limit1~20
prompt_offsetinteger프롬프트 조각 문자 위치

production_inspect

현재 노드 지문과 제작 기록을 읽습니다. nodes로 대상을 찾고 node_details로 필요한 원본·설정만 조회하세요. 변경된 원본의 예전 검수는 재사용되지 않습니다.

인자형식설명
board_idinteger · 필수내 워크스페이스 번호
sectionstring = summarysummary · contract · decisions · reviews · attempts · history · nodes · node_details
offsetinteger = 0기록 페이지 시작; node_details는 반환된 next를 그대로 사용
limitinteger = 12기록 페이지 1~20; next_offset이 있으면 이어서 조회
node_idstringnode_details의 필수 대상 노드
fieldsstring[]node_details: name, src, from, roles, draft.model, draft.prompt, draft.params, text, gen.model, gen.prompt, seq, input, mask, element, scene, stale 중 필요한 항목
expected_fingerprintstringnode_details의 다음 페이지에 필수: 첫 응답의 현재 원본 지문
expected_projection_sha256stringnode_details의 다음 페이지에 필수: 같은 선택 항목의 projection SHA

production_update

contract·decision·review·edit를 최신 revision에 저장합니다. 생성하지 않으며 edit는 원본·이력을 보존하고 영향을 받는 후속 결과를 stale로 표시합니다.

인자형식설명
board_idinteger · 필수
operationstring · 필수contract · decision · review · edit
payloadobject · 필수production_commands의 입력 규격. edit: reason, changes, add_nodes, regenerate, dry_run. params는 옵션 객체 전체 교체
expected_updated_atstring · 필수직전 조회의 updated_at; 충돌 시 다시 읽고 판단

production_compare

비교 노드들의 실제 모델·입력·견적·검수 근거를 대조합니다. 생성하지 않으며 견적만으로 품질 우승을 정하지 않습니다.

인자형식설명
board_idinteger · 필수
node_idsstring[] · 필수같은 조건으로 비교할 서로 다른 실제 노드 2~6개

production_plan

한 노드의 요청·예상 표준 비용·누적 예약·검수 조건·plan_hash를 읽습니다. 미검수 참고·오래된 결정·예산 초과는 can_run=false입니다.

인자형식설명
board_idinteger · 필수
node_idstring · 필수실행할 한 노드

production_run

조건을 통과한 한 노드를 실행·확인·저장합니다. 표준 비용 예약은 보드에 먼저 기록하고 실제 계정 차감과 구분합니다. done도 품질 검수 전 상태입니다.

인자형식설명
board_idinteger · 필수
node_idstring · 필수
plan_hashstring · 필수현재 production_plan 결과
request_idstring · 필수고유 실행 키. 진행 중·응답 유실은 같은 키와 plan_hash로 복구
confirm_tokenstring사용자가 승인한 경우에만
recovery_onlyboolean = falsetrue면 기존 요청 조회·결과 연결만; 404에도 새 생성·후처리 접수 없음

production_preview

시각·기술 검사를 통과한 완료 컷을 검토용으로 이어 붙입니다(0크레딧). 음향 uncertain을 승인하지 않으며 결과는 review_pending=true, quality_approved=false, ready=false입니다.

인자형식설명
board_idinteger · 필수
node_idstring · 필수검토용 합본을 저장할 sequence 노드
request_idstring · 필수영문·숫자·_·- 8~40자, 응답 유실도 같은 키로 기존 합본 조회
timeout_secinteger = 50~30초. 재시작·만료로 조회가 404여도 자동 재접수 금지
recovery_onlyboolean = falsetrue면 기존 요청 조회·결과 연결만, 새 합본 접수 금지

production_media_inspect

내 이미지·영상·음원의 실제 SHA·길이·코덱·음량과 해당되는 치수·프레임을 검사하는 0크레딧 작업입니다. 음원은 frames=[]이며 커버 이미지가 붙은 음원은 지원하지 않습니다. 음성·음악·캐릭터 일치를 자동 판정하지 않습니다.

인자형식설명
urlstring · 필수내 생성/업로드 자산 URL, 최대 300초·210MB
request_idstring · 필수같은 검사 재조회용 키
timesnumber[]영상 안의 초 값 최대 12개. 기본 첫0.1·중간·끝0.1초 전; 이미지는 0, 음원은 생략 또는 빈 목록

production_media_job

미디어 검사·음원 추출·후처리의 기존 영수증을 GET으로 조회합니다. job_id를 잃었으면 원래 request_id·operation·arguments 전체로 조회하며 재접수하지 않습니다. 메모리 영수증은 만료/재시작으로 사라질 수 있어 404는 미접수 증명이 아닙니다.

인자형식설명
job_idstring반환된 pm_ 작업 ID. request_id 방식과 함께 사용 금지
request_idstring원래 미디어 도구의 내부 요청 ID
operationinspect | finish | audiorequest_id 조회 시 필수
argumentsobjectrequest_id 조회 시 원래 도구 인자 전체(URL·request_id·times 또는 출력 설정/음원 구간). 임의 필드 금지

production_media_view

완료한 검사에서 추출한 실제 프레임을 이미지로 반환합니다. 승인한 캐릭터·공간과 직접 비교하고 표본 검수의 한계를 기록하세요.

인자형식설명
job_idstring · 필수완료된 inspect 작업
frame_indexinteger = 0반환된 frames의 인덱스, 최대 0~11

production_audio_sample

원본 첫 오디오의 구간을 16kHz mono PCM WAV로 추출합니다(0크레딧). 합성·음량 보정·분류 없이 디코딩·리샘플한 청취 자료입니다.

인자형식설명
urlstring · 필수내 영상·음원 URL
startnumber · 필수시작 초
secondsnumber · 필수실제 미디어 안의 0초 초과~10초
request_idstring · 필수고유 추출 키

production_audio_listen

완료된 추출 작업의 실제 오디오를 반환합니다. 재생·청취를 지원하지 않는 에이전트는 observed=false, uncertain으로 기록하고 승인하지 않습니다.

인자형식설명
job_idstring · 필수완료된 audio 작업

production_media_finish

정확한 크기로 패딩하고 선택적으로 마지막 iris 암전을 적용해 라이브러리에 새 영상을 저장합니다(0크레딧). 원본을 보존하고 지원되는 원본 오디오 패킷을 복사·검증합니다.

인자형식설명
urlstring · 필수내 SAR1:1 영상, 최대300초·210MB
widthinteger · 필수64~1920 짝수
heightinteger · 필수64~1920 짝수
request_idstring · 필수고유 후처리 키
irisobject선택: duration, cx, cy, width, roundness, shape(ellipse|cat), black_seconds, ear_height, ear_spread. 아래 사용법 참고

production_attach_finish

현재 노드의 원본과 일치하는 본인 finish 결과를 보드에 적용합니다. 기존 결과·이력을 보존하고 후속 결과를 stale로 표시하며 새 결과는 다시 검수해야 합니다.

인자형식설명
board_idinteger · 필수
node_idstring · 필수
job_idstring · 필수완료된 본인 finish 작업
expected_updated_atstring · 필수현재 보드 revision

production_delivery

현재 원본과 일치하는 검수와 활성 작업을 확인해 전달 준비 여부를 반환합니다. 공개 설정 변경이나 갤러리 게시를 하지 않습니다.

인자형식설명
board_idinteger · 필수
node_idstring · 필수전달할 최종 결과 노드

ComfyUI 워커

workspace_comfy_plan

워크스페이스 ComfyUI 노드의 실제 연결·설정으로 서버 계획을 준비합니다. 생성하지 않으며 로컬 브라우저가 필요 없습니다.

인자형식설명
board_idinteger · 필수내 보드
node_idstring · 필수ComfyUI 이미지·영상·오디오 노드

workspace_comfy_plan_status

계획의 입력 규격·가이드·참고 연결·차단 사유·별도 컴피 견적을 확인합니다. 준비 중이면 같은 ID로 조회하세요.

인자형식설명
plan_idstring · 필수서버 계획 ID
offsetinteger = 0입력 페이지 시작
limitinteger = 401~100; next_input_offset으로 이어 읽기

workspace_comfy_capacity

내 계정의 현재 Comfy 실행 한도와 다른 보드를 포함한 진행 요청을 조회합니다. 기본 1, 관리자가 최대 5로 설정합니다. 조회는 슬롯을 예약하지 않습니다. 미확정 요청은 먼저 같은 ID로 복구하세요.

인자 없음

workspace_comfy_run

현재 입력과 일치하는 실행 가능 계획을 제출합니다. 별도 컴피 권한·잔액·계정 실행 한도를 적용합니다.

인자형식설명
plan_idstring · 필수runnable=true인 계획
request_idstring · 필수미리 보관한 새 소문자 UUID
max_creditsinteger · 필수현재 예상액 이상의 승인 상한. first_run은 전체 잔액 임시 예약이 필요할 수 있으므로 credit_cap.minimum도 확인
confirm_tokenstring사용자가 승인한 경우에만

workspace_comfy_job

내 실행·정산·라이브러리 결과를 조회합니다. 완료 시 원본이 그대로인 노드에 연결하며 변경·충돌 시 덮어쓰지 않습니다. 접수 불확실도 같은 ID로 확인합니다.

인자형식설명
request_idstring · 필수실행 UUID
attach_resultboolean = truefalse면 보드·정산 기록을 쓰지 않고 조회만
board_idinteger = 0영수증 404 시 소유 보드의 기존 예약·계획을 조회합니다. 재접수하지 않으며 계획 404도 미확정으로 보존

comfy_status

ComfyUI 실행 권한, 컴피 실행 크레딧과 내 대기열을 조회합니다.

인자 없음

comfy_wiki_find

현재 매뉴얼을 번호·ID·이름·용도로 찾습니다. 개인 저장본은 로그인한 본인만 조회합니다.

인자형식설명
querystring목차 검색어
limitinteger1~20, 기본 10
offsetinteger페이지 시작 위치
sourcestring = dashboarddashboard · personal

comfy_wiki_read

현재 원본에 묶인 Markdown 사용법을 페이지별로 읽습니다. stale/missing·legacy_notes는 최신 전체 매뉴얼이 아니며 입력 unknown은 실제 계획에서 확인해야 합니다.

인자형식설명
workflow_idstring · 필수위키 목차의 workflow_id
sourcestring = dashboarddashboard · personal
offsetinteger = 0다음 페이지는 manual.next_offset
limit_charsinteger = 40002~6000 UTF-16 단위
expected_manual_sha256string다음 페이지에 필수: manual.manual_sha256
expected_content_sha256string다음 페이지에 필수: manual.source.content_sha256

comfy_personal_list

로그인한 내 ComfyUI 개인 워크플로우 목록을 조회합니다.

인자형식설명
querystring이름 검색어
limitinteger1~100, 기본 30
offsetinteger페이지 시작 위치

comfy_personal_get

내 개인 워크플로우의 저장된 원본 또는 노드 요약을 조회합니다.

인자형식설명
workflow_idstring · 필수개인 목록의 id
summary_onlybooleantrue면 원본 대신 노드 요약

comfy_node_info

ComfyUI 노드의 입력과 출력 규격을 조회합니다.

인자형식설명
namestring · 필수노드 클래스 이름

comfy_upload_input

로컬 파일을 내 컴피 입력 저장소에 올립니다(최대 50MB).

인자형식설명
pathstring · 필수로컬 파일 경로

comfy_upload_url

원격 MCP: HTTPS 미디어 URL을 내 컴피 입력 저장소에 올립니다(최대 50MB).

인자형식설명
urlstring · 필수HTTPS 미디어 URL

comfy_workflow_plan

대시보드 또는 내 개인 워크플로우를 준비하고 변경 가능한 입력과 비용을 확인합니다. Chrome 또는 Edge가 필요합니다.

인자형식설명
workflow_idstring · 필수대시보드 번호·ID 또는 개인 워크플로우 ID
sourcestringdashboard(기본) 또는 personal
inputsobject노드 ID별 입력 값

comfy_workflow_inputs

준비한 계획의 변경 가능한 입력을 페이지별로 확인합니다.

인자형식설명
plan_idstring · 필수준비 결과의 plan_id
offsetinteger페이지 시작 위치
limitinteger1~100, 기본 100

comfy_workflow_run

대시보드 또는 내 개인 워크플로우에서 준비한 계획을 실행합니다. 불확실하면 같은 작업 ID로 확인하세요.

인자형식설명
plan_idstring · 필수준비 결과의 plan_id
request_idstring · 필수새 소문자 UUID
max_creditsinteger · 필수승인할 최대 예약·사용 크레딧
confirm_tokenstring사용자가 승인한 경우에만

comfy_job

내 작업의 상태·결과·컴피 크레딧 정산을 확인합니다.

인자형식설명
request_idstring · 필수실행 시 사용한 UUID

comfy_download_result

내 작업의 결과 파일을 로컬에 저장합니다. 기존 파일은 덮어쓰지 않습니다.

인자형식설명
request_idstring · 필수작업 UUID
filenamestring · 필수결과 파일명
destinationstring · 필수저장할 새 로컬 경로
subfolderstring결과의 subfolder

comfy_cancel

내 작업 한 건을 취소합니다. 완료 상태를 확인한 뒤 정산합니다.

인자형식설명
request_idstring · 필수실행 시 사용한 UUID
confirm_tokenstring사용자가 승인한 경우에만

계정

whoami

로그인한 계정, 크레딧 잔액, 에이전트 확인 정책(모드·동의 여부).

인자 없음

agent_policy

현재 확인 정책과 모드 설명. 정책을 바꾸는 도구는 없습니다 — 사용자가 터미널에서만 바꿉니다.

인자 없음

생성

list_models

생성 모델 목록. credits 는 기본 옵션 1회 기준 크레딧, capabilities 는 params 에 넣을 수 있는 키.

인자형식설명
modalitystringimage · video · audio · text · model3d(글·그림 → 3D 모델) (비우면 전체)
querystring이름·id·브랜드 검색어

model_info

모델 하나의 입력 규격 — 키마다 타입·선택지·최소/최대·기본값. 생성 params.aspect_ratio는 출력 비율이며, GPT Image의 size(small·medium·large)는 픽셀 크기가 아닌 화질(low·medium·high)입니다. 구형 모델은 지원 비율이 다르므로 실제 선택지를 확인하세요.

인자형식설명
model_idstring · 필수list_models 의 id

list_voices

ElevenLabs 목소리 — 읽기(el_tts)·대화(el_dialogue) params 의 voice·voice2·voice3 에 id 를 넣습니다. source=library 면 ElevenLabs 공개 라이브러리(수천 개)에서 찾고, 그 id 도 그대로 씁니다. preview_url 은 들어도 크레딧이 들지 않습니다.

인자형식설명
sourcestring = accountaccount(계정 목록·기본 목소리) · library(공개 라이브러리)
querystring이름·분위기 검색
languagestringlibrary — ko · en · ja …
genderstringlibrary — male · female
agestringlibrary — young · middle_aged · old
use_casestringlibrary — conversational · narrative_story · characters_animation · social_media · advertisement · entertainment_tv · informative_educational
sortstringlibrary — trending · cloned_by_count · created_date
pageinteger = 0library — has_more 면 다음 쪽

find_voice

ElevenLabs 목소리 링크(elevenlabs.io/app/voice-library?voiceId=…)나 20자 ID 로 그 목소리를 찾습니다. 추가 요금이 붙은 목소리는 거절됩니다.

인자형식설명
link_or_idstring · 필수ElevenLabs 목소리 링크 또는 ID

estimate_credits

생성 전 예상 크레딧. credits_max 가 실제로 먼저 차감되는 상한입니다. out_size가 있으면 요청한 비율과 일치하는지 확인하세요. 정확한 비율을 지원하는 GPT Image 경로의 16:9는 1536x864, 9:16은 864x1536이며 1536x1024는 3:2입니다. 명시한 비율을 참고 이미지 비율로 덮어쓰지 말고, 첫 결과의 실제 가로·세로까지 확인한 뒤 여러 장을 생성하세요.

인자형식설명
model_idstring · 필수
paramsobjectgenerate 에 넣을 params 그대로

generate

생성 한 건(크레딧 사용). 정책에 따라 처음 한 번 사용자 확인을 거칩니다. 여러 개는 generate_batch 를 쓰세요. 서버 줄이 꽉 차면(429) 잠시 기다렸다 같은 요청으로 다시 보냅니다.

인자형식설명
model_idstring · 필수
paramsobject · 필수model_info 의 키만. prompt 필수(그림만 받는 모델은 init_image). 이미지·영상·오디오 입력은 http(s) URL 또는 이 PC 의 파일 경로(자동 업로드). 3D 모델(tripo-3d · tripo-3d-image)은 결과가 GLB 주소
waitboolean = true끝날 때까지 기다리기
timeout_secinteger = 300기다릴 최대 초(5~3600). 넘으면 job_id 로 job_status
session_idstring같은 값이면 한 묶음(세션)
download_dirstring결과 파일을 저장할 이 PC 의 폴더
confirm_tokenstring‘사용자 확인 필요’ 때 받은 일회용 표 — 사용자가 승인한 경우에만
projectstring스튜디오 프로젝트 이름 — 결과가 그 프로젝트에 담긴다(없으면 만든다). 비우면 오늘 날짜의 프로젝트(MCP 2026-11-12 모양)

job_status

생성 작업 상태(queued · running · done · failed · canceled)와 결과 URL.

인자형식설명
job_idstring · 필수
waitboolean = false끝날 때까지 기다리기
timeout_secinteger = 300
download_dirstring끝났으면 결과를 이 폴더에 저장

active_jobs

진행 중인(queued · running) 내 생성 작업.

인자 없음

recent_failures

최근 실패한 내 생성과 실패 이유.

인자형식설명
limitinteger = 101~100

대기열 조율

queue_status

서버 대기열 — 실행 칸 사용·대기 수·공급사 칸이 꽉 찬 모델·새 작업 예상 시작(초)·내 작업 순번과 요약 문장.

인자 없음

generate_batch

여러 생성을 한 번에 접수(승인 1번, 최대 20개). 서버 대기열이 순서대로 돌린다 — 꽉 차 있어도 실패가 아니라 대기.

인자형식설명
itemsobject[] · 필수[{"model_id": "…", "params": {…}}, …] — 항목마다 prompt 필수
waitboolean = falsetrue 면 모두 끝날 때까지 기다린다. 기본은 접수만 → wait_jobs
timeout_secinteger = 600
download_dirstring끝난 결과를 저장할 폴더(wait=true 일 때)
session_idstring한 묶음(세션)
confirm_tokenstring사용자가 승인한 경우에만
projectstring스튜디오 프로젝트 이름 — 전부 그 프로젝트에 담긴다. 항목마다 "project" 로 따로 줄 수도 있다

wait_jobs

여러 작업을 함께 기다린다. 결과를 done(URL·텍스트) · failed(이유) · pending(순번·예상 시간)으로 나눠 준다.

인자형식설명
job_idsstring[] · 필수최대 100개
timeout_secinteger = 600시간 안에 안 끝난 것은 다시 부르면 이어서 기다린다
return_whenstring = allall(모두 끝) · any(하나라도 끝나면 바로)
download_dirstring

파일

upload_file

이 PC 의 파일(이미지·영상·오디오·문서, 50MB)을 기본으로 라이브러리에 등록합니다. to_library=false는 임시 URL만 저장합니다.

인자형식설명
pathstring · 필수파일 경로
to_libraryboolean = true라이브러리 등록
request_idstring같은 입력 업로드 복구용 ID

download_outputs

결과 URL 들을 이 PC 폴더에 저장. 같은 이름이 있으면 덮어쓰지 않고 번호를 붙입니다.

인자형식설명
urlsstring[] · 필수
dest_dirstring · 필수저장 폴더

video_probe

영상 한 편의 주소가 무엇인지(제목·길이)와 그 영상에서 고를 수 있는 것(choices — 화질마다 어림한 크기, 끝에 소리만), 받는 값을 봅니다. 받지 않습니다. 유튜브·X·인스타그램·Threads·틱톡·Facebook·Twitch 와 서버가 아는 다른 사이트의 주소를 받습니다.

인자형식설명
urlstring · 필수영상 한 편의 주소
heightinteger = 1080이 값 이하에서 가장 좋은 화질의 크기를 함께 알려 준다(144~2160)
audioboolean = falsetrue 면 소리만(mp3)

video_download

영상 한 편을 서버가 받아 내 라이브러리에 저장합니다. 한 편에 정액이고 다 받아 저장한 뒤에만 크레딧이 듭니다. 15분·400MB 까지. 영상이 여럿인 게시물은 첫 영상을 받습니다.

인자형식설명
urlstring · 필수영상 한 편의 주소
heightinteger = 1080video_probe 의 choices 에서 고른 res(144~2160) — 그 이하에서 가장 좋은 화질
audioboolean = falsetrue 면 소리만(mp3)
waitboolean = true끝날 때까지 기다린다
timeout_secinteger = 600
download_dirstring이 PC 에도 저장할 폴더
request_keystring끊겨서 다시 부를 때 처음 받은 값 — 새로 받지 않는다

video_job

영상 받기·레퍼런스 분석 작업의 상태와 결과. 시간 안에 안 끝난 작업은 다시 시작하지 말고 이 도구로 이어서 기다립니다.

인자형식설명
job_idstring · 필수video_download · reference_analyze 가 준 값
waitboolean = false
timeout_secinteger = 300

image_edit_commands

이미지 편집 명령을 찾습니다 — 이미지 편집기(PhotoCraft 기반, 포토샵과 같은 메뉴)와 같은 엔진의 명령 760여 개 가운데 아이디·이름·메뉴에 낱말이 모두 든 것. 각 명령의 매개변수 설명(범위·기본값)이 함께 옵니다. 파일·창·설정·프리셋 계열은 없습니다.

인자형식설명
querystring예: gaussian blur · curves · image size · text · crop
limitinteger = 401~200

image_edit_run

라이브러리 그림 하나에 이미지 편집 명령을 차례로 걸고 결과를 라이브러리에 새 이미지로 남깁니다(원본은 그대로, 0 크레딧). 레이어·조정 레이어·마스크·선택·글·도형·필터·크기·자르기 명령이 다 됩니다. 결과는 한 장으로 합쳐집니다 — 레이어째 고치려면 화면의 '이미지 편집'에서 엽니다. 60MP·60MB·120초, 사용자마다 1분에 6번.

인자형식설명
imagestring · 필수라이브러리 그림의 주소(로컬 연결에서는 이 PC 의 파일 경로도 — 먼저 올린다)
stepsobject[] · 필수[{command: image_edit_commands 의 id, params}] 최대 40개, 위에서부터
formatstring = pngpng · jpg · webp
namestring라이브러리에 보일 이름
qualityintegerjpg · webp 의 1~100
download_dirstring이 PC 에도 저장할 폴더(로컬만)
source_generation_idinteger내 원본 라이브러리 ID. image를 비우면 이 항목의 주소 사용
source_output_indexinteger = 0원본 항목의 출력 순서
request_idstring실행 전 저장한 ID. 응답 유실 시 같은 인자로 복구

라이브러리 · 워크플로우

agent_archive_list

내 홈 에이전트 대화 보관함 목록.

인자형식설명
limitinteger = 501~100
offsetinteger = 0

agent_archive_get

보관된 홈 에이전트 대화와 작업 제안 상태.

인자형식설명
conversation_idstring · 필수보관함 대화 ID

list_projects

내 스튜디오 프로젝트(이름·세션 수·최근 사용) — 이미지·영상·오디오·채팅 탭 왼쪽 목록의 프로젝트입니다. 이 이름을 generate 의 project 에 줍니다.

인자형식설명
querystring이름 검색어

project_add

스튜디오 프로젝트를 찾거나 만들고, 이미 만든 결과를 그 안에 담습니다(크레딧 없음). 결과가 속한 세션이 통째로 옮겨집니다. 프로젝트 없이 쌓인 옛 결과를 정리할 때 씁니다.

인자형식설명
projectstring · 필수프로젝트 이름 — 같은 이름이 있으면 그 프로젝트
generation_idsinteger[]담을 생성물 번호(list_generations 의 id). 비우면 프로젝트만 만든다

library_get

내 라이브러리 ID로 원본 주소와 메타데이터를 확인합니다. 다른 계정의 항목은 관리자로도 조회할 수 없습니다.

인자형식설명
generation_idinteger · 필수라이브러리 항목 ID
output_indexinteger = 0출력 순서

library_upload

로컬 CLI에서 이미 만든 파일을 라이브러리에 등록합니다(50MB). 렌더·편집을 반복하지 않고 저장된 파일과 같은 request_id로 등록을 복구할 수 있습니다.

인자형식설명
pathstring · 필수보존된 로컬 파일
namestring표시 이름
request_idstring같은 업로드 재호출용 ID
scene_idinteger원본 3D 씬
source_generation_idinteger편집 원본의 내 라이브러리 ID
source_output_indexinteger = 0원본 출력 순서
source_refsarray가져온 본인 원본 목록 [{source_generation_id,source_output_index,source_url}], 최대 100개. 최종 타임라인 사용 증명은 아님

library_registration_status

등록 영수증을 조회합니다. registered와 generation_id가 확인돼야 라이브러리 등록 완료입니다. pending은 파일 저장 후 DB 등록 대기, unknown은 결과 미확정입니다.

인자형식설명
registration_idstring · 필수서버가 반환한 영수증 ID

library_registration_recover

이미 저장된 결과의 라이브러리 등록만 복구합니다. 생성·편집·업로드를 반복하지 않으며 unknown 결과는 다시 실행하지 않습니다.

인자형식설명
registration_idstring · 필수서버가 반환한 영수증 ID

list_generations

내 라이브러리. 기본으로 업로드한 원본과 생성 결과를 함께 조회합니다.

인자형식설명
modalitystring
querystring이름·프롬프트 검색
limitinteger = 201~200
offsetinteger = 0
folderstring'' 전체 · 'inbox' 미분류 · 폴더(프로젝트) id
session_idstring생성 묶음 — generate 에 준 이름표 또는 결과의 session_id
include_uploadsboolean = true업로드 원본 포함

list_workflows

Labs 워크플로우(기본 제공 + 내 것) 목록.

인자형식설명
querystring이름 검색어

get_workflow

워크플로우 하나(그래프 포함).

인자형식설명
wf_idstring · 필수

workflow_estimate

저장된 워크플로우의 서버 견적, 잔액과 모델 가용성. 실행하지 않습니다.

인자형식설명
wf_idstring · 필수

workflow_create

서버 검증을 거쳐 새 Labs 워크플로우를 저장합니다. 생성 실행이나 크레딧 사용은 없습니다.

인자형식설명
namestring · 필수
graphobject · 필수inputs와 nodes를 담은 그래프
descriptionstring
emojistring

workflow_runs

워크플로우의 실행 회차 목록을 조회합니다.

인자형식설명
wf_idstring · 필수

workflow_run_get

회차의 그래프·결과·진행 상태를 조회합니다.

인자형식설명
run_idstring · 필수

workflow_start

새 Labs 체인 회차를 만들고 입력을 고정합니다. 재전송은 멱등이며 생성은 하지 않습니다.

인자형식설명
wf_idstring · 필수
run_idstring · 필수r_ 뒤에 소문자·숫자 4~38자의 새 고유 ID
inputsobject입력 키와 문자열 값

workflow_plan

다음 단계의 모델·입력·견적과 plan_hash 를 확인합니다.

인자형식설명
run_idstring · 필수

workflow_step

확인한 단계를 실행하고 회차에 기록합니다. 대기 중이면 같은 계획으로 다시 확인하세요.

인자형식설명
run_idstring · 필수
plan_hashstring · 필수workflow_plan 의 값
timeout_secinteger = 300
confirm_tokenstring사용자가 승인한 경우에만

워크스페이스

workspace_list

내 워크스페이스 목록.

인자 없음

workspace_get

워크스페이스의 노드·연결·저장 시각을 조회합니다.

인자형식설명
board_idinteger · 필수

workspace_flows

예시 워크플로우 목록 — 기획부터 한 편의 영상까지 가는 흐름(숏드라마·시트콤·제품 광고·뮤직비디오·정보 숏폼·동화 애니메이션·영화 예고편·스토리보드 애니매틱·역사 다큐·애니메이션·요리 숏폼·판타지 시네마틱). 인물이 이어지는 흐름은 인물 그림에서 캐릭터 시트(흰 배경 4분할)를, 장소마다 공간 시트를 만들어 씬마다 참고로 싣습니다. 씬마다 같은 모습이어야 하는 핵심 물건(글자가 보이는 상표·간판·서류, 유물 같은 이야기의 중심 물건)은 소품 샷으로 따로 찍어 글자가 깨지지 않고 생김새가 이어지게 합니다. 시나리오가 올린 소품만 만듭니다. 씬 글은 영상 모델의 핵심 문서를 읽고 씁니다.

인자 없음

workspace_flow_plan

새 설계의 컷 길이·지원 모델·예상 크레딧을 비교합니다(생성·크레딧 없음). custom은 예산이 없어도 지원 모델 전체를 비교하고 기본 추천은 예산 안에서 평판이 가장 높은 모델입니다. 성공 응답에도 cheapest(최저가), cheaper(더 싼 대안), better(예산을 넘는 상위 대안)를 줍니다. 모델명과 견적을 함께 보여 주세요. 숫자 예산 없이 저렴하게 요청하면 cheapest.credits를 budget으로 다시 계획하되 spec·seconds·ratio·style·sound와 참고 입력·네이티브 소리 조건을 유지합니다. 명시한 숫자 예산이 우선입니다. rank_basis는 아레나 투표·맞대결 리뷰·계열 등급 중 순위의 근거입니다.

인자형식설명
flow_idstring · 필수새 설계는 custom, 명시적으로 고른 예시는 workspace_flows의 id
specobjecttitle·look·rule·mode·cast·places·props·bgm. look은 확정 외형·그림체를 역할별(Character/Environment/Props/Shared)로, rule은 수정 시 유지 제약을 기록. video_model: 명시한 영상 모델의 id(미지원 시 대체하지 않음). 시트 합계9개까지. shot_durations: 컷별 초 배열(최대36컷·합계300초)
secondsinteger = 0완성본 전체 길이, custom은 최대300초, 기존 예시는 최대180초. 지정하면 shot_durations 합계와 같아야 함
budgetinteger = 0크레딧 상한. 0이면 상한 없이 비교(custom); 기존 수동 예시는 원래 모델 유지
ratiostring16:9, 9:16 또는 1:1
stylestringanimation
soundstringeffects: 장면 효과음 중심

workspace_flow_create

새 설계 또는 명시적으로 고른 예시로 워크스페이스를 만듭니다(생성·크레딧 없음). workspace_flow_plan의 최종 spec·seconds·budget·ratio·style·sound를 그대로 전달합니다. 성공 응답에도 cheapest가 포함됩니다. 실제 생성 전 workspace_run_plan에서 최신 비용을 확인하세요.

인자형식설명
flow_idstring · 필수새 설계는 custom
specobjecttitle·look·rule·mode·cast·places·props·bgm. look은 확정 외형·그림체를 역할별(Character/Environment/Props/Shared)로, rule은 수정 시 유지 제약을 기록. video_model: 명시한 영상 모델의 id(미지원 시 대체하지 않음). 시트 합계9개까지. shot_durations: 컷별 초 배열(최대36컷·합계300초)
ideastring아이디어 메모
secondsinteger = 0custom은 최대300초, 기존 예시는 최대180초. 지정하면 컷별 길이 합계와 같아야 함
budgetinteger = 0크레딧 상한
ratiostring16:9, 9:16 또는 1:1
stylestringanimation
soundstringeffects
exampleboolean완성 예시 사본
namestring워크스페이스 이름
upload_urlstring사진 주소

workspace_set_ratio

기존 워크플로우의 미생성 컷 비율을 바꾼 사본을 만듭니다. 원본이나 기존 결과는 보존합니다.

인자형식설명
board_idinteger · 필수원본 작업판
ratiostring · 필수16:9, 9:16 또는 1:1
expected_updated_atstring · 필수workspace_get 의 저장 시각
sequence_idstring완성본이 여러 개일 때 대상

reference_estimate

레퍼런스 영상 분석의 값과 그 영상이 무엇인지(제목·길이)를 봅니다. 받거나 분석하지 않습니다. 5분까지이고 3분보다 길면 앞 3분만 분석합니다.

인자형식설명
urlstring영상 한 편의 주소(유튜브·X·인스타그램·Threads·틱톡 등)
video_urlstring또는 내 라이브러리의 영상 주소
model_idstring = gemini-flash영상을 보는 글 모델

reference_analyze

레퍼런스 영상을 컷으로 나누어 재고, 영상을 보는 글 모델이 구성·컷·인물·소리를 읽습니다. 값은 영상 길이만큼(쓴 만큼)입니다. 돌려주는 brief.flow 가 같은 구성의 워크플로우 설계입니다.

인자형식설명
urlstring영상 한 편의 주소(유튜브·X·인스타그램·Threads·틱톡 등 — 받은 영상은 라이브러리에 남는다)
video_urlstring또는 내 라이브러리의 영상 주소
model_idstring = gemini-flash
waitboolean = true
timeout_secinteger = 900
request_keystring끊겨서 다시 부를 때 처음 받은 값

workspace_reference

레퍼런스 분석으로 워크스페이스를 만들거나 고칩니다. flow 를 주면 그 영상과 같은 구성의 워크플로우가 새로 깔리고, board_id·node_id 를 주면 있는 시나리오 글 노드에 분석 메모를 잇습니다. 생성이나 크레딧 사용은 없습니다.

인자형식설명
flowobjectreference_analyze 의 brief.flow
notestring분석 메모
video_urlstring분석한 영상
ideastring사용자가 만들 소재(비우면 레퍼런스의 소재)
namestring워크스페이스 이름
board_idinteger있는 워크스페이스를 고칠 때
node_idstring분석 메모를 이을 글 노드
expected_updated_atstringworkspace_get 의 값

workspace_run_plan

아직 결과가 없는 노드를 만들 순서와 예상 크레딧, plan_hash 를 확인합니다. 뒤 단계의 견적은 어림입니다.

인자형식설명
board_idinteger · 필수
until_node_idstring이 노드에 필요한 것까지만

workspace_run

계획한 노드들을 의존 순서대로 만들고 결과를 같은 워크스페이스에 넣습니다. running 이면 같은 request_id 로 다시 부릅니다 — 도는 작업마다 지금 상태(대기 순번·생성 중)가 붙습니다. 승인한 한도를 넘기게 되면 멈춥니다. 시나리오가 올리지 않은 소품 칸은 만들지 않고 치웁니다(unused).

인자형식설명
board_idinteger · 필수
plan_hashstring · 필수workspace_run_plan 의 값
request_idstring · 필수8~40자 고유값
until_node_idstring계획과 같은 값
timeout_secinteger = 120한 번에 기다리는 초
confirm_tokenstring사용자가 승인한 경우에만

workspace_plan

노드 연결과 초안으로 생성 요청·견적·plan_hash 를 준비합니다. 완성본 노드는 이어 붙이기 요청(컷·대사·내레이션·배경 음악·자막)을 돌려줍니다(크레딧 없음).

인자형식설명
board_idinteger · 필수
node_idstring · 필수

workspace_generate

계획한 노드를 생성합니다. 대기 중에는 같은 request_id 로 재호출합니다.

인자형식설명
board_idinteger · 필수
node_idstring · 필수
plan_hashstring · 필수
request_idstring · 필수8~40자 고유값
timeout_secinteger = 300
confirm_tokenstring사용자가 승인한 경우에만

workspace_mask_edit

그림 노드에서 한 영역만 바꾸는 '영역 편집' 노드를 그 옆에 만듭니다(생성·크레딧 없음 — 화면의 마스크 칠하기와 같은 기능). 영역은 상자·타원으로, 그림에 대한 비율(0~1)로 줍니다. 영역 밖은 원본 그대로 남습니다. 돌려주는 marked_url 로 영역을 확인한 뒤 workspace_run_plan → workspace_run 으로 만듭니다.

인자형식설명
board_idinteger · 필수
node_idstring · 필수결과가 있는 그림 노드
shapesarray · 필수[{type: rect|ellipse, x, y, w, h}] — 0~1 비율
expected_updated_atstring · 필수workspace_get 의 updated_at
promptstring그 영역을 무엇으로 바꿀지 (비우면 지우기)
model_idstring참고 그림을 받는 그림 모델 (기본 nanobanana_pro)

workspace_comfy_inputs

워크스페이스의 ComfyUI 노드가 받을 입력을 읽습니다 — 워크플로우·그림/영상/음원 참고 순서·프롬프트·입력 설정. workspace_comfy_plan → workspace_comfy_run → workspace_comfy_job으로 실행·연결합니다.

인자형식설명
board_idinteger · 필수
node_idstring · 필수ComfyUI 노드의 id

workspace_comfy_result

끝난 ComfyUI 작업의 결과를 워크스페이스의 그림·영상 노드에 넣습니다(크레딧 없음). 기본은 새 사본, in_place 면 같은 워크스페이스. 작업이 아직 돌고 있거나 결과가 라이브러리에 아직 없으면 알려 줍니다.

인자형식설명
board_idinteger · 필수
node_idstring · 필수
request_idstring · 필수comfy_workflow_run 에 쓴 UUID
expected_updated_atstring · 필수workspace_get 의 updated_at
in_placeboolean같은 워크스페이스에 넣기

workspace_copy_result

완료 결과를 새 워크스페이스 사본에 넣습니다. in_place 면 같은 워크스페이스에 넣습니다. 원본이 변경됐다면 중단합니다.

인자형식설명
board_idinteger · 필수
node_idstring · 필수
job_idstring · 필수
expected_updated_atstring · 필수workspace_plan 의 updated_at
in_placeboolean = false같은 워크스페이스에 넣기

3D 씬

scene_catalog

씬 작업(ops) 설명과 고를 수 있는 값 — 몸·자세·동작·세트·도형·샷·카메라 무브. 좌표는 미터, 시간은 초. 크레딧을 쓰지 않는다.

인자 없음

list_scenes

내 3D 씬 목록 — id·이름·고친 때·브라우저에서 여는 링크.

인자형식설명
querystring이름 검색어

scene_get

씬 하나의 요약 — 인물·세트·카메라 이름과 자리·방향, 촬영 카메라, 길이.

인자형식설명
scene_idinteger · 필수
include_documentboolean = false전체 씬 문서도 반환 (큰 문서는 응답이 잘릴 수 있음)

scene_capture

저장된 씬의 이미지·프리비즈 영상을 로컬과 라이브러리에 저장합니다. 빠른 시안은 settings의 resolution [640,360]을 쓰고, shot_list의 컷 순서와 여러 시점을 실제 영상으로 확인하세요(Chrome·Edge 또는 Playwright Chromium 필요).

인자형식설명
scene_idinteger · 필수
dest_dirstring · 필수로컬 저장 폴더
kindstring = imageimage 또는 video
timeout_secinteger = 300최대 3600초
camerastring찍을 카메라 이름 (비우면 촬영 카메라)
at_secondsnumber = 0그림을 찍을 순간
pass_namestring = rgbrgb · depth · normal · lineart · pose · mask — 구도 입력(ControlNet·VACE)용 패스
to_libraryboolean = true로컬 파일 보존 후 라이브러리에도 등록

scene_view

씬을 실제 3D 화면으로 찍어 그림으로 돌려줍니다 — 고친 뒤 눈으로 확인하는 용도(저장 없음, 크레딧 없음). 기본은 전체 부감 + 평면도 + 촬영 카메라.

인자형식설명
scene_idinteger · 필수
viewsobject[]최대 8장: {view: camera|overview|top|custom|angles, camera, at, look_at, lens, target, angles, seconds, pass, size, guides, overlay(겹쳐 볼 사진 주소 — 그 비율로 찍는다), overlay_opacity}
presetstring = overviewviews 를 비우면: overview · cameras(모든 카메라) · active(촬영 카메라)
at_secondsnumber = 0
pass_namestring = rgbrgb · depth · normal · lineart · pose · mask
sizeinteger = 768긴 변 px (128~1600)
guidesboolean = false3분할선·안전선

scene_storyboard

스토리보드 한 장 — 카메라마다 한 칸(cameras), 시간을 나눈 컷(timeline — 컷이 있으면 그 순간의 카메라), 샷마다 한 칸(shots). 칸마다 카메라 이름·화각 또는 시각.

인자형식설명
scene_idinteger · 필수
modestring = camerascameras · timeline · shots(shot_list 의 샷마다)
at_secondsnumber = 0cameras 의 순간
countinteger = 6timeline 컷 수 (2~12)
save_to_libraryboolean = true라이브러리에도 넣기

scene_export_glb

씬 전체를 GLB 한 파일로 내 라이브러리에 저장합니다 — Blender·Unreal·Unity 에서 이어 작업. 그 순간의 자리·자세, 오브젝트 이름·카메라·조명 포함(스플랫 제외, 360° 하늘은 sky 주소로 따로).

인자형식설명
scene_idinteger · 필수
at_secondsnumber = 0그 순간의 자리
namestring파일 이름 (비우면 씬 이름)

scene_duplicate

씬을 통째로 복사해 새 씬으로 저장합니다 — 크게 고치기 전의 체크포인트.

인자형식설명
scene_idinteger · 필수
namestring비우면 '<원래 이름> 사본'

블록아웃 에셋 찾기 — Poly Haven(CC0) 모델·360° 하늘(HDRI)과 내 라이브러리의 3D 파일. 모델은 실제 치수(dims_m)를 함께.

인자형식설명
querystring영어 낱말 (chair · car · tree · sunset …)
kindstring = modelmodel · hdri
sourcestring = allall · polyhaven · library
limitinteger = 12최대 40
previewsboolean = false앞의 6개 미리보기 그림

asset_import

에셋을 씬에서 쓸 주소로 — Poly Haven 모델은 GLB 한 파일로 묶어 내 라이브러리에 올리고 url·dims_m·animations 를, HDRI 는 .hdr 주소를 준다. 결과의 use 를 scene_apply 에.

인자형식설명
asset_idstring · 필수asset_search 의 id (library:… 포함)
kindstring = modelmodel · hdri
resolutionstring모델 1k(기본)·2k·4k / HDRI 2k(기본)

scene_export_to_library

로컬 CLI와 원격 MCP에서 저장된 씬을 이미지 또는 영상으로 렌더하고 내 라이브러리에 저장합니다. 등록 상태와 결과 ID를 확인하세요.

인자형식설명
scene_idinteger · 필수
kindstring = imageimage 또는 video
camerastring찍을 카메라 이름
at_secondsnumber = 0
pass_namestring = rgbrgb · depth · normal · lineart · pose · mask

scene_inspect

카메라 점검 — 카메라마다 누가 화면 어디에 얼마나 크게 보이는지, 잘림·가림, 그리고 문제(가림·머리 잘림·인물 겹침·떠 있는 것·같은 자리에 겹쳐 선 것). 3D 화면의 씬 에이전트가 자기 결과를 검토할 때와 같은 계산이다.

인자형식설명
scene_idinteger · 필수
camerasarray볼 카메라 이름들 (비우면 촬영 카메라 먼저 최대 8대)
at_secondsnumber = 0그 순간

scene_create

새 씬을 만들고 ops 를 적용해 저장한다. 링크로 3D 화면에서 바로 열린다. 결과에 작업별 성공·실패와 카메라 점검(check)이 붙는다.

인자형식설명
namestring · 필수씬 이름
opsarray작업 목록 — 예: [{op:'add_person', name:'민수', body:'male', at:[0,0]}, {op:'add_camera', shot:'medium', subject:'민수', active:true}]

scene_apply

있는 씬에 ops 를 적용해 저장한다. 실패한 작업은 이유를 돌려준다(전부 실패하면 저장하지 않는다). 그 씬을 3D 화면에 열어 두면 몇 초 안에 저절로 바뀐다.

인자형식설명
scene_idinteger · 필수
opsarray · 필수작업 목록 (scene_catalog 참고)

영상 편집기

editor_open

이 PC에서 별도 브라우저 편집기 세션을 엽니다(Chrome·Edge 또는 Playwright Chromium 필요). editor 도구는 같은 aimz mcp 프로세스에서 이어 호출해야 합니다. 별개의 aimz call마다 세션이 이어지지 않습니다. 저장한 .fcproj는 project로 다시 열 수 있습니다. 크레딧을 쓰지 않습니다.

인자형식설명
projectstring이어서 편집할 프로젝트 파일 경로 (editor_save 로 저장한 것)
restartboolean = false열린 세션을 버리고 새로 띄운다

editor_commands

편집 명령 찾기 — 편집기의 모든 기능은 명령이다(700여 개). 결과의 params 가 그 명령의 인자. 비우면 갈래별 개수.

인자형식설명
querystring낱말 (예: razor, captions, marker add, export)
limitinteger = 40최대 200

editor_run

편집 명령 하나를 실행한다(되돌리기 한 단계). 시간은 틱(1초 = 254016000000), 많은 명령이 seconds 도 받는다.

인자형식설명
commandstring · 필수명령 id (예: timeline.razor)
paramsobject그 명령의 인자

editor_batch

명령 여러 개를 순서대로 실행한다. 기본은 전부가 되돌리기 한 단계이고 하나라도 실패하면 전부 되돌아간다. 값 자리에 {"$ref": [단계, 키…]} 로 앞 단계의 결과를 쓴다.

인자형식설명
stepsarray · 필수[{id, params}] 최대 2000개
labelstring되돌리기 목록에 보일 이름
atomicboolean = truefalse 면 하나씩 실행하고 실패한 곳에서 멈춘다

editor_inspect

편집기의 지금 상태 — 프로젝트 항목, 열린 시퀀스의 트랙·클립·마커, 선택, 내보내기 진행, 되돌리기 목록.

인자형식설명
whatstring = projectproject · sequence · state · jobs · history · session
iteminteger다른 시퀀스의 item id (what=sequence)

editor_import

CLI 0.4.43부터 본인 라이브러리 항목 ID로 원본을 가져옵니다. URL은 본인 항목과 정확히 일치할 때만 받으며 임의 외부 URL은 내려받지 않습니다. 가져온 목록은 세션 입력 기록이며 실제 타임라인 사용 여부의 증명은 아닙니다.

인자형식설명
sourcesarray로컬 파일 경로 또는 본인 라이브러리 URL
library_sourcesarray[{generation_id, output_index: 0}] — 최대 100개. sources와 합계 최대 200개

editor_frame

열린 시퀀스의 한 프레임을 그림으로 저장한다 — 편집 결과를 눈으로 확인할 때. 기존 파일을 덮어쓰지 않는다.

인자형식설명
dest_dirstring · 필수로컬 저장 폴더
secondsnumber그 시각 (비우면 재생 헤드)
formatstring = pngpng 또는 jpeg

editor_export

열린 시퀀스를 로컬 파일과 라이브러리에 저장합니다(파일당 50MB). 가져온 라이브러리 원본 목록도 기록합니다. 긴 영상은 editor_commands에서 실제 내보내기 옵션을 확인해 bitrateKbps를 정하고 파일 크기·화질을 검사하세요. 등록이 미완료면 반환한 recovery_arguments로 library_upload를 호출하고 다시 렌더하지 않습니다.

인자형식설명
dest_dirstring · 필수로컬 저장 폴더
filenamestring파일 이름
formatstring = h264h264 · hevc · prores · dnxhr · gif · wav · mp3 · aac · flac …
settingsobjectfile.exportMedia 의 나머지 인자 (예: width·height·bitrateKbps)
to_libraryboolean = true라이브러리 등록. false면 로컬 저장만
timeout_secinteger = 1800최대 6시간

editor_save

프로젝트를 이 PC 의 파일(.fcproj)로 저장한다. 옆에 미디어 목록(.media.json)을 함께 써서 editor_open 이 미디어를 다시 잇는다.

인자형식설명
pathstring · 필수저장할 경로

editor_close

편집기 세션을 닫는다. 저장하지 않은 편집이 있으면 닫지 않고 알려 준다.

인자형식설명
discardboolean = false저장하지 않은 편집을 버리고 닫는다

관리자

admin_status

(관리자 계정) ComfyUI 워커·브로커 상태 — 워커별 연결·큐·진행 작업·최근 실패.

인자 없음

admin_companies

관리자 승인 후 회사 목록과 리포트에 쓸 회사 ID를 조회합니다.

인자형식설명
confirm_tokenstring요청한 승인 후에만 사용

admin_credit_report

관리자 전용 회사별 월간 리포트. 사용자 승인 후 크레딧, 직원, API 추정 원가를 조회합니다. 확정 지출은 별도 청구서 검증이 없으면 비어 있습니다.

인자형식설명
startstring · 필수시작 월 YYYY-MM
endstring · 필수종료 월 YYYY-MM (최대 12개월)
company_idstring · 필수회사 ID
confirm_tokenstring요청한 승인 후에만 사용

admin_machgen_reconcile

관리자 승인 후 MachGen 거래와 연결된 작업의 부분 순 이용액을 조회합니다. 실제 현금 결제액이나 전체 공급사 지출은 아닙니다.

인자형식설명
startstring · 필수시작 월 YYYY-MM
endstring · 필수종료 월 YYYY-MM
company_idstring · 필수회사 ID
confirm_tokenstring요청한 승인 후에만 사용

범용 API

api_endpoints

서버 API 엔드포인트 검색. guard 가 admin 이면 관리자 전용입니다.

인자형식설명
querystring예: 'folders', 'credits', 'notices'
methodstringGET · POST · …
admin_onlyboolean = false

api_request

전용 도구가 없는 기능을 서버 API 로 직접 호출. 조회는 바로, 크레딧 사용·삭제·관리자 변경은 정책에 따라 확인을 거칩니다.

인자형식설명
methodstring · 필수GET · POST · PUT · PATCH · DELETE
pathstring · 필수/api/ 로 시작
queryobject쿼리 문자열
bodyanyJSON 본문
confirm_tokenstring사용자가 승인한 경우에만

예: 생성 결과

generate 결과 (요약)
{
  "job": { "job_id": "j_3a31…", "state": "done", "model_id": "nanobanana",
           "credits": 8, "outputs": ["https://…/image.png"], "error": "" },
  "estimate": { "credits": 8, "credits_max": 8, "exact": true },
  "uploaded": [],
  "urls": ["https://…/image.png"],
  "saved": ["./out/j_3a31…-image.png"]
}

텍스트 모델은 texts 에 답변이 들어옵니다. 시간 안에 끝나지 않으면 state 가 running 이고 hint 가 붙습니다 — job_status(job_id, wait=true) 로 이어서 기다리세요.