Text to Motion API

자연어 설명으로부터 캐릭터 모션 클립을 생성합니다. "손을 흔드는 캐릭터", "비틀거리며 앞으로 걸어가는 좀비"처럼 동작을 설명하면, 자신만의 파이프라인이나 DCC 툴에서 리깅된 캐릭터에 리타겟팅할 수 있는 원본 모션 클립을 받을 수 있습니다.

출력물은 독립적인 모션 클립이며, 캐릭터 모델을 필요로 하지 않고 캐릭터 모델에 연결되지도 않습니다. 먼저 캐릭터를 리깅하려면 Rigging API를 참조하세요. 생성된 클립을 리깅된 캐릭터에 적용하려면 작업 id를 motion_task_id로 Animation API에 전달하세요 — 3일간의 에셋 보존 기간 내에 적용해야 합니다.

POST/openapi/v1/text-to-motion

Text to Motion 작업 생성하기

이 엔드포인트는 텍스트 prompt로부터 모션 클립을 생성하는 새로운 작업을 생성합니다.

mode가 prime인 작업은 10크레딧이 소요되며 최고 품질의 모션 모델로 생성됩니다. mode가 swift인 작업은 3크레딧이 소요되며 경제적인 모션 모델로 더 빠르게 생성됩니다.

매개변수

Name
prompt
Type
string
필수
Description
생성할 모션에 대한 자연어 설명입니다. 최대 400자까지 가능합니다.
Name
mode
Type
string
기본값 prime
Description
모션 생성 mode입니다. 사용 가능한 값: prime, swift. prime은 최고 품질을 생성하며 FBX를 출력하고, swift는 더 빠르고 저렴하며 BVH를 출력합니다.
Name
duration
Type
number
필수
Description
생성할 모션 클립의 목표 길이(초)입니다. 2에서 10 사이의 값이며, 0.5 단위로 지정할 수 있습니다(예: 2, 2.5, 3, … 10).

반환 값

응답의 result 속성에는 새로 생성된 Text to Motion 작업의 작업 id가 포함됩니다.

실패 모드

Name
400 - Bad Request
Description
요청이 허용되지 않았습니다. 일반적인 원인:
- prompt 누락 또는 빈 값: prompt가 누락되었거나, 비어 있거나, 400자를 초과합니다.
- 잘못된 mode: mode가 prime 또는 swift가 아닙니다.
- 잘못된 duration: duration이 누락되었거나, 2~10 범위를 벗어나거나, 0.5초 단위가 아닙니다.
Name
401 - Unauthorized
Description
인증에 실패했습니다. API 키를 확인해 주세요.
Name
402 - Payment Required
Description
이 작업을 수행하기에 크레딧이 부족합니다.
Name
403 - Forbidden
Description
prompt가 콘텐츠 moderation에 의해 플래그 처리되었습니다.
Name
429 - Too Many Requests
Description
속도 제한을 초과했습니다.

Request

POST

/openapi/v1/text-to-motion

# Generate a motion clip with required params only
curl https://api.meshy.ai/openapi/v1/text-to-motion \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "a character waving",
    "duration": 3
  }'

# Generate a fast, economical clip with Swift mode
curl https://api.meshy.ai/openapi/v1/text-to-motion \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "a character waving",
    "mode": "swift",
    "duration": 4.5
  }'

Response

{
  "result": "018c425b-b2c6-727e-d333-3c1887i9h791"
}

GET/openapi/v1/text-to-motion/:id

텍스트 투 모션 작업 조회

이 엔드포인트를 사용하면 유효한 작업 id를 통해 텍스트 투 모션 작업을 조회할 수 있습니다. 어떤 속성이 포함되는지는 텍스트 투 모션 작업 객체를 참고하세요.

매개변수

Name
id
Type
path
Description
조회할 텍스트 투 모션 작업의 고유 식별자입니다.

반환 값

응답에는 텍스트 투 모션 작업 객체가 포함됩니다. 자세한 내용은 텍스트 투 모션 작업 객체 섹션을 확인하세요.

Request

GET

/openapi/v1/text-to-motion/018c425b-b2c6-727e-d333-3c1887i9h791

curl https://api.meshy.ai/openapi/v1/text-to-motion/018c425b-b2c6-727e-d333-3c1887i9h791 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "text-to-motion",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1787314497437,
  "started_at": 1787314498012,
  "finished_at": 1787314505881,
  "expires_at": 1787573705881,
  "task_error": null,
  "result": {
    "motion_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/clip.fbx?Expires=...",
    "motion_format": "fbx",
    "duration_ms": 3000,
    "mode": "prime"
  },
  "consumed_credits": 10
}

GET/openapi/v1/text-to-motion

Text to Motion 작업 목록 조회

호출자의 Text to Motion 작업을 최신순으로 페이지네이션하여 반환합니다. page_num과 page_size를 사용한 표준 페이지네이션이 적용됩니다.

응답은 Text to Motion Task 객체의 배열입니다.

API를 통해 생성된 작업은 API를 통해서만 관리되며, 웹 앱의 My Assets에는 표시되지 않습니다. ID를 더 이상 가지고 있지 않은 작업을 찾으려면 이 엔드포인트를 사용하세요.

Request

GET

/openapi/v1/text-to-motion

curl "https://api.meshy.ai/openapi/v1/text-to-motion?page_num=1&page_size=20" \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
    "type": "text-to-motion",
    "status": "SUCCEEDED",
    "...": "..."
  }
]

GET/openapi/v1/text-to-motion/:id/stream

Text to Motion 작업 스트리밍

이 엔드포인트는 Server-Sent Events(SSE)를 사용하여 Text to Motion 작업의 실시간 업데이트를 스트리밍합니다.

매개변수

Name
id
Type
path
Description
스트리밍할 Text to Motion 작업의 고유 식별자입니다.

반환값

The Text to Motion Task Objects의 스트림을 Server-Sent Events로 반환합니다.

모든 message 이벤트는 전체 작업 객체를 담고 있습니다. 작업이 PENDING 또는 IN_PROGRESS 상태인 동안에는 result 필드가 여전히 비어 있으며("" / 0), finished_at / expires_at는 0입니다. status와 progress를 주시하세요.

Request

GET

/openapi/v1/text-to-motion/018c425b-b2c6-727e-d333-3c1887i9h791/stream

curl -N https://api.meshy.ai/openapi/v1/text-to-motion/018c425b-b2c6-727e-d333-3c1887i9h791/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message events carry the full task object at every stage; the result
// fields stay empty until the task succeeds.
event: message
data: {
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "text-to-motion",
  "status": "IN_PROGRESS",
  "progress": 50,
  "created_at": 1787314497437,
  "started_at": 1787314498012,
  "finished_at": 0,
  "expires_at": 0,
  "task_error": null,
  "result": {
    "motion_url": "",
    "motion_format": "",
    "duration_ms": 0,
    "mode": ""
  },
  "consumed_credits": 10
}

event: message
data: { // Example of a SUCCEEDED task stream item, mirroring The Text to Motion Task Object structure
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "text-to-motion",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1787314497437,
  "started_at": 1787314498012,
  "finished_at": 1787314505881,
  "expires_at": 1787573705881,
  "task_error": null,
  "result": {
    "motion_url": "https://assets.meshy.ai/.../output/clip.fbx?Expires=...",
    "motion_format": "fbx",
    "duration_ms": 3000,
    "mode": "prime"
  },
  "consumed_credits": 10
}

DELETE/openapi/v1/text-to-motion/:id

텍스트 투 모션 작업 삭제

이 엔드포인트는 생성된 모션 클립을 포함하여 Text to Motion 작업을 영구적으로 삭제합니다. 이 작업은 되돌릴 수 없습니다.

경로 매개변수

Name
id
Type
path
Description
삭제할 Text to Motion 작업의 ID입니다.

반환값

성공 시 200 OK를 반환합니다.

Request

DELETE

/openapi/v1/text-to-motion/018c425b-b2c6-727e-d333-3c1887i9h791

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/text-to-motion/018c425b-b2c6-727e-d333-3c1887i9h791 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 200 Ok on success.

The Text to Motion Task Object

Text to Motion Task 객체는 텍스트 prompt로부터 모션 클립을 생성하는 작업 단위를 나타냅니다.

Properties

Name
id
Type
string
Description
작업의 고유 식별자입니다.
Name
type
Type
string
Description
작업의 유형입니다. 값은 text-to-motion입니다.
Name
status
Type
string
Description
작업의 상태입니다. 가능한 값: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
작업의 progress(0-100)입니다.
Name
created_at
Type
timestamp
Description
작업이 생성된 타임스탬프(에포크 이후 밀리초)입니다.
타임스탬프는 RFC 3339 표준을 따라 1970년 1월 1일 UTC 이후 경과한 밀리초 수를 나타냅니다. 예를 들어, 2023년 9월 1일 금요일 12:00:00 PM GMT는 1693569600000으로 표현됩니다. 이는 Meshy API의 모든 타임스탬프에 적용됩니다.
Name
started_at
Type
timestamp
Description
작업이 처리를 시작한 타임스탬프(에포크 이후 밀리초)입니다. 시작되지 않은 경우 0입니다.
Name
finished_at
Type
timestamp
Description
작업이 완료된 타임스탬프(에포크 이후 밀리초)입니다. 완료되지 않은 경우 0입니다.
Name
expires_at
Type
timestamp
Description
작업 결과 에셋이 만료되는 타임스탬프(에포크 이후 밀리초)입니다. 작업이 완료되기 전까지는 0입니다. 생성된 클립은 작업 완료 후 3일 동안 보관되므로, 만료되기 전에 다운로드하세요.
Name
preceding_tasks
Type
integer
Description
대기열에서 앞서 있는 작업의 수입니다. status가 PENDING인 경우에만 의미가 있으며, 0인 경우에는 생략됩니다.
Name
consumed_credits
Type
integer
Description
이 작업에서 소비된 크레딧 수입니다. prime mode의 경우 10, swift mode의 경우 3입니다. FAILED 작업의 경우 0을 반환합니다(실패 시 크레딧은 환불됩니다).
Name
task_error
Type
object
Description
실패한 작업에 대한 오류 세부 정보입니다. 작업이 FAILED가 아닌 경우 null입니다. 전체 task_error 객체 참조는 오류를 참고하세요.
Name
result
Type
object
Description
작업이 SUCCEEDED되면 생성된 모션 클립을 포함합니다. 그 전까지 필드는 존재하지만 비어 있습니다("" / 0).
- Name
  motion_url
  Type
  string
  Description
  생성된 모션 클립의 다운로드 가능한 URL입니다. 이 URL은 읽을 때마다 재서명되며 작업의 보관 기간이 끝나면 만료됩니다.
- Name
  motion_format
  Type
  string
  Description
  클립의 파일 형식입니다: prime mode의 경우 fbx, swift mode의 경우 bvh입니다.
- Name
  duration_ms
  Type
  integer
  Description
  생성된 클립의 재생 시간(밀리초)입니다.
- Name
  mode
  Type
  string
  Description
  클립이 생성된 mode입니다: prime 또는 swift.

Example Text to Motion Task Object

{
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "text-to-motion",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1787314497437,
  "started_at": 1787314498012,
  "finished_at": 1787314505881,
  "expires_at": 1787573705881,
  "task_error": null,
  "result": {
    "motion_url": "https://assets.meshy.ai/.../output/clip.fbx?Expires=...",
    "motion_format": "fbx",
    "duration_ms": 3000,
    "mode": "prime"
  },
  "consumed_credits": 10
}