텍스트 모션 API

자연어 설명에서 캐릭터 모션 클립을 생성합니다. "캐릭터가 손을 흔든다", "좀비가 앞으로 비틀거리며 나아간다"와 같은 동작을 설명하고, 자신의 파이프라인이나 DCC 도구에서 리깅된 캐릭터에 재적용할 수 있는 원본 모션 클립을 받으세요.

출력물은 독립적인 모션 클립이며, 캐릭터 모델을 요구하거나 붙지 않습니다. 캐릭터를 먼저 리깅하려면, 리깅 API를 참조하세요.

POST/openapi/v1/text-to-motion

텍스트를 모션으로 변환 작업 생성

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

mode가 prime인 작업은 10 크레딧이 필요하며, 가장 높은 품질의 모션 모델로 생성됩니다. mode가 swift인 작업은 3 크레딧이 필요하며, 경제적인 모션 모델로 빠르게 생성됩니다.

매개변수

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

반환값

응답의 result 속성에는 새로 생성된 텍스트를 모션으로 변환하는 작업의 id가 포함되어 있습니다.

실패 모드

Name
400 - Bad Request
Description
요청이 수용 가능하지 않습니다. 일반적인 원인:
- 프롬프트 누락 또는 비어 있음: prompt가 누락되었거나 비어 있거나 400자를 초과합니다.
- 유효하지 않은 모드: mode가 prime 또는 swift가 아닙니다.
- 유효하지 않은 지속 시간: duration이 누락되었거나 2–10범위를 벗어나거나 0.5초 단위로 지정되지 않았습니다.
Name
401 - Unauthorized
Description
인증에 실패했습니다. API 키를 확인하세요.
Name
402 - Payment Required
Description
이 작업을 수행할 크레딧이 부족합니다.
Name
403 - Forbidden
Description
prompt가 content moderation에 의해 플래그되었습니다.
Name
429 - Too Many Requests
Description
속도 제한을 초과하였습니다.

Request

POST

/openapi/v1/text-to-motion

# 필수 매개변수로만 모션 클립 생성
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
  }'

# Swift 모드로 빠르고 경제적인 클립 생성
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

텍스트 to 모션 작업 가져오기

이 엔드포인트는 유효한 작업 id를 제공받아 텍스트 to 모션 작업을 가져올 수 있게 합니다. 포함된 속성을 보려면 텍스트 to 모션 작업 객체를 참조하세요.

매개변수

Name
id
Type
path
Description
가져올 텍스트 to 모션 작업에 대한 고유 식별자.

반환값

응답은 텍스트 to 모션 작업 객체를 포함합니다. 자세한 내용은 텍스트 to 모션 작업 객체 섹션을 확인하세요.

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

텍스트로 모션 작업 목록

호출자의 텍스트를 모션으로 변환하는 작업을 페이지네이션된 목록으로 반환하며, 최신 항목이 먼저 표시됩니다. 표준 페이지네이션은 page_num과 page_size를 통해 이루어집니다.

응답은 텍스트로 모션 변환 작업 객체의 배열입니다.

API를 통해 생성된 작업은 API를 통해 관리되며, 웹 앱의 내 자산에 나타나지 않습니다. 이 엔드포인트를 사용하여 더 이상 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

텍스트를 모션으로 변환하는 작업 스트리밍

이 엔드포인트는 Server-Sent Events (SSE)를 사용하여 텍스트를 모션으로 변환하는 작업에 대한 실시간 업데이트를 스트리밍합니다.

매개변수

Name
id
Type
path
Description
스트리밍할 텍스트를 모션으로 변환하는 작업의 고유 식별자입니다.

반환

Server-Sent Events로 텍스트를 모션으로 변환하는 작업 객체의 스트림을 반환합니다.

작업이 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

// 오류 이벤트 예제
event: error
data: {
  "status_code": 404,
  "message": "작업을 찾을 수 없습니다."
}

// 메시지 이벤트는 모든 단계에서 전체 작업 객체를 나릅니다; 결과
// 필드는 작업이 성공할 때까지 비어 있습니다.
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: { // SUCCEEDED 작업 스트림 항목의 예제, 텍스트를 모션으로 변환하는 작업 객체 구조와 유사
  "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

텍스트에서 모션으로 작업 삭제

이 엔드포인트는 생성된 모션 클립을 포함해 텍스트에서 모션으로 작업을 영구적으로 삭제합니다. 이 작업은 되돌릴 수 없습니다.

경로 매개변수

Name
id
Type
path
Description
삭제할 텍스트에서 모션으로 작업의 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

// 성공 시 200 Ok를 반환합니다.

텍스트에서 모션으로 변환 작업 오브젝트

텍스트 prompt로부터 모션 클립을 생성하기 위한 작업 단위를 나타냅니다.

속성

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
작업의 진행도입니다 (0-100).
Name
created_at
Type
timestamp
Description
작업이 생성된 시점의 타임스탬프 (epoch 밀리초 기준)입니다.
타임스탬프는 1970년 1월 1일 UTC 이후 경과된 밀리초 수를 나타내며, RFC 3339 표준을 따릅니다. 예를 들어, 2023년 9월 1일 금요일 12:00:00 PM GMT는 1693569600000으로 표현됩니다. 이는 Meshy API의 모든 타임스탬프에 적용됩니다.
Name
started_at
Type
timestamp
Description
작업이 처리 시작된 시점의 타임스탬프 (epoch 밀리초 기준)입니다. 시작되지 않은 경우 0입니다.
Name
finished_at
Type
timestamp
Description
작업이 완료된 시점의 타임스탬프 (epoch 밀리초 기준)입니다. 완료되지 않은 경우 0입니다.
Name
expires_at
Type
timestamp
Description
작업 결과 asset가 만료되는 시점의 타임스탬프 (epoch 밀리초 기준)입니다. 작업이 완료될 때까지는 0입니다. 생성된 클립은 작업 완료 후 3일 동안 유지되며, 만료되기 전에 다운로드하십시오.
Name
preceding_tasks
Type
integer
Description
대기열에 있는 앞선 작업의 수입니다. 상태가 PENDING인 경우에만 의미가 있으며, 0일 경우 생략됩니다.
Name
consumed_credits
Type
integer
Description
이 작업으로 소모된 크레딧의 수입니다. prime mode의 경우 10, swift mode의 경우 3입니다. 실패한 작업의 경우 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
}