meshy-5는 2026. 10. 10.에 지원 종료됩니다. lowpoly는 2026. 10. 30.에 지원 종료됩니다. 요청 오류를 피하려면 해당 날짜 전에 모델을 전환하세요.

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 작업 삭제

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

경로 매개변수

  • Name
    id
    Type
    path
    Description

    삭제할 Text to Motion 작업의 ID입니다.

작업 상태

아직 PENDING 상태인 작업은 삭제되며, 생성 시점에 소모된 크레딧은 환불됩니다.

이미 IN_PROGRESS 상태인 작업은 삭제할 수 없습니다. 요청은 409 Conflict로 거부되며 작업은 계속 실행됩니다. 워커가 이미 시작한 작업에 대한 크레딧은 환불이 불가능하므로, 실행 중에 삭제하면 크레딧과 결과물을 모두 잃게 됩니다. SUCCEEDED, FAILED 또는 CANCELED 상태에 도달할 때까지 기다린 후 삭제하세요.

최종 상태(SUCCEEDED, FAILED 또는 CANCELED)의 작업은 환불 없이 삭제됩니다.

반환 값

성공 시 200 OK를 반환하며, 작업이 IN_PROGRESS 상태인 경우 409 Conflict를 반환합니다.

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 is left 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."
}

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
}