사용자 이미지부터 다운로드까지: MCP로 투명 캐릭터 애니메이션 생성하기

AI 어시스턴트가 “작업이 대기열에 들어갔습니다”라고 말하거나 임시 링크를 반환했다고 MCP 애니메이션 작업이 끝난 것은 아닙니다. 제대로 된 전체 워크플로는 실제 이미지 바이트를 전송하고, 생성 전에 비용을 보여주고, 최종 상태까지 기다린 다음, 요청한 모든 파일을 저장하고 다운로드한 픽셀을 확인해야 합니다.

이 글은 2026년 9월 11일 Codex를 통해 완료한 실제 AnimGen 운영 MCP 실행을 기록합니다. 투명 캐릭터 PNG로 시작하여 원본 영상, 스프라이트 시트, JSON 메타데이터를 받았습니다. 이후 시각적 검토에서 첫 스프라이트 시트의 가로세로 비율 오류를 발견했습니다. 따라서 공개 샘플에는 정확히 같은 다운로드 MP4에서 수정 후 다시 내보낸 시트를 사용합니다. 모델을 다시 생성하지 않았고 추가 크레딧도 사용하지 않았습니다. 전체 검증 자료를 다운로드해 최종 파일을 확인할 수 있습니다.

결과 요약

36크레딧은 이 실행에 대한 당시 견적이지 고정 가격이 아닙니다. 사용 가능한 모델과 가격은 실시간 계정 응답을 기준으로 하므로 새로 생성하기 전에는 항상 다시 조회하고 견적을 확인하세요.

실제로 투명한 입력으로 시작하기

원본은 공개된 픽셀 여검사 PNG입니다. 실제 RGBA 파일이며 알파 채널 값은 0–255입니다. 네 모서리는 모두 투명하고, 캔버스의 약 27%에 보이는 캐릭터 픽셀이 있습니다.

원격 MCP 서버는 사용자 컴퓨터의 ./character.png 같은 경로를 열 수 없습니다. 클라이언트가 prepare_image_upload를 호출하고 반환된 HTTP 메서드와 헤더로 정확한 바이트를 전송한 뒤 complete_image_upload를 호출해야 합니다. 애니메이션 요청에는 이렇게 얻은 file_id만 넣어야 합니다.

이번 실행에서는 업로드 완료 응답의 파일 크기 875,625바이트와 SHA-256 해시가 로컬 원본과 일치했습니다. 임시 업로드 URL과 계정 소유 파일 ID는 공개 자료에 포함하지 않았습니다.

MCP 클라이언트에 범위가 명확한 작업 지시하기

재사용하기 좋은 시작점은 창작 결과와 운영 안전장치를 함께 설명하는 작업 프롬프트입니다.

Use the AnimGen MCP server to turn ./character.png into a transparent,
in-place walk animation for a 2D game.

First call list_models and confirm that Seedance 2.0 Fast supports a
first-frame request at 4 seconds and 480p. Upload the actual PNG bytes;
do not treat the local path as an uploaded image.

Use automatic Alpha Key mode. Request a 16-frame transparent sprite
sheet and matching JSON metadata at 256 × 256 per frame.

Before calling generate_animation, show me the exact request and current
credit quote and wait for my approval. Do not exceed the amount I approve.
Persist one idempotency key, poll the same task to a terminal state, then
download and verify every returned asset without exposing signed URLs.

이렇게 하면 세 가지 잘못된 완료 판단을 방지할 수 있습니다. 로컬 경로를 실제로 전송했다고 가정하는 것, OAuth 연결을 지출 승인으로 간주하는 것, 파일을 저장하지 않은 채 서명 URL만 보고하는 것입니다.

업로드 전에 연결하고 확인하기

AnimGen 운영 MCP 엔드포인트는 https://api.animgen.com/mcp입니다. Streamable HTTP와 OAuth를 사용합니다. 이 클라이언트 설정에 AnimGen API 키를 넣으면 안 됩니다.

Codex CLI의 연결 명령은 다음과 같습니다.

codex mcp add animgen --url https://api.animgen.com/mcp
codex mcp login animgen

공식 Codex MCP 문서는 원격 HTTP 서버와 OAuth 로그인을 설명합니다. AnimGen의 클라이언트 연결 가이드에서도 엔드포인트와 다른 호환 클라이언트를 다룹니다.

OAuth 연결 후 빈 객체로 list_models를 호출하세요. 구조화된 모델 목록으로 크레딧을 쓰지 않고 읽기 전용 접근을 확인할 수 있습니다. 이번 테스트의 실시간 응답에는 첫 프레임 입력, 최소 4초, 480p, 아래에서 사용한 adaptive 비율을 지원하는 Seedance 2.0 Fast가 있었습니다.

요청을 하나 만들고 그대로 유지하기

업로드한 file_id는 비공개 계정 데이터이므로 공개 요청에서는 자리표시자로 대체했습니다. 나머지는 성공한 실행과 같습니다.

{
  "input": {
    "first_frame": {
      "type": "file",
      "file_id": "YOUR_COMPLETED_UPLOAD_FILE_ID"
    }
  },
  "prompt": "Static camera. The pixel-art swordswoman faces right and walks in place. Alternate the legs clearly, swing the arms naturally, and let the hair and scarf move slightly. Keep the original character design, pixel-art style, full-body framing, scale, and screen position. Do not move the camera or let the character leave the frame.",
  "video": {
    "model": "volcengine_seedance:doubao-seedance-2-0-fast-260128",
    "duration_seconds": 4,
    "resolution": "480p",
    "ratio": "adaptive",
    "transparency": {
      "mode": "alpha_key",
      "key_selection": "auto"
    }
  },
  "selection": {"mode": "full"},
  "export": {
    "frame_count": 16,
    "output_width": 256,
    "output_height": 256,
    "output_formats": ["spritesheet", "spritesheet_json"],
    "transparent": {"enabled": true}
  }
}

두 투명도 설정이 모두 중요합니다. video.transparency.mode는 영상 단계에서 Alpha Key 워크플로를 사용하도록 요청하고, export.transparent.enabled는 내보내기 단계에서 RGBA 에셋을 요청합니다. 하나를 생략하면 같은 작업을 뜻하지 않습니다.

모델 ID는 이 실행을 기록하기 위해 포함했습니다. 새로운 작업에서는 카탈로그가 그대로라고 가정하지 말고 현재 list_models 호출이 반환한 ID를 사용하세요.

먼저 견적을 확인하고 유료 호출 승인받기

위 요청을 quote_animation에 보냈습니다. 36크레딧 견적이 반환되었으며, 모두 4초 영상 생성 비용이었습니다. 이번 실행에서는 선택한 16프레임 내보내기에 추가 크레딧이 들지 않았습니다.

요청과 금액을 보여준 후에야 사용자가 최대 36크레딧을 승인했습니다. 클라이언트는 견적을 다시 받아 금액이 오르지 않았음을 확인한 다음 아래와 같이 generate_animation을 호출했습니다.

{
  "idempotency_key": "ONE_PERSISTED_LOGICAL_OPERATION_KEY",
  "quote_id": "FRESH_QUOTE_ID",
  "max_credits": 36,
  "request": {"...": "the unchanged request above"}
}

다른 요청에 36을 예산으로 그대로 복사하지 마세요. 사용자가 실제로 검토한 가격을 사용해야 합니다. 작업 생성 전에 요청과 멱등성 키를 저장하세요. 응답이 불확실해지면 새 유료 작업을 조용히 만드는 대신 같은 작업을 복구해야 합니다. MCP 지출 안전장치에서 이 경계를 자세히 설명합니다.

작업을 폴링한 뒤 실제 바이트 다운로드하기

generate_animation은 애니메이션 파일이 아니라 비동기 작업을 반환했습니다. 같은 작업을 video_generation과 animation_export 단계에 걸쳐 폴링하여 succeeded에 도달할 때까지 기다렸습니다. 요청한 두 내보내기 에셋보다 중간 MP4가 먼저 나타났습니다.

각 결과물에 대해 클라이언트는 download_asset을 호출하고, OAuth나 API 자격 증명을 전달하지 않은 채 임시 URL을 사용하여 로컬에 바이트를 저장했습니다. 서명 URL은 글이나 압축 파일에 복사하지 않았습니다.

원본 MP4에는 단색 키 배경이 있습니다. 이는 중간 동작 에셋이지 투명한 최종 결과물이 아닙니다.

투명도는 내보낸 PNG 프레임에서 나타납니다.

움직이는 체크무늬 미리보기를 열어 최종 16프레임을 순서대로 확인하세요.

스프라이트 시트와 JSON을 함께 확인하기

최종 시트는 4 × 4 격자입니다. JSON은 각 셀의 사각형, 원본 크기, 재생 시간을 기록하므로 게임이나 빌드 도구가 이미지에서 레이아웃을 추측할 필요가 없습니다.

파일 검사 결과는 다음과 같았습니다.

• 처음 다운로드한 세 파일의 바이트 수가 MCP 에셋 메타데이터와 일치했습니다.
• 수정된 최종 스프라이트 시트는 809,336바이트였으며 원본 영상의 비율을 유지했습니다.
• PNG는 RGBA였고 모든 프레임에 0부터 255까지의 알파 값이 있었습니다.
• 16개 프레임 이미지는 모두 서로 달랐습니다.
• 검사한 모든 프레임 모서리는 완전히 투명했습니다.
• JSON의 16개 사각형이 1024 × 1024 시트의 256 × 256 셀과 모두 일치했습니다.
• JSON의 총 재생 시간은 4.048초로, 생성 원본 영상과의 차이가 0.01초 이내였습니다.
• 작업은 승인된 36크레딧을 한 번만 차감했으며 보류 잔액이나 유료 재시도가 없었습니다.

이 검사로 전송, 패키징, 명백한 투명도 실패를 잡을 수 있습니다. 최종 판단은 여전히 실제 사용처에서 동작을 보며 내려야 합니다.

시각적 검토로 가로세로 비율 버그를 찾아 수정하기

첫 내보내기는 파일, 알파, 프레임 수, JSON 레이아웃 검사를 통과했지만 여전히 이상해 보였습니다. 캐릭터가 눈에 띄게 넓고 짧았습니다. 원본 영상은 560 × 752인데 내보내기 경로가 각 프레임을 256 × 256으로 직접 늘렸기 때문입니다. 그 결과 높이에 대한 너비가 약 34% 커졌습니다. 기술적으로 유효하더라도 시각적으로 잘못된 결과를 사용하지 않고 해당 시트를 제외했습니다.

최종 샘플을 위해 투명 내보내기 경로를 수정하고, 정확히 같은 다운로드 MP4에 대해 결정론적인 프레임 내보내기만 다시 실행했습니다. 각 샘플 프레임은 이제 비율을 유지한 191 × 256으로 조정된 뒤 256 × 256 투명 캔버스 중앙에 배치됩니다. 왼쪽 여백은 32픽셀, 오른쪽은 33픽셀입니다. 상대 가로세로 비율 오차는 0.2% 미만이며, 보이는 픽셀의 오른쪽 가장자리에는 최소 33픽셀의 공간이 남습니다.

수정된 4 × 4 시트에는 여전히 서로 다른 RGBA 프레임 16개가 있고, 검사한 모서리는 모두 완전히 투명합니다. JSON 셀 레이아웃과 4.048초 재생 시간도 바뀌지 않았습니다. 원본 영상을 재사용했으므로 모델을 두 번째로 호출하지 않았고, 처음 승인한 36크레딧 외에 추가 크레딧도 들지 않았습니다.

AnimGen의 입력 캔버스는 생성 중 캐릭터 자체에 더 많은 공간이 필요할 때 유용합니다. 하지만 이는 창작을 위한 프레이밍 제어이며, 내보내기 과정에서 비율을 유지하는 기능을 대신하지는 않습니다.

샘플을 다운로드하거나 Public API 사용하기

다운로드 가능한 MCP 예제에는 공개 입력 이미지, 실제 운영 작업의 원본 MP4와 JSON 메타데이터, 수정된 최종 스프라이트 시트, 애니메이션 미리보기, 프레임 검사 이미지, README, 민감 정보를 제거한 요청 템플릿이 있습니다. OAuth 토큰, 서명 URL, 계정 소유 ID, 견적 ID, 작업 ID, 멱등성 키는 의도적으로 포함하지 않았습니다.

실제 서비스 구조에 AI 어시스턴트가 없다면 Public API에서도 같은 유형의 워크플로를 사용할 수 있습니다. API 이미지에서 에셋까지 빠른 시작부터 읽어보세요. MCP는 OAuth 도구를 사용하며 승인된 quote_id 또는 max_credits를 적용할 수 있습니다. API는 API 키와 별도로 문서화된 사전 점검 절차를 사용하므로 인증 방식이나 지출 모델을 혼용하지 마세요.

에이전트 기반 워크플로는 전체 MCP 생성 가이드를 따르세요. 먼저 원본 이미지를 만들고 대화형으로 내보내기 결과를 확인하려면 AnimGen Studio를 여세요.