본문으로 건너뛰기

API로 비디오 만들기

이 가이드에서는 Shakr API로 하나의 비디오를 제작하는 예시를 소개합니다.

준비​

템플릿의 매핑 스펙 받아오기​

템플릿에 있는 디자인 요소를 변경하기 위해서, 사용하고 싶은 템플릿의 매핑 스펙을 가져옵니다. 매핑 스펙을 보면 디자이너가 선택한 변경 가능 요소를 알 수 있고, 비디오 제작을 위해 RenderSession 생성 요청을 할 때 사용하는 mapping 객체를 만들 수 있습니다.

이 가이드에서는 간단하지만 재미있는 애니메이션을 보여주는 템플릿인 Skin Company를 기준으로 설명하겠습니다.

curl 'https://api.shakr.com/v2/template_style_versions/TEMPLATE_STYLE_VERSION_ID/specs' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer SERVER_ACCESS_TOKEN'
{
  "style_version": {
    ... // 매핑 스펙
  }
}

매핑 스펙 예시​

예시 템플릿인 Skin Company의 매핑 스펙은 다음과 같습니다.

{
  "style_version": {
    "id": "xQGAFq",
    "editables": {
      "c_01": {
        "input_type": "color",
        "example_text": "EEADA7",
        "stillcut": "stillcut_01",
        "fonts": [
          "Montserrat-Regular"
        ]
      },

      ...

      "t_01": {
        "input_type": "text",
        "example_text": "Skin care",
        "stillcut": "stillcut_01",
        "fonts": [
          "AbrilFatface-Regular"
        ]
      },

      ...

      "(Footage)/USER/logo_01.png": {
        "input_type": "image",
        "width": 550,
        "height": 180,
        "stillcut": "stillcut_01"
      },

      ...

    },
    "fonts": [
      "Montserrat-Regular",
      "AbrilFatface-Regular",
      "Montserrat-Medium"
    ]
  }
}

위 요청에서 반환되는 매핑 스펙 중 가장 주의 깊게 볼 부분은 에디터블(editables) 객체입니다. 이름에서 알 수 있듯이 편집 가능한(edit-able) 사진, 동영상, 텍스트 등의 요소가 포함되어 있고, 각 요소의 종류는 input_type으로 구분할 수 있습니다.

참고 문서​

매핑 내 리소스 채우기​

매핑 스펙을 가져왔다면, 원하는 텍스트나 미디어 파일을 넣어 나만의 매핑을 만들 차례입니다. 예시 템플릿에서는 텍스트와 사진 에디터블이 존재하므로, 두 형태의 에디터블을 지정하는 법에 대해 알아보겠습니다.

텍스트 에디터블​

텍스트 에디터블은 가장 간단한 에디터블로, 영상 내 텍스트를 표시합니다. 텍스트 에디터블은 단 하나, 텍스트의 입력을 사용할 수 있습니다. 만약 t_01 텍스트 에디터블에 My video text 값을 지정하고 싶다면, 다음과 같이 매핑에 추가할 수 있습니다.

{
  "t_01": {
    "source": { "text": "My video text" }
  }
}

이미지 에디터블​

이미지 에디터블은 영상 내 이미지를 표시하며, 제품의 사진이나 브랜드 로고 등 다양한 방식으로 활용됩니다. 이미지 에디터블에는 입력 URL과 이미지 처리 옵션을 지정해주어야 하는데요, 이미지 처리 옵션을 사용하여 이미지의 크기가 어떻게 조절될 지, 자르는 영역은 어떻게 될 지를 지정할 수 있습니다. 자세한 설명은 이미지 에디터블을 참고해주세요.

만약 (Footage)/USER/logo_01.png 이미지 에디터블에 https://via.placeholder.com/1280x720.jpg 이미지를 지정하고, 화면을 꽉 채우도록 자르고 싶다면, 다음과 같이 매핑에 추가할 수 있습니다.

{
  "(Footage)/USER/logo_01.png": {
    "source": {
      "remote_url": "https://via.placeholder.com/1280x720.jpg"
    },
    "transform": {
      "crop_strategy": "cover"
    }
  }
}

이와 같은 방식으로 모든 에디터블을 채워 넣으면 매핑을 완성할 수 있습니다. 비디오나 색상 에디터블을 사용하는 등 매핑에 대한 자세한 설명은 매핑 구조을 참고해주세요.

RenderSession 만들기​

비디오 제작을 위한 모든 정보가 준비되었으니 이제 RenderSession을 만들 수 있습니다. mapping 객체 내에는 이전 단계에서 얻은 template_style_version_id 과 매핑 내 리소스가 포함된 resources 객체가 들어갑니다. 아래는 예시 요청입니다.

curl 'https://api.shakr.com/v2/render_sessions' \
  -X POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer SERVER_ACCESS_TOKEN'
  --data-raw '{
    "title": "My New Video (Using Skin Company template)",
    "render": "preview",
    "mapping": {
      "template_style_version_id": "xQGAFq",
      "resources": {
        "t_01": { "source": { "text": "Skin beauty" } },
        "t_02": { "source": { "text": "delivered" } },
        "t_03": { "source": { "text": "just for you" } },
        "t_04": { "source": { "text": "only at " } },
        "t_05": { "source": { "text": "EXCLUSIVE TRIAL OFFER" } },
        "(Footage)/USER/logo_01.png": {
          "source": { "remote_url": "https://via.placeholder.com/550x180.png" },
          "transform": { "crop_strategy": "cover" }
        },
        "(Footage)/USER/user_02.jpg": {
          "source": { "remote_url": "https://via.placeholder.com/1680x1050.jpg" },
          "transform": { "crop_strategy": "cover" }
        }
      }
    }
  }'
{
  "render_session": {
    "id": "RENDER_SESSION_ID",
    "title": "My New Video (Using Skin Company template)",
    "status": "preview_rendering",
    "render_progress": 0,
    "thumbnails": [],
    "video_url": null,
    "errors": [],
    "created_at": "2030-01-01T07:20:22.527Z",
    "updated_at": "2030-01-01T07:20:22.619Z",
    "mapping": {
      "id": "MAPPING_ID",
      "template_style_version_id": "xQGAFq",
      "resources": {
        "t_01": { "source": { "text": "Skin beauty" } },
        "t_02": { "source": { "text": "delivered" } },
        "t_03": { "source": { "text": "just for you" } },
        "t_04": { "source": { "text": "only at " } },
        "t_05": { "source": { "text": "EXCLUSIVE TRIAL OFFER" } },
        "(Footage)/USER/logo_01.png": {
          "source": { "remote_url": "https://via.placeholder.com/550x180.png" },
          "transform": { "crop_strategy": "cover" }
        },
        "(Footage)/USER/user_02.jpg": {
          "source": { "remote_url": "https://via.placeholder.com/1680x1050.jpg" },
          "transform": { "crop_strategy": "cover" }
        }
      }
    },
    "audio_tracks": {},
    "font_changes": {},
    "source_uploads": [],
    "fonts": []
  }
}

요청이 성공하면, render_session 객체가 정상적으로 반환되는 것을 확인할 수 있습니다.

참고 문서​

완성된 비디오 확인하기​

RenderSession 객체에 있는 status 프로퍼티가 preview_rendered로 바뀌면, 렌더가 완료되었다는 의미입니다. video_url 프로퍼티를 참조하여 완성된 비디오의 URL을 가져올 수 있습니다.

curl 'https://api.shakr.com/v2/render_sessions/RENDER_SESSION_ID' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer SERVER_ACCESS_TOKEN'
{
  "render_session": {
    "id": "<RENDER_SESSION_ID>",
    "title": "My New Video",
    "status": "preview_rendered",
    "render_progress": 100,
    "thumbnails": ["IMAGE_URL"],
    "video_url": "VIDEO_URL",

    ...

  }
}

축하합니다, API로 비디오를 제작하였습니다! 🎉

참고 문서​



API의 추가 기능 활용하기​

  • 폰트 에디터블 등 더 많은 에디터블 종류를 사용할 수 있습니다.
  • Automated Video Delivery를 사용하면, 클라우드 저장소로 자동으로 비디오를 가져올 수 있습니다.
  • Webhook을 사용하면, Automated Video Delivery가 완료된 후 알림을 웹 서버 엔드포인트로 받아볼 수 있습니다.