공개 API

자신의 코드로 비디오, 이미지 및 음악 생성

키를 생성하고 Bearer 인증과 함께 요청을 보내며 작업이 완료될 때까지 상태를 확인하세요. 동일한 모델, 가격, 요금제 제한 및 환불 정책이 NovaMotions AI 스튜디오와 동일하며, 하나의 공유 크레딧 잔액을 사용합니다.

API 키 받기 빠른 시작

기본 URLhttps://novamotions.com/api/v1

빠른 시작

세 단계로 영상 완성까지. 모든 요청은 JSON을 사용하는 일반 HTTPS이므로 어떤 언어나 도구도 사용 가능합니다.

1
키 생성하기
계정의 API 페이지를 열고 키를 생성하세요. 전체 키는 한 번만 표시되므로 API_KEY라는 환경 변수에 저장하세요.
키 생성하기

작업 제출하기

모델, 프롬프트 및 옵션을 보내세요. 크레딧은 제출 시 한 번 차감되며, 응답에 사용량과 남은 크레딧이 표시됩니다.

curl -X POST https://novamotions.com/api/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-pro",
    "prompt": "비 오는 네온 거리에서 천천히 이동하는 돌리 샷, 젖은 아스팔트에 반사, 영화 같은 분위기",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'

완료될 때까지 상태 확인

몇 초마다 작업 상태를 확인하세요. 상태가 성공이면 output_url에서 파일을 다운로드하세요. 실패하면 크레딧이 이미 잔액으로 환불됩니다.

TASK_ID=your_task_id
while true
do
  TASK=$(curl -s https://novamotions.com/api/v1/tasks/$TASK_ID -H "Authorization: Bearer $API_KEY")
  STATUS=$(echo "$TASK" | jq -r .status)
  echo "$STATUS"
  if [ "$STATUS" = "succeeded" ] || [ "$STATUS" = "failed" ]
  then
    echo "$TASK" | jq
    break
  fi
  sleep 5
done

인증

모든 요청의 Authorization 헤더에 키를 포함하세요. 키는 nm_live_로 시작하며 하나의 계정에 속합니다.

HTTP

Authorization: Bearer nm_live_your_api_key
Content-Type: application/json

기본 URL: 모든 엔드포인트는 https://novamotions.com/api/v1 아래에 있으며 JSON을 반환합니다.
키는 비밀로 유지하세요: API는 서버에서 호출하고 브라우저나 모바일 앱에서는 호출하지 마세요. 키가 취소되면 즉시 작동이 중지됩니다.
하나의 잔액: API 호출은 키 소유자의 크레딧을 사용하며, 스튜디오와 동일한 잔액을 공유합니다. 생성당 요금제 제한도 적용됩니다.
미디어 URL: 전달하는 이미지, 비디오, 오디오는 쿠키나 로그인 없이 로드되는 공개 https URL이어야 합니다.

모델 목록

GET/api/v1/models

API가 제공하는 모든 모델과 모드, 길이, 해상도, 화면비, 오디오 지원, 참조 제한 및 최소 크레딧 가격을 포함합니다. 옵션을 하드코딩하지 않고 모델 선택기를 만들 때 사용하세요.

요청

curl https://novamotions.com/api/v1/models \
  -H "Authorization: Bearer $API_KEY"

응답

JSON

{
  "object": "list",
  "data": [
    {
      "slug": "seedance-2-pro",
      "name": "Seedance 2.0 Pro",
      "kind": "video",
      "endpoint": "/api/v1/videos",
      "available": true,
      "modes": [
        "text-to-video",
        "image-to-video",
        "reference-to-video"
      ],
      "durations": [
        4,
        5,
        6,
        8,
        10,
        12,
        15
      ],
      "default_duration": 5,
      "resolutions": [
        "480p",
        "720p",
        "1080p",
        "4K"
      ],
      "aspect_ratios": [
        "16:9",
        "9:16",
        "1:1",
        "4:3",
        "3:4",
        "21:9"
      ],
      "audio": {
        "supported": true,
        "extra_credits": 20
      },
      "references": {
        "images": 9,
        "videos": 3,
        "audio": 3,
        "end_frame": true
      },
      "max_count": 4,
      "prompt_max_length": 10000,
      "from_credits": 35
    }
  ]
}

잔액 확인

GET/api/v1/balance

키 소유자가 현재 사용할 수 있는 크레딧을 만료일별 풀로 나누어 보여주며, 현재 요금제도 포함됩니다.

요청

curl https://novamotions.com/api/v1/balance \
  -H "Authorization: Bearer $API_KEY"

응답

JSON

{
  "object": "balance",
  "balance": 1175,
  "never_expiring": 375,
  "next_expiry": "2026-11-17T00:00:00.000Z",
  "pools": [
    {
      "source": "subscription",
      "remaining": 800,
      "granted": 2000,
      "expires_at": "2026-11-17T00:00:00.000Z"
    },
    {
      "source": "topup",
      "remaining": 375,
      "granted": 375,
      "expires_at": null
    }
  ],
  "plan": {
    "name": "Pro",
    "status": "active",
    "cycle": "monthly",
    "renews_or_ends_at": "2026-11-14T00:00:00.000Z"
  }
}

비디오 만들기

POST/api/v1/videos

텍스트에서 비디오, 이미지에서 비디오(시작 프레임과 선택적 종료 프레임), 또는 참조 비디오(결과를 안내하는 이미지, 클립, 오디오) 생성. 모드는 입력에서 자동 선택됩니다.

매개변수

modelstring
필수models 엔드포인트에서 받은 모델 슬러그.
promptstring
필수클립에서 일어날 일. 이미지-비디오 모드에서는 시작 프레임이 주도하므로 선택 사항.
modestring
선택text-to-video, image-to-video 또는 reference-to-video. 생략 시 입력에서 자동 선택.
durationinteger
선택클립 길이(초). 모델의 지원 길이 중 하나여야 하며, 아니면 기본값이 사용됩니다.
resolutionstring
선택출력 해상도(예: 720p, 1080p), 모델 목록에서 선택.
aspect_ratiostring
선택모델 목록에서 선택 가능한 16:9, 9:16, 1:1, 4:3, 3:4 또는 21:9. 기본값은 16:9입니다.
audioboolean
선택지원하는 모델에서 대화, 효과 및 분위기가 포함된 사운드트랙을 생성합니다. 20 크레딧이 추가됩니다. 기본값은 false입니다.
image_urlstring (URL)
선택이미지에서 비디오로 변환할 시작 프레임입니다.
end_image_urlstring (URL)
선택지원하는 모델에서 첫 번째와 마지막 프레임으로 사용할 종료 프레임입니다.
reference_image_urlsstring[]
선택참조-비디오용 참조 이미지, 모델 제한까지 허용됩니다.
reference_video_urlsstring[]
선택참조-비디오용 참조 클립, 모델 제한까지 허용됩니다.
reference_audio_urlsstring[]
선택사운드트랙을 안내하는 오디오, 모델 제한까지 허용됩니다.
countinteger
선택같은 요청으로 만들 비디오 수, 1에서 4까지 가능합니다. 각각 별도의 작업이며 별도로 요금이 부과됩니다.
seedinteger
선택재현 가능한 결과를 위한 고정 시드입니다. 배치 내 추가 항목마다 다음 시드를 사용합니다.

요청

curl -X POST https://novamotions.com/api/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-pro",
    "prompt": "비 오는 네온 거리에서 천천히 이동하는 돌리 샷, 젖은 아스팔트에 반사, 영화 같은 분위기",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'

응답

JSON

{
  "tasks": [
    {
      "id": "cmtask8k2x0001ab7c9d0e1f2",
      "status": "queued",
      "credits": 44,
      "url": "https://novamotions.com/api/v1/tasks/cmtask8k2x0001ab7c9d0e1f2"
    }
  ],
  "credits_charged": 44,
  "balance": 1131
}

이미지 만들기

POST/api/v1/images

텍스트에서 이미지 생성 또는 기존 이미지를 프롬프트로 편집. 요청당 최대 4개 이미지 생성 가능하며 각각 별도 작업입니다.

매개변수

modelstring
필수models 엔드포인트에서 받은 모델 슬러그.
promptstring
필수이미지가 보여야 할 내용 또는 전달한 이미지를 변경하는 방법입니다.
modestring
선택텍스트-이미지 또는 이미지 편집. 생략 시 입력에서 선택됩니다.
resolutionstring
선택모델 목록에서 선택 가능한 1K, 2K 또는 4K 해상도입니다.
aspect_ratiostring
선택모델 목록에서 선택 가능한 종횡비이며, 지원하는 모델에서는 자동도 포함됩니다.
image_urlstring (URL)
선택편집할 이미지입니다. 이미지 편집 시 필수입니다.
reference_image_urlsstring[]
선택편집용 추가 참조 이미지, 모델 제한까지 허용됩니다.
countinteger
선택프롬프트당 이미지 수, 1에서 4까지 가능합니다. 각각 별도의 작업입니다.
seedinteger
선택재현 가능한 결과를 위한 고정 시드입니다. 배치 내 추가 항목마다 다음 시드를 사용합니다.

요청

curl -X POST https://novamotions.com/api/v1/images \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "참나무 위 세라믹 커피잔 스튜디오 제품 사진, 부드러운 창가 빛, 얕은 피사계 심도",
    "resolution": "1K",
    "aspect_ratio": "1:1",
    "count": 1
  }'

응답

JSON

{
  "tasks": [
    {
      "id": "cmtask8k2x0001ab7c9d0e1f2",
      "status": "queued",
      "credits": 3,
      "url": "https://novamotions.com/api/v1/tasks/cmtask8k2x0001ab7c9d0e1f2"
    }
  ],
  "credits_charged": 3,
  "balance": 1172
}

노래 만들기

POST/api/v1/music

설명으로 완성된 노래 생성, 직접 작성한 가사 포함 또는 연주곡으로 생성 가능.

매개변수

modelstring
필수models 엔드포인트에서 받은 모델 슬러그.
promptstring
필수노래의 장르, 분위기, 악기 및 템포입니다.
durationinteger
선택모델에서 지원하는 노래 길이(초)입니다.
lyricsstring
선택직접 작성한 가사입니다. 생략하면 모델이 작성합니다.
instrumentalboolean
선택보컬 없는 노래를 만듭니다. 기본값은 false입니다.

요청

curl -X POST https://novamotions.com/api/v1/music \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ai-music",
    "prompt": "따뜻한 로파이 힙합, 부드러운 피아노, 비닐 잡음, 편안한 심야 그루브",
    "duration": 60,
    "instrumental": false
  }'

응답

JSON

{
  "tasks": [
    {
      "id": "cmtask8k2x0001ab7c9d0e1f2",
      "status": "queued",
      "credits": 11,
      "url": "https://novamotions.com/api/v1/tasks/cmtask8k2x0001ab7c9d0e1f2"
    }
  ],
  "credits_charged": 11,
  "balance": 1164
}

작업 조회

GET/api/v1/tasks/{id}

작업 ID로 상태를 확인하세요. 상태가 성공이면 output_url이 완성된 파일을 가리킵니다. 상태 확인은 읽기 제한을 사용하므로 제출 예산을 소모하지 않습니다.

요청

curl https://novamotions.com/api/v1/tasks/cmtask8k2x0001ab7c9d0e1f2 \
  -H "Authorization: Bearer $API_KEY"

응답

JSON

{
  "id": "cmtask8k2x0001ab7c9d0e1f2",
  "object": "task",
  "kind": "video",
  "model": "seedance-2-pro",
  "mode": "text-to-video",
  "status": "succeeded",
  "progress": 100,
  "prompt": "비 오는 네온 거리에서 천천히 이동하는 돌리 샷, 젖은 아스팔트에 반사, 영화 같은 분위기",
  "params": {
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "audio": false,
    "seed": null
  },
  "output_url": "https://novamotions.com/uploads/videos/2026/10/example.mp4",
  "thumbnail_url": "https://novamotions.com/uploads/videos/2026/10/example.jpg",
  "width": 1280,
  "height": 720,
  "duration_seconds": 5,
  "credits": 44,
  "refunded": false,
  "error": null,
  "created_at": "2026-10-18T09:30:00.000Z",
  "completed_at": "2026-10-18T09:31:12.000Z"
}

작업 목록

GET/api/v1/tasks

최근 30일간 API로 생성한 작업을 최신순으로 보여줍니다. 단일 작업과 같은 형식이며, 다음 페이지를 불러오려면 next_cursor를 cursor로 전달하세요.

매개변수

limitinteger
선택페이지당 결과 수, 1에서 50까지 가능합니다. 기본값은 20입니다.
cursorstring
선택이전 페이지의 next_cursor 값입니다.
statusstring
선택이 상태인 작업만 표시: 대기 중, 실행 중, 성공 또는 실패.

요청

curl https://novamotions.com/api/v1/tasks?limit=20 \
  -H "Authorization: Bearer $API_KEY"

응답

JSON

{
  "object": "list",
  "data": [
    {
      "id": "cmtask8k2x0001ab7c9d0e1f2",
      "object": "task",
      "kind": "video",
      "model": "seedance-2-pro",
      "mode": "text-to-video",
      "status": "succeeded",
      "progress": 100,
      "prompt": "비 오는 네온 거리에서 천천히 이동하는 돌리 샷, 젖은 아스팔트에 반사, 영화 같은 분위기",
      "params": {
        "duration": 5,
        "resolution": "720p",
        "aspect_ratio": "16:9",
        "audio": false,
        "seed": null
      },
      "output_url": "https://novamotions.com/uploads/videos/2026/10/example.mp4",
      "thumbnail_url": "https://novamotions.com/uploads/videos/2026/10/example.jpg",
      "width": 1280,
      "height": 720,
      "duration_seconds": 5,
      "credits": 44,
      "refunded": false,
      "error": null,
      "created_at": "2026-10-18T09:30:00.000Z",
      "completed_at": "2026-10-18T09:31:12.000Z"
    }
  ],
  "next_cursor": null
}

작업 상태

작업은 대기 중에서 실행 중으로 이동하며 성공 또는 실패로 종료됩니다. 종료 상태에서는 폴링을 중지하세요.

queued: 수락되어 렌더링 슬롯을 기다리는 중입니다. 계속 폴링하세요.
running: 현재 렌더링 중입니다. 진행률은 0에서 99까지 변합니다.
succeeded: 완료되었습니다. output_url과 thumbnail_url이 완성된 파일을 가리킵니다.
failed: 결과 없이 종료되었습니다. error가 이유를 설명하며 refunded가 true이면 크레딧이 잔액으로 환불됩니다.

오류 코드

모든 오류는 동일한 형식을 가집니다. 코드를 기준으로 분기하여 사용자에게 메시지를 표시하세요. 수락된 작업도 나중에 실패할 수 있으니 폴링 시 상태를 확인하세요.

오류 응답

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits for this request. Top up or renew your plan, then retry.",
    "needed": 44,
    "balance": 14
  }
}

HTTP 상태코드의미

400invalid_json본문이 JSON 객체가 아닙니다.
401unauthorizedAuthorization 헤더에 Bearer 키가 없습니다.
401invalid_api_key키가 존재하지 않거나 형식이 잘못되었습니다.
401key_revoked키가 취소되었습니다. 새 키를 생성하세요.
402insufficient_credits이 요청에 충분한 크레딧이 없습니다. 응답에 필요 크레딧과 잔액이 포함됩니다.
403plan_limit_exceeded요청이 플랜의 세대별 한도를 초과했습니다. 길이나 해상도를 낮추세요.
403account_suspended키 소유 계정이 정지되었습니다.
403api_disabledAPI가 현재 비활성화되어 있습니다.
404not_found작업 또는 엔드포인트가 이 계정에 존재하지 않습니다.
404model_not_found해당 슬러그의 모델이 없습니다. 모델 엔드포인트를 확인하세요.
409too_many_running이 계정에는 이미 3개의 작업이 실행 중입니다. 하나가 완료될 때까지 기다리세요.
422invalid_request필드가 누락되었거나 유형이 잘못되었습니다. details에 각 문제를 나열합니다.
422wrong_endpoint모델이 다른 엔드포인트에 속해 있습니다. 예: 이미지 모델을 비디오에 보낸 경우.
422invalid_mode이 엔드포인트에서 알지 못하는 모드입니다.
422mode_not_supported모델이 이 모드를 지원하지 않습니다.
422prompt_required이 모드에는 프롬프트가 필요합니다.
422image_required이 모드에는 image_url이 필요합니다.
429rate_limited요청이 너무 많습니다. Retry-After에 명시된 초만큼 기다린 후 다시 시도하세요.
500internal_error서버 측 오류가 발생했습니다. 잠시 후 다시 시도하세요.
503service_busy현재 용량이 가득 찼습니다. 몇 분 후 다시 시도하세요.

크레딧 및 환불

제출 시 1회 청구

각 작업은 스튜디오에서 동일한 설정으로 작업할 때와 동일한 비용이 듭니다. 제출 응답에 credits_charged와 새 잔액이 반환됩니다. 비디오에 오디오를 추가하면 20 크레딧이 추가됩니다.

실패한 작업은 전액 환불

작업이 어떤 이유로 실패하면 해당 작업에 사용된 모든 크레딧이 원래 풀로 돌아가며 작업에 refunded가 true로 표시됩니다. 별도로 청구할 필요가 없습니다.

플랜 한도 적용

플랜의 세대별 한도는 API 작업에도 적용됩니다. 만료가 가장 임박한 크레딧부터 먼저 사용되며, 충전 크레딧은 나중에 사용됩니다.

요청 제한

제한은 1분 단위로 키별로 계산됩니다. 제한을 초과하면 HTTP 429와 Retry-After 헤더(초 단위)를 받습니다. 모든 응답에는 X-RateLimit 헤더가 포함되어 있어 제한 전에 속도를 조절할 수 있습니다.

제출: 분당 30회; 비디오, 이미지 및 노래 생성.
조회: 분당 120회; 작업, 잔액 및 모델. 제출과 별도로 계산됩니다.
동시 실행 중: 3; 계정별로 동시에 렌더링 중인 작업 수.

요청 제한 헤더

HTTP/1.1 429 Too Many Requests
Retry-After: 42
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 42

모델

오늘 호출할 수 있는 모델과 해당 슬러그 및 최저 가격입니다. 모델 엔드포인트는 모든 옵션과 함께 동일한 목록을 반환합니다.

모델Slug유형시작가

Seedance 2.5seedance-2-5비디오45 크레딧
Seedance 2.0 Proseedance-2-pro비디오35 크레딧
Seedance 2.0 Miniseedance-2-mini비디오24 크레딧
Wan 3.0wan-3비디오46 크레딧
MiniMax H3minimax-h3비디오30 크레딧
Kling 3kling-3비디오30 크레딧
Seedance 1.5 Proseedance-1-5-pro비디오31 크레딧
Seedance 1.0seedance-1비디오32 크레딧
Kling O3kling-o3비디오46 크레딧
Kling 2.6kling-2-6비디오41 크레딧
Wan 2.7wan-2-7비디오35 크레딧
Wanwan비디오32 크레딧
Grokgrok-video비디오47 크레딧
Veo 3veo-3비디오42 크레딧
GPT Image 2.5gpt-image-2-5이미지4 크레딧
GPT Image 2gpt-image-2이미지3 크레딧
Seedream 5 Proseedream-5-pro이미지4 크레딧
Seedream 5seedream-5이미지3 크레딧
Nano Banana Pronano-banana-pro이미지5 크레딧
Nano Banana 2nano-banana-2이미지3 크레딧
Nano Banana 2 Litenano-banana-2-lite이미지2 크레딧
AI Musicai-music음악6 크레딧

시작할 준비가 되셨나요?

계정에서 키를 생성하고 1분 안에 첫 요청을 보내보세요.

API 키 생성

자신의 코드로 비디오, 이미지 및 음악 생성

빠른 시작

키 생성하기

작업 제출하기

완료될 때까지 상태 확인

인증

모델 목록

요청

응답

잔액 확인

요청

응답

비디오 만들기

매개변수

요청

응답

이미지 만들기

매개변수

요청

응답

노래 만들기

매개변수

요청

응답

작업 조회

요청

응답

작업 목록

매개변수

요청

응답

작업 상태

오류 코드

크레딧 및 환불

제출 시 1회 청구

실패한 작업은 전액 환불

플랜 한도 적용

요청 제한

모델

시작할 준비가 되셨나요?