curl --request POST \
--url https://api.apimart.ai/v1/videos/generations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Idempotency-Key: <unique-operation-key>' \
--data '{
"model": "muse-video-ext",
"prompt": "Waves gently wash a beach at sunset, slow camera pan, natural ocean sounds, no text",
"aspect_ratio": "16:9",
"duration": 10,
"resolution": "720p"
}'
import requests
response = requests.post(
"https://api.apimart.ai/v1/videos/generations",
headers={
"Authorization": "Bearer <token>",
"Accept": "application/json",
"Idempotency-Key": "<unique-operation-key>"
},
json={
"model": "muse-video-ext",
"prompt": "Waves gently wash a beach at sunset, slow camera pan, natural ocean sounds, no text",
"aspect_ratio": "16:9",
"duration": 10,
"resolution": "720p"
}
)
response.raise_for_status()
print(response.json())
const response = await fetch("https://api.apimart.ai/v1/videos/generations", {
method: "POST",
headers: {
Authorization: "Bearer <token>",
"Content-Type": "application/json",
Accept: "application/json",
"Idempotency-Key": "<unique-operation-key>"
},
body: JSON.stringify({
"model": "muse-video-ext",
"prompt": "Waves gently wash a beach at sunset, slow camera pan, natural ocean sounds, no text",
"aspect_ratio": "16:9",
"duration": 10,
"resolution": "720p"
})
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01K..."
}
]
}
Muse Video Ext
Muse Video Ext 동영상 생성
텍스트 또는 최대 9장의 참조 이미지로 약 10초, 720p, 사운드가 포함된 MP4 동영상 1개를 생성합니다.
POST
/
v1
/
videos
/
generations
curl --request POST \
--url https://api.apimart.ai/v1/videos/generations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Idempotency-Key: <unique-operation-key>' \
--data '{
"model": "muse-video-ext",
"prompt": "Waves gently wash a beach at sunset, slow camera pan, natural ocean sounds, no text",
"aspect_ratio": "16:9",
"duration": 10,
"resolution": "720p"
}'
import requests
response = requests.post(
"https://api.apimart.ai/v1/videos/generations",
headers={
"Authorization": "Bearer <token>",
"Accept": "application/json",
"Idempotency-Key": "<unique-operation-key>"
},
json={
"model": "muse-video-ext",
"prompt": "Waves gently wash a beach at sunset, slow camera pan, natural ocean sounds, no text",
"aspect_ratio": "16:9",
"duration": 10,
"resolution": "720p"
}
)
response.raise_for_status()
print(response.json())
const response = await fetch("https://api.apimart.ai/v1/videos/generations", {
method: "POST",
headers: {
Authorization: "Bearer <token>",
"Content-Type": "application/json",
Accept: "application/json",
"Idempotency-Key": "<unique-operation-key>"
},
body: JSON.stringify({
"model": "muse-video-ext",
"prompt": "Waves gently wash a beach at sunset, slow camera pan, natural ocean sounds, no text",
"aspect_ratio": "16:9",
"duration": 10,
"resolution": "720p"
})
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01K..."
}
]
}
이 API는 비동기로 처리됩니다. 제출 후 작업 ID를 저장하고
GET /v1/tasks/{task_id}로 상태와 결과를 조회하세요. 기본 제출 응답의 ID 경로는 data[0].task_id입니다.curl --request POST \
--url https://api.apimart.ai/v1/videos/generations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Idempotency-Key: <unique-operation-key>' \
--data '{
"model": "muse-video-ext",
"prompt": "Waves gently wash a beach at sunset, slow camera pan, natural ocean sounds, no text",
"aspect_ratio": "16:9",
"duration": 10,
"resolution": "720p"
}'
import requests
response = requests.post(
"https://api.apimart.ai/v1/videos/generations",
headers={
"Authorization": "Bearer <token>",
"Accept": "application/json",
"Idempotency-Key": "<unique-operation-key>"
},
json={
"model": "muse-video-ext",
"prompt": "Waves gently wash a beach at sunset, slow camera pan, natural ocean sounds, no text",
"aspect_ratio": "16:9",
"duration": 10,
"resolution": "720p"
}
)
response.raise_for_status()
print(response.json())
const response = await fetch("https://api.apimart.ai/v1/videos/generations", {
method: "POST",
headers: {
Authorization: "Bearer <token>",
"Content-Type": "application/json",
Accept: "application/json",
"Idempotency-Key": "<unique-operation-key>"
},
body: JSON.stringify({
"model": "muse-video-ext",
"prompt": "Waves gently wash a beach at sunset, slow camera pan, natural ocean sounds, no text",
"aspect_ratio": "16:9",
"duration": 10,
"resolution": "720p"
})
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01K..."
}
]
}
요청 헤더
string
필수
APIMart API Key를
Bearer <token> 형식으로 사용합니다. 제출과 조회 모두 동일한 사용자로 인증해야 합니다.string
사용을 강력히 권장합니다. 독립적인 생성마다 새 키를 사용하세요(표시 가능한 ASCII 문자 1–191자, UUID 권장). 예제의
<unique-operation-key>를 실제 값으로 바꾸세요. 제출 시간 초과나 네트워크 오류로 재시도할 때는 엔드포인트, 본문, 응답 버전, 키를 동일하게 유지해야 합니다. 작업 ID를 받았다면 해당 작업만 조회하세요.요청 매개변수
string
필수
고정값:
muse-video-ext.string
필수
생성할 내용에 대한 설명입니다. 중국어와 영어를 지원하며, 앞뒤 공백을 제거한 후 비어 있으면 안 됩니다. 참조 이미지가 있어도 필수입니다.
string[]
비어 있지 않은 참조 이미지 입력을 최대 9개까지 받습니다. 공개 URL, Data URI(예:
data:image/png;base64,...), 원시 base64를 지원합니다. 생략하거나 []를 보내면 텍스트만으로 생성합니다. PNG, JPEG, WebP를 권장합니다. URL은 브라우저 로그인 쿠키 없이 서버에서 직접 접근할 수 있어야 합니다.모든 참조 이미지의 원본 크기 합계는 11 MiB(11,534,336바이트) 이하여야 합니다. 이미지별 제한이 아닌 전체 제한입니다. base64 인코딩은 요청 본문 크기를 늘립니다. blob: URL, 로컬 파일 경로, File 객체를 보내지 마세요.string
아래 7가지 비율을 지원합니다. 생략하면 텍스트 기반 생성은
16:9, 참조 이미지 기반 생성은 참조 이미지의 구도를 따릅니다. 명시한 비율이 우선합니다. 자동 선택 시 이 필드를 생략하고 "auto"를 보내지 마세요.1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3string
호환 필드로 위 7가지 비율 또는
auto를 받으며, 1024x1024 같은 픽셀 크기는 지원하지 않습니다. size: "auto"만 보내면 비율을 지정하지 않은 것과 같습니다. aspect_ratio 사용을 권장합니다. 두 필드가 유효하면 aspect_ratio가 우선하지만 각각 검증하므로 잘못된 size는 오류를 일으킵니다.integer
기본값:"1"
요청당 결과는 1개입니다. 숫자
1만 허용합니다. 0, 음수, 1보다 큰 값을 명시하면 오류가 발생합니다.integer | string
기본값:"10"
약 10초로 고정됩니다. 숫자
10 또는 문자열 "10", "10s"를 지원하며 숫자 10을 권장합니다. 호환 별칭은 seconds, duration_seconds입니다. 하나만 사용하세요. 전달한 각 시간 필드는 독립적으로 검증됩니다.string
기본값:"720p"
720p만 지원하며 1080p나 4k는 사용할 수 없습니다. 실제 크기와 재생 시간은 반환된 미디어의 메타데이터를 기준으로 합니다.boolean
동영상에는 기본적으로 사운드가 포함되므로 생략해도 됩니다.
true는 동작을 바꾸지 않으며 false는 거부됩니다.약 10초, 720p, 사운드가 포함된 MP4 URL을 반환합니다. 참조 이미지는 생성에 참고되며 첫 프레임이 픽셀 단위로 일치한다고 보장하지 않습니다.
기타 선택 매개변수
string
작업 알림을 수신하는 백엔드 기본 URL입니다. 끝의 슬래시를 제거한 뒤
/callback을 붙입니다. 예: https://your-backend.example/muse → https://your-backend.example/muse/callback. 조회만 사용한다면 생략할 수 있습니다.string
Webhook 오류 메시지의 언어이며 생성 내용에는 영향을 주지 않습니다. 지원 값:
zh, en, ja, ko, ru, fr, de, id, pt, es. zh-CN 같은 지역 태그는 지원하지 않습니다. 조회 언어는 GET 쿼리 매개변수에 별도로 지정하세요.참조 이미지를 사용하는 예제
{
"model": "muse-video-ext",
"prompt": "The fox in the reference image slowly raises its head, wind moves its fur, gentle camera push-in",
"image_urls": [
"https://your-cdn.example/fox.png"
],
"duration": 10,
"resolution": "720p"
}
aspect_ratio를 추가하세요. 여러 이미지는 image_urls에 추가하되 총 9장을 넘지 않아야 합니다.
제출 응답
기본 응답은 HTTP200이며 data는 배열입니다. submitted는 접수되었다는 의미이며 생성 완료를 뜻하지 않습니다. data[0].task_id를 저장한 후 작업을 조회하세요.
선택적 응답 버전: 2026-07-27
선택적 응답 버전: 2026-07-27
X-APIMart-Response-Version: 2026-07-27 헤더를 보내면 HTTP 202를 반환합니다. 작업 ID는 data.id, 조회 경로는 data.poll_url에서 읽습니다.{
"code": 202,
"request_id": "req_example",
"data": {
"id": "task_01K...",
"object": "generation.task",
"type": "video",
"status": "pending",
"progress": 0,
"poll_url": "/v1/tasks/task_01K..."
}
}
data[0].task_id로 파싱하지 마세요.작업 상태 및 결과 조회
제출 시 반환된 전체 작업 ID와 동일한 사용자 인증을 사용하세요.language는 오류 메시지 언어를 지정하는 선택 매개변수입니다. 전체 필드는 작업 조회를 참고하세요.
curl --request GET \
--url 'https://api.apimart.ai/v1/tasks/<task_id>?language=ko' \
--header 'Authorization: Bearer <token>'
data.status | 처리 방법 |
|---|---|
pending / processing | 대기 중 또는 처리 중입니다. 조회를 계속합니다. |
completed | 생성 성공. 조회를 중지하고 결과 URL을 읽습니다. |
failed | 생성 실패. 조회를 중지하고 data.error.message를 확인합니다. |
unknown / … | 상태가 불확실합니다. ID를 보관하고 제한된 횟수로 다시 조회하세요. 성공으로 처리하거나 자동으로 재생성하지 마세요. |
data.status로 판단합니다. HTTP 200이나 progress: 100만으로 생성 성공을 판단할 수 없습니다. 처리 중 polling_error도 최종 실패를 의미하지 않습니다.
완료된 작업의 조회 응답 예제(결과 URL은 예시 값):
{
"code": 200,
"data": {
"id": "task_01K...",
"status": "completed",
"progress": 100,
"result": {
"videos": [
{
"url": [
"https://cdn.example/generated-video.mp4"
]
}
]
}
}
}
data는 객체이며 url은 문자열 배열입니다. 첫 결과는 data.result.videos[0].url[0]에 있습니다. expires_at이 있으면 Unix 초 단위 만료 시각이므로 필요한 파일을 만료 전에 저장하세요. actual_time은 작업 처리 시간이며 동영상 재생 시간이 아닙니다.
기능 제한 및 오류 처리
참조 동영상, 참조 오디오, 마스크, 시작/끝 프레임 제어, 연장, remix는 지원하지 않습니다.quality는 효과가 없습니다. seed, negative_prompt, width, height, response_format, output_format은 이 모델의 생성 매개변수가 아니므로 생략하세요. async: false로 동기 생성으로 전환할 수 없으며 stream은 SSE 생성 스트림을 제공하지 않습니다.
HTTP / error.code | 처리 방법 |
|---|---|
400 / invalid_request_error | 프롬프트, 참조 이미지 수, 비율, 출력 수, 고정 출력 사양을 확인하세요. |
409 / idempotency_in_progress | Retry-After에 따라 기다린 후 같은 멱등 키로 원래 요청을 재시도하세요. |
409 / idempotency_key_reused | 같은 키가 서로 다른 요청에 사용되었습니다. 키 사용을 수정하고 독립적인 생성마다 새 키를 사용하세요. |
409 / idempotency_result_indeterminate | 자동 재전송을 멈추고 확인을 위해 키와 작업 정보를 보관하세요. |
429 | Retry-After에 따라 대기한 후 재시도하세요. |
200을 반환할 수 있습니다. data.status와 data.error.message를 확인하세요. 제출 중 네트워크 오류나 5xx가 발생해도 이미 접수되었을 수 있으므로 즉시 새 키로 다시 제출하지 마세요.