Text to Motion API

텍스트 설명으로부터 캐릭터 모션 클립을 생성합니다. "손을 흔드는 캐릭터" 또는 "비틀거리며 앞으로 걸어가는 좀비"와 같은 동작을 설명하면 원시 모션 클립을 얻을 수 있습니다. 이 클립은 자신의 파이프라인이나 DCC 도구에서 리깅된 캐릭터에 리타겟팅할 수 있습니다.

출력물은 독립적인 모션 클립입니다. 캐릭터 모델이 필요하지 않으며, 특정 모델에 종속되지도 않습니다. 먼저 캐릭터를 리깅하려면 Rigging API를 참고하세요. 클립을 리깅된 캐릭터에 적용하려면 작업의 id를 motion_task_id로 Animation API에 전달하세요.

POST/openapi/v1/text-to-motion

Text to Motion 작업 생성

텍스트 prompt로부터 모션 클립을 생성하는 Text to Motion 작업을 생성합니다.

작업은 백그라운드에서 실행됩니다. 작업이 일반적으로 소요되는 시간은 처리 시간을 참고하세요.

prime 작업은 10크레딧이 소요되며 Meshy의 더 높은 품질의 모션 모델을 사용합니다. swift 작업은 3크레딧이 소요되며 더 빠르고 저렴한 모션 모델을 사용합니다.

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"
}

매개변수

Name
prompt
Type
string
필수
Description
생성할 모션을 설명하는 텍스트로, 최대 400자까지 입력할 수 있습니다. 더 긴 텍스트는 400을 반환합니다.
Name
mode
Type
string
기본값 prime
Description
모션 모델로, 클립의 파일 형식도 함께 설정됩니다.
사용 가능한 값:
- prime: 더 높은 품질, FBX 클립을 반환
- swift: 더 빠르고 저렴함, BVH 클립을 반환
다른 값을 지정하면 400을 반환합니다.
Name
duration
Type
number
필수
Description
초 단위의 목표 클립 길이로, 2부터 10까지 0.5 단위로 설정할 수 있습니다. 예: 2, 2.5, 3. 다른 값을 지정하면 400을 반환합니다.

반환값

응답의 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 키가 없거나 유효하지 않습니다. Authorization 헤더를 확인하세요.
Name
402 - Payment Required
Description
예를 들면:
- 크레딧 부족: 계정에 이 작업을 수행할 충분한 크레딧이 없거나, 계정이 크레딧 한도에 도달했습니다. 크레딧 잔액을 확인한 후 다시 시도하세요.
- 무료 플랜: 작업을 생성하려면 유료 플랜이 필요합니다. 구독 설정에서 플랜을 업그레이드한 후 다시 시도하세요.
Name
403 - Forbidden
Description
콘텐츠 moderation에서 prompt를 플래그 처리했습니다. prompt를 변경한 후 요청을 다시 보내세요.
Name
429 - Too Many Requests
Description
속도 제한을 초과했습니다. 잠시 기다린 후 다시 시도하세요. 속도 제한을 참고하세요.

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

Get a Text to Motion task

ID로 Text to Motion task를 조회합니다.

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
}

Parameters

Name
id
Type
path
Description
생성 응답에서 받은 task ID입니다.

Returns

Text to Motion task 객체를 반환합니다.

GET/openapi/v1/text-to-motion

Text to Motion 작업 스트리밍

Text to Motion 작업의 업데이트를 서버 전송 이벤트(SSE)로 스트리밍합니다.

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 event, with the same fields as the 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
}

매개변수

Name
id
Type
path
Description
생성 응답에서 제공된 작업 ID입니다.

반환값

Text to Motion 작업 객체의 스트림을 서버 전송 이벤트로 반환합니다.

모든 message 이벤트는 전체 작업 객체를 포함합니다. 작업이 PENDING 또는 IN_PROGRESS 상태인 동안에는 result 필드가 비어 있으며("" 또는 0), finished_at과 expires_at은 0입니다. 작업을 추적하려면 status와 progress를 확인하세요.

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

Text to Motion 작업 삭제

Text to Motion 작업을 모션 클립을 포함하여 영구적으로 삭제합니다. 삭제는 취소할 수 없습니다.

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 on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS. The task keeps running:
{
  "message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}

경로 매개변수

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

작업 상태

PENDING 상태의 작업을 삭제하면 작업을 생성할 때 사용된 크레딧이 환불됩니다.

IN_PROGRESS 상태의 작업은 삭제할 수 없습니다. 이 경우 요청은 409 Conflict를 반환하며, 작업은 계속 실행됩니다. Meshy는 이미 시작된 작업에 대해서는 환불을 제공하지 않으므로, 이를 삭제하면 크레딧과 결과물을 모두 잃게 됩니다. 작업이 SUCCEEDED, FAILED, 또는 CANCELED 상태가 될 때까지 기다린 후 삭제하세요.

최종 상태(SUCCEEDED, FAILED, 또는 CANCELED)인 작업을 삭제해도 크레딧은 환불되지 않습니다.

반환값

작업이 삭제되면 200 OK를 반환하며, 작업이 IN_PROGRESS 상태인 경우 409 Conflict를 반환합니다.

Text to Motion 작업 객체

Text to Motion 작업 객체는 하나의 모션 클립 생성 과정을 나타냅니다. 작업이 성공하면 상태, progress, 클립 정보를 담고 있습니다.

속성

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
}

Name
id
Type
string
Description
작업 ID입니다. 형식에 의존하지 말고 불투명한 문자열로 취급하세요.
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
작업이 생성된 시각으로, 유닉스 밀리초 단위입니다.
Name
started_at
Type
timestamp
Description
작업이 시작된 시각으로, 유닉스 밀리초 단위입니다. 작업이 시작되기 전까지는 0입니다.
Name
finished_at
Type
timestamp
Description
작업이 완료된 시각으로, 유닉스 밀리초 단위입니다. 작업이 완료되기 전까지는 0입니다.
Name
expires_at
Type
timestamp
Description
작업 결과 파일이 만료되는 시각으로, 유닉스 밀리초 단위입니다. 작업이 완료되기 전까지는 0입니다. Meshy는 작업 완료 후 3일 동안 클립을 보관하므로, 그 전에 다운로드해야 합니다.
Name
preceding_tasks
Type
integer
Description
대기열에서 이 작업보다 앞서 있는 작업의 수입니다. 이 값은 작업이 PENDING 상태일 때만 의미가 있습니다. 값이 0일 때는 이 필드가 생략됩니다.
Name
consumed_credits
Type
integer
Description
작업에 사용된 크레딧 수로, prime mode에서는 10, swift mode에서는 3입니다. FAILED 작업의 경우 Meshy가 작업 실패 시 크레딧을 환불하므로 0입니다.
Name
task_error
Type
object
Description
작업이 실패했을 때의 오류 세부 정보이며, 그렇지 않으면 null입니다. 오류를 참고하세요.
Name
result
Type
object
Description
작업이 성공했을 때 생성된 모션 클립입니다. 그 전까지는 필드가 존재하지만 비어 있습니다 ("" 또는 0).
- Name
  motion_url
  Type
  string
  Description
  모션 클립의 다운로드 URL입니다. Meshy는 읽을 때마다 URL에 다시 서명하며, 작업의 보존 기간이 지나면 만료됩니다.
- Name
  motion_format
  Type
  string
  Description
  클립의 파일 형식으로, prime mode에서는 fbx, swift mode에서는 bvh입니다.
- Name
  duration_ms
  Type
  integer
  Description
  클립의 길이로, 밀리초 단위입니다.
- Name
  mode
  Type
  string
  Description
  Meshy가 클립을 생성하는 데 사용한 mode로, prime 또는 swift입니다.

Text to Motion API

Text to Motion 작업 생성

Request

Response

매개변수

반환값

실패 모드

Get a Text to Motion task

Request

Response

Parameters

Returns

Text to Motion 작업 목록 조회

Request

Response

Text to Motion 작업 스트리밍

Request

Response Stream

매개변수

반환값

Text to Motion 작업 삭제

Request

Response

경로 매개변수

작업 상태

반환값

Text to Motion 작업 객체

속성

Example Text to Motion Task Object