MLMux API

빠른 시작

1. 01

   API 키 생성하기

   콘솔 → API 키에서 키를 생성하세요. 전체 키는 한 번만 표시되므로 MLMUX_API_KEY 등으로 즉시 저장하세요.

2. 02

   요청 보내기

   모델 ID와 프롬프트를 사용하여 이미지 또는 비디오 엔드포인트를 호출하세요. 사용량은 키를 소유한 계정에 청구됩니다.

3. 03

   결과 받기

   이미지 요청은 응답으로 URL을 반환합니다. 비디오 요청은 작업을 반환하며, 해당 작업의 poll_url을 폴링하거나 웹훅을 구독할 수 있습니다.

인증

https://api.mlmux.com으로 보내는 모든 요청의 Authorization: Bearer 헤더에 키를 포함하세요. 키는 sk-로 시작합니다. API는 다른 헤더나 쿼리 문자열에 포함된 키를 허용하지 않습니다.

키가 작동하는지 확인하려면 호출 가능한 모델 목록을 조회하세요:

curl https://api.mlmux.com/v1/models \
  -H "Authorization: Bearer $MLMUX_API_KEY"

{
  "object": "list",
  "data": [
    { "id": "nano-banana-2", "object": "model", "owned_by": "platform" },
    { "id": "model/seedance-2.5-max", "object": "model", "owned_by": "platform" }
  ]
}

엔드포인트

모든 엔드포인트는 https://api.mlmux.com 아래에 있습니다. 별도의 언급이 없는 한 요청 및 응답 본문은 JSON입니다.

라우팅 모드

업스트림 티어를 선택하려면 요청 본문에 route_mode를 설정하세요. 요청은 지정된 티어에 유지되며 다른 티어로 자동 전환되지 않습니다. 해당 모델에 대해 해당 티어가 비활성화되어 있으면 요청은 route_mode_disabled 오류와 함께 실패합니다. 이 필드를 생략하면 MLMux는 API 키에 설정된 라우트 모드를 사용하고, 그 다음 모델 기본값인 official-cheap을 사용합니다.

결제 및 청구

사용량은 크레딧으로 청구되며, 1 크레딧은 1 미국 달러에 해당합니다. 비디오 모델은 출력 토큰당 청구되며, 이미지 모델은 모델에 따라 업스트림 토큰당 또는 이미지당 청구됩니다. 각 라우트별 요금은 가격 페이지를 참조하세요.

작업 응답에는 작업 생성 시 estimated_charge_credits가 표시되고, 작업 성공 후 actual_charge_credits가 표시되며 둘 다 크레딧 단위입니다. 웹훅 페이로드에는 actual_charge_nano_credits가 정수로 표시되며, 1,000,000,000 나노크레딧이 1 크레딧과 같습니다.

GET /v1/account/balance를 사용하여 남은 잔액을 확인하세요.

작업 및 폴링

비디오 요청 및 "async": true로 전송된 이미지 요청은 작업 정보와 함께 HTTP 202를 반환합니다. 작업 상태가 succeeded, failed, expired 또는 canceled가 될 때까지 작업의 poll_url을 몇 초마다 폴링하세요.

작업 취소

대기 중(queued), 제출됨(submitted) 또는 실행 중(running)인 작업은 취소할 수 있으며, 보류되었던 크레딧이 반환됩니다. 응답은 {"id": "task_…", "status": "canceled"}입니다. 그 외의 상태인 작업은 409 task_not_cancelable을 반환합니다.

안전한 재시도

비동기 비디오 및 이미지 생성 요청은 최대 160자의 Idempotency-Key 헤더를 지원합니다. 동일한 본문으로 동일한 키를 다시 전송하면 새 작업을 생성하는 대신 기존 작업을 반환합니다. 다른 본문으로 동일한 키를 전송하면 409 idempotency_key_reused를 반환합니다. 동기식 요청 및 이미지 편집에서는 이 헤더를 지원하지 않습니다.

업로드

로컬 파일을 참조로 사용하려면 multipart 필드 file로 업로드하세요. 최대 50 MB의 이미지, 비디오, 오디오가 지원되며 3일 동안 보관됩니다. 반환된 url을 생성 요청의 URL 필드에 전달하세요.

curl https://api.mlmux.com/v1/uploads \
  -H "Authorization: Bearer $MLMUX_API_KEY" \
  -F "file=@start-frame.jpg"

{
  "url": "https://.../uploads/3f8a....jpg",
  "asset_id": 1024,
  "mime_type": "image/jpeg",
  "size_bytes": 482113,
  "asset_type": "image"
}

웹훅

Console → Webhooks에서 엔드포인트를 생성하고 수신할 이벤트를 선택하세요. 요청이나 작업이 완료되면 MLMux가 해당 URL로 JSON 본문이 포함된 POST 요청을 보냅니다.

{
  "event_id": "evt_5b0d...",
  "event_type": "request.succeeded",
  "created_at": "2026-10-26T08:00:00Z",
  "data": {
    "request_id": "task_task_01a9...",
    "task_id": "task_01a9...",
    "public_model_id": "model/seedance-2.5-max",
    "api_method": "videos.generations.create",
    "image_count": 0,
    "image_resolution": "",
    "video_seconds": 8,
    "video_resolution": "720p",
    "actual_charge_nano_credits": 1790000000,
    "latency_ms": 94210
  }
}

서명 검증

각 전송은 엔드포인트의 서명 암호(whsec_…)로 서명되며, 이는 생성하거나 교체할 때 한 번만 표시됩니다. X-MLMux-Signature 헤더에는 Unix 타임스탬프 t와 서명 v1(타임스탬프, 마침표, 원시 요청 본문의 16진수 HMAC-SHA256)이 포함됩니다. 동일한 값을 계산하여 비교하고, 오래된 타임스탬프는 거부하세요.

import crypto from "node:crypto";

// header: X-MLMux-Signature: t=1767225600,v1=5f8c...
export function verifyMLMuxSignature(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((part) => part.split("=")));
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  return fresh && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 ?? ""));
}

10초 이내에 2xx 상태 코드를 반환하세요. MLMux는 약 11시간에 걸쳐 최대 6회 재시도합니다. 중복 전송을 무시하려면 X-MLMux-Event-ID를 사용하세요.

오류

오류는 동일한 JSON 형식을 공유합니다. message 대신 code를 기준으로 분기 처리하세요. 지원팀에 문의할 때는 X-Request-ID 헤더에도 반환되는 request_id를 함께 알려주세요.

{
  "error": {
    "message": "Invalid API key",
    "type": "invalid_request_error",
    "code": "invalid_api_key",
    "request_id": "req_9f2c..."
  }
}

429 응답에는 Retry-After 헤더가 포함됩니다. 해당 시간(초)만큼 대기한 후 다시 시도하고, 5xx 오류는 지수 백오프로 재시도하세요.