비디오 생성

빠른 시작

비디오 생성은 항상 비동기입니다. 예제는 wan2.6-t2v와 초 단위 정수 duration을 사용합니다.

curl -X POST https://aihubmix.com/ai/v1/videos \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.6-t2v",
    "prompt": "Ocean waves crashing on rocky cliffs at sunset",
    "duration": 5,
    "size": "1280x720"
  }'

{
  "id": "task_01K0ABCDEF",
  "object": "video",
  "model": "wan2.6-t2v",
  "status": "in_progress",
  "output": [],
  "error": null,
  "created_at": 1784707200,
  "completed_at": null,
  "expires_at": null
}

curl https://aihubmix.com/ai/v1/videos/{id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

curl https://aihubmix.com/ai/v1/videos/{id}/content \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  --output result.mp4

비동기 미디어 모델을 찾고 Schema를 가져오는 방법

검색 절차는 두 단계입니다. 먼저 공개 모델 카탈로그에서 비동기 API를 지원하는 텍스트 이미지 또는 텍스트 비디오 모델을 가져옵니다. 그런 다음 모델의 model_id를 사용해 해당 엔드포인트의 요청 Schema를 가져옵니다.

비동기 API를 지원하는 모델 목록 조회

모델 카탈로그는 Playground와 같은 데이터 소스를 사용합니다. 텍스트 이미지 모델에는 type=image_generation, 텍스트 비디오 모델에는 type=video를 사용하세요. schema_checked=true를 추가하면 요청 Schema가 게시되고 검토된 모델만 반환됩니다.

# 텍스트 이미지 모델
curl "https://aihubmix.com/api/v1/models?type=image_generation&schema_checked=true&sort_by=order"

# 텍스트 비디오 모델
curl "https://aihubmix.com/api/v1/models?type=video&schema_checked=true&sort_by=order"

두 요청은 같은 API를 사용합니다. 현재 type 필터는 하나의 값만 허용하므로 모델 유형별로 요청하세요. 응답 구조는 {success, message, data}입니다. 비동기 미디어 연동과 관련된 data 필드는 다음과 같습니다.

필드	설명
`data[].model_id`	생성 요청과 후속 Schema 요청에 사용하는 모델 ID
`data[].model_name`	모델 표시 이름
`data[].types`	쉼표로 구분된 모델 유형이며 `image_generation`과 `llm`을 함께 포함할 수 있음
`data[].input_modalities`	쉼표로 구분된 입력 모달리티
`data[].schema_checked`	`true`이면 요청 Schema가 게시되고 검토되었음을 의미

{
  "success": true,
  "message": "",
  "data": [
    {
      "model_id": "qwen-image-2.0",
      "model_name": "Qwen Image 2.0",
      "types": "image_generation",
      "input_modalities": "text,image",
      "schema_checked": true
    }
  ]
}

단일 모델의 요청 Schema 조회

지원 필드, 열거형 및 숫자 범위는 모델마다 다를 수 있습니다. 이미지 또는 비디오 요청을 보내기 전에 다음 공개 API를 사용하여 선택한 모델의 사용 가능한 엔드포인트와 요청 JSON Schema를 조회하세요.

# 텍스트 이미지 모델
curl "https://aihubmix.com/call/schema/models/qwen-image-2.0/endpoints"

# 텍스트 비디오 모델
curl "https://aihubmix.com/call/schema/models/wan2.6-t2v/endpoints"

응답의 modality는 image 또는 video입니다. endpoints 배열의 각 항목은 사용 가능한 호출 프로토콜 하나를 설명합니다.

필드	설명
`default_endpoint`	모델의 기본 엔드포인트 식별자
`endpoints[].endpoint`	엔드포인트 식별자
`endpoints[].method`	`POST`와 같은 HTTP 메서드
`endpoints[].path`	실제 요청 경로
`endpoints[].content_types`	엔드포인트가 허용하는 콘텐츠 유형
`endpoints[].lifecycle`	동기 또는 비동기 모드, 폴링 경로 및 상태 값
`endpoints[].request.schema`	필수 필드와 값 제약을 포함한 해당 모델 및 엔드포인트의 전체 JSON Schema

같은 모델에서 /ai/v1 엔드포인트와 OpenAI 호환 /v1 엔드포인트가 함께 반환될 수 있습니다. OpenAI 호환 엔드포인트는 최신 모델을 아직 지원하지 않을 수 있으므로 /ai/v1 엔드포인트를 우선 사용하세요. 비동기 작업 API에는 path가 /ai/v1/images/generations 또는 /ai/v1/videos인 항목을 선택한 후 해당 request.schema를 사용하세요. endpoints 배열의 위치에 의존하지 마세요. 다음 명령은 각 비동기 작업 엔드포인트의 요청 Schema를 직접 추출합니다.

# 텍스트 이미지
curl -s "https://aihubmix.com/call/schema/models/qwen-image-2.0/endpoints" \
  | jq '.endpoints[] | select(.path == "/ai/v1/images/generations") | .request.schema'

# 텍스트 비디오
curl -s "https://aihubmix.com/call/schema/models/wan2.6-t2v/endpoints" \
  | jq '.endpoints[] | select(.path == "/ai/v1/videos") | .request.schema'

모델이 없거나 검색 가능한 엔드포인트가 없으면 404 model_not_found를 반환합니다. 엔드포인트 데이터를 일시적으로 사용할 수 없으면 500 endpoints_unavailable를 반환합니다.

비디오 작업을 생성하는 방법

비디오 요청은 항상 비동기이며, Prefer: wait로 동기 대기로 전환할 수 없습니다. 표준 프로토콜은 정수 duration을 초 단위로 사용합니다.

curl -X POST https://aihubmix.com/ai/v1/videos \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.6-t2v",
    "prompt": "Ocean waves crashing on rocky cliffs at sunset",
    "duration": 5,
    "size": "1280x720"
  }'

비디오 표준 필드

필드	타입	필수	설명
`model`	string	예	모델 이름
`prompt`	string	예	비디오 설명, 빈 문자열은 허용되지 않음
`duration`	integer/null	아니요	비디오 길이, 단위는 초이며 구체적인 범위는 모델에 따라 결정됨
`aspect_ratio`	string/null	아니요	화면 비율, 프로토콜 기본값 `16:9`
`resolution`	string/null	아니요	`480p`, `720p`, `1080p`, `1K`, `2K` 또는 `4K`
`size`	string/null	아니요	`{width}x{height}`, `resolution` 및 `aspect_ratio` 대신 사용 가능
`seed`	integer/null	아니요	난수 시드
`input_references`	array/null	아니요	이미지, 비디오 또는 오디오 참조 자료
`frame_images`	array/null	아니요	첫 프레임 또는 마지막 프레임 이미지
`generate_audio`	boolean/null	아니요	오디오 트랙 생성 여부
`webhook_url`	string	아니요	HTTPS 콜백 주소, 최대 512자
`webhook_events_filter`	string[]	아니요	`completed`, `failed`, `cancelled`의 비어 있지 않은 부분 집합
`extra`	object/null	아니요	특정 모델의 확장 파라미터

input_references 항목 구조:

{
  "type": "image_url",
  "url": "https://example.com/reference.png"
}

type은 image_url, video_url 또는 audio_url일 수 있습니다. frame_images 항목 구조:

{
  "frame_type": "first_frame",
  "image_url": {
    "url": "https://example.com/first-frame.png"
  }
}

frame_type은 first_frame 또는 last_frame일 수 있습니다.

미디어 작업 객체

이미지 및 비디오 전용 API는 다음 구조를 반환합니다.

{
  "id": "task_01K0ABCDEF",
  "object": "video",
  "model": "wan2.6-t2v",
  "status": "completed",
  "output": [
    {
      "index": 0,
      "type": "file",
      "b64_json": null,
      "content_url": "https://aihubmix.com/ai/v1/videos/task_01K0ABCDEF/content"
    }
  ],
  "error": null,
  "created_at": 1784707200,
  "completed_at": 1784707320,
  "expires_at": null
}

필드	타입	설명
`id`	string	플랫폼 작업 ID
`object`	string	`image` 또는 `video`
`model`	string	모델 이름
`status`	string	현재 작업 상태
`output`	array	생성된 결과, 결과가 아직 없으면 빈 배열
`error`	object/null	실패 정보, `code`, `message`, `upstream_detail`을 포함할 수 있음
`created_at`	integer	생성 시간, Unix 초
`completed_at`	integer/null	최종 상태 시간, Unix 초
`expires_at`	null	미디어 전용 API는 현재 `null` 반환

미디어 output 항목:

필드	타입	설명
`index`	integer	결과 순서, `0`부터 시작
`type`	string	현재 값은 `file`
`content_url`	string/null	결과 다운로드 주소
`b64_json`	string/null	Base64로 인코딩된 이미지 결과

상태 설명

상태	종료 여부	설명
`pending`	아니요	플랫폼이 작업을 접수했으며 실행 대기 중
`in_progress`	아니요	작업 실행 중
`completed`	예	작업 완료, `output` 읽기 가능
`failed`	예	작업 실패, 원인은 `error` 참조
`cancelled`	예	작업 취소됨

상태가 completed, failed 또는 cancelled로 바뀔 때까지 클라이언트에서 15초마다 조회할 수 있습니다. 15초는 클라이언트 폴링 권장 간격이며 서버 프로토콜 제한이 아닙니다.

미디어 작업을 조회하는 방법

미디어 상세 조회

# 이미지
curl https://aihubmix.com/ai/v1/images/{task_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

# 비디오
curl https://aihubmix.com/ai/v1/videos/{task_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

미디어 상세 API는 갱신된 작업 상태를 반환할 수 있으므로, 미디어 폴링에는 해당 이미지 또는 비디오 상세 API를 사용하세요.

미디어 목록 조회

생성 응답을 잃은 경우 해당 미디어 목록에서 작업 ID를 찾을 수 있습니다.

curl "https://aihubmix.com/ai/v1/videos?limit=20&order=desc" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

파라미터	타입	기본값	설명
`after`	string	-	페이지네이션 커서, 이전 페이지의 `next_after` 사용
`limit`	integer	`20`	페이지당 개수, 최대 `100`
`order`	string	`desc`	`asc`는 오름차순, 그 외 값은 `desc`로 처리

{
  "object": "list",
  "data": [
    {
      "id": "task_01K0ABCDEF",
      "object": "video",
      "model": "wan2.6-t2v",
      "status": "in_progress",
      "output": [],
      "error": null,
      "created_at": 1784707200,
      "completed_at": null,
      "expires_at": null
    }
  ],
  "has_more": true,
  "next_after": "task_01K0ABCDEF"
}

미디어 목록은 조회 시점의 작업 스냅샷을 반환하며 작업 상태를 직접 갱신하지 않습니다.

통합 작업 API를 사용하는 방법

통합 작업 API는 다음 필터를 지원합니다.

curl "https://aihubmix.com/ai/v1/tasks?object=video&status=in_progress&limit=20&order=desc" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

파라미터	타입	기본값	설명
`object`	string	-	`llm`, `image` 또는 `video`
`status`	string	-	`pending`, `in_progress`, `completed`, `failed` 또는 `cancelled`
`model`	string	-	모델 이름 정확 일치 필터
`after`	string	-	페이지네이션 커서
`limit`	integer	`20`	범위 `1`에서 `100`
`order`	string	`desc`	`asc` 또는 `desc`

통합 작업 상세:

curl https://aihubmix.com/ai/v1/tasks/{task_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

미디어 작업의 통합 output 항목:

{
  "index": 0,
  "result_id": "result_01K0XYZ",
  "type": "file",
  "content_type": "video/mp4",
  "content_url": "https://aihubmix.com/ai/v1/tasks/task_01K0ABCDEF/content"
}

단일 결과물은 /ai/v1/tasks/{id}/content로 직접 요청하세요. 다중 결과물 작업은 /ai/v1/tasks/{id}/content/{result_id}를 요청해야 하며, 결과 ID를 지정하지 않으면 400 result_id_required가 반환됩니다.

통합 작업 목록, 상세 및 콘텐츠 API는 작업을 생성한 Bearer Token에 따라 격리됩니다. 같은 계정의 다른 API Key로는 해당 작업을 읽을 수 없습니다.

미디어 결과를 다운로드하는 방법

비디오 다운로드

curl https://aihubmix.com/ai/v1/videos/{task_id}/content \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  --output result.mp4

결과는 만료될 수 있으며 다운로드 횟수 제한이 적용될 수 있습니다. 만료된 경우 410 artifact_expired, 다운로드 횟수 제한을 초과한 경우 429 too_many_downloads가 반환됩니다.

Webhook 사용 방법

비동기 이미지 및 비디오는 작업 단위 Webhook을 지원합니다.

curl -X POST https://aihubmix.com/ai/v1/videos \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.6-t2v",
    "prompt": "A tranquil garden at sunrise",
    "duration": 5,
    "size": "1280x720",
    "webhook_url": "https://example.com/webhooks/aihubmix",
    "webhook_events_filter": ["completed", "failed"]
  }'

webhook_url은 최대 512자이며 로컬 호스트, 사설망 또는 기타 제한된 주소를 가리킬 수 없습니다. webhook_events_filter를 생략하면 플랫폼은 completed, failed, cancelled를 전송합니다. 명시적으로 전달하는 경우 배열은 비어 있거나 중복될 수 없으며 webhook_url과 함께 사용해야 합니다. 요청에 webhook_url을 전달하지 않으면 비동기 이미지 및 비디오는 계정에 설정된 기본 콜백 주소를 사용하려고 시도합니다. 유효하지 않은 계정 기본 주소는 무시되며 작업 생성을 차단하지 않습니다.

콜백 요청

{
  "event_id": "evt_01K0ABCDEF",
  "event_type": "completed",
  "created_at": "2026-08-12T12:00:00Z",
  "data": {
    "task_id": "task_01K0ABCDEF",
    "status": "completed",
    "model": "wan2.6-t2v",
    "results": [
      {
        "url": "https://aihubmix.com/ai/v1/tasks/task_01K0ABCDEF/content"
      }
    ]
  }
}

필드	설명
`event_id`	콜백 이벤트 ID, 중복 제거에 사용
`event_type`	`completed`, `failed` 또는 `cancelled`
`created_at`	RFC 3339 형식의 이벤트 시간
`data.task_id`	플랫폼 작업 ID
`data.status`	현재 최종 상태
`data.model`	모델 이름
`data.results[].url`	완료 시 반환될 수 있는 결과 다운로드 주소
`data.error`	실패 시 반환될 수 있는 오류 정보

results는 결과가 저장된 경우에만 표시되며 다운로드에는 여전히 Bearer Token이 필요합니다.

재시도 및 중복 제거

플랫폼은 최소 한 번 전달 방식을 사용하므로 동일한 이벤트가 중복 전송될 수 있습니다.

HTTP 2xx는 수신 성공을 의미합니다.
HTTP 5xx, 네트워크 오류 또는 타임아웃은 재시도를 유발합니다.
HTTP 3xx 및 4xx는 재시도하지 않습니다.
최대 6회 전달하며, 재시도 간격은 순서대로 1, 4, 16, 64, 256초입니다.

수신 측은 event_id를 저장하고 동일한 이벤트를 다시 받으면 즉시 2xx를 반환해야 합니다.

작업 단위 Webhook 자체에는 별도의 서명 키가 없습니다. 서명 검증이 필요하면 계정 단위 Webhook 구독을 설정하고 작업 상세 조회를 결과 확인 방법으로 유지하세요.

오류 응답 및 오류 코드

{
  "error": {
    "message": "Task not found.",
    "type": "invalid_request_error",
    "code": "task_not_found",
    "tid": "req_01K0ABCDEF"
  }
}

HTTP 상태 코드	오류 코드	설명
400	`invalid_request`	파라미터 타입 또는 값이 올바르지 않음
400	`result_id_required`	통합 작업에 여러 결과가 있지만 다운로드 시 `result_id`를 지정하지 않음
400	`webhook_invalid`	Webhook URL이 유효하지 않거나 필터에 URL이 없음
400	`webhook_events_filter_invalid`	Webhook 이벤트 목록이 유효하지 않음
401	`authentication_failed`	API Key 누락 또는 무효
403	`async_not_enabled`	계정에서 비동기 작업 기능이 활성화되지 않음
404	`task_not_found`	작업 또는 페이지네이션 커서가 존재하지 않음
404	`result_not_found`	결과가 존재하지 않거나 현재 다운로드할 수 없음
410	`artifact_expired`	결과가 만료됨
413	`request_too_large`	요청 본문이 32 MiB를 초과함
429	`too_many_downloads`	결과 다운로드 횟수 제한 초과
503	`async_unavailable`	비동기 이미지 서비스를 일시적으로 사용할 수 없음

error.tid는 요청 추적 ID입니다. 기술 지원에 문의할 때 함께 제공하세요.

전체 예제

작업을 만들고 폴링한 뒤 MP4 결과를 다운로드합니다.

import os
import time

import requests

base_url = "https://aihubmix.com"
headers = {
    "Authorization": f"Bearer {os.environ['AIHUBMIX_API_KEY']}",
    "Content-Type": "application/json",
}

response = requests.post(
    f"{base_url}/ai/v1/videos",
    headers=headers,
    json={
        "model": "wan2.6-t2v",
        "prompt": "A cat playing jazz on a piano",
        "duration": 5,
        "size": "1280x720",
    },
    timeout=60,
)
response.raise_for_status()
task = response.json()

while task["status"] not in {"completed", "failed", "cancelled"}:
    time.sleep(15)
    response = requests.get(
        f"{base_url}/ai/v1/videos/{task['id']}",
        headers=headers,
        timeout=30,
    )
    response.raise_for_status()
    task = response.json()

if task["status"] == "completed":
    result = requests.get(
        f"{base_url}/ai/v1/videos/{task['id']}/content",
        headers=headers,
        timeout=120,
    )
    result.raise_for_status()
    with open("result.mp4", "wb") as file:
        file.write(result.content)
else:
    raise RuntimeError(task.get("error") or task["status"])

import { writeFile } from "node:fs/promises";

const baseUrl = "https://aihubmix.com";
const headers = {
  Authorization: `Bearer ${process.env.AIHUBMIX_API_KEY}`,
  "Content-Type": "application/json",
};

const created = await fetch(`${baseUrl}/ai/v1/videos`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    model: "wan2.6-t2v",
    prompt: "A cat playing jazz on a piano",
    duration: 5,
    size: "1280x720",
  }),
});
if (!created.ok) throw new Error(await created.text());
let task = await created.json();

const finished = new Set(["completed", "failed", "cancelled"]);
while (!finished.has(task.status)) {
  await new Promise((resolve) => setTimeout(resolve, 15_000));
  const polled = await fetch(`${baseUrl}/ai/v1/videos/${task.id}`, { headers });
  if (!polled.ok) throw new Error(await polled.text());
  task = await polled.json();
}

if (task.status === "completed") {
  const result = await fetch(`${baseUrl}/ai/v1/videos/${task.id}/content`, {
    headers,
  });
  if (!result.ok) throw new Error(await result.text());
  await writeFile("result.mp4", Buffer.from(await result.arrayBuffer()));
} else {
  throw new Error(JSON.stringify(task.error ?? task.status));
}

시작하기

게이트웨이 기능

모델 기능

프로토콜 참조

플랫폼 관리

개인정보 및 약관

빠른 시작

비동기 미디어 모델을 찾고 Schema를 가져오는 방법

비동기 API를 지원하는 모델 목록 조회

단일 모델의 요청 Schema 조회

비디오 작업을 생성하는 방법

비디오 표준 필드

미디어 작업 객체

상태 설명

미디어 작업을 조회하는 방법

미디어 상세 조회

미디어 목록 조회

통합 작업 API를 사용하는 방법

미디어 결과를 다운로드하는 방법

비디오 다운로드

Webhook 사용 방법

콜백 요청

재시도 및 중복 제거

오류 응답 및 오류 코드

전체 예제

​빠른 시작

​비동기 미디어 모델을 찾고 Schema를 가져오는 방법

​비동기 API를 지원하는 모델 목록 조회

​단일 모델의 요청 Schema 조회

​비디오 작업을 생성하는 방법

​비디오 표준 필드

​미디어 작업 객체

​상태 설명

​미디어 작업을 조회하는 방법

​미디어 상세 조회

​미디어 목록 조회

​통합 작업 API를 사용하는 방법

​미디어 결과를 다운로드하는 방법

​비디오 다운로드

​Webhook 사용 방법

​콜백 요청

​재시도 및 중복 제거

​오류 응답 및 오류 코드

​전체 예제

빠른 시작

비동기 미디어 모델을 찾고 Schema를 가져오는 방법

비동기 API를 지원하는 모델 목록 조회

단일 모델의 요청 Schema 조회

비디오 작업을 생성하는 방법

비디오 표준 필드

미디어 작업 객체

상태 설명

미디어 작업을 조회하는 방법

미디어 상세 조회

미디어 목록 조회

통합 작업 API를 사용하는 방법

미디어 결과를 다운로드하는 방법

비디오 다운로드

Webhook 사용 방법

콜백 요청

재시도 및 중복 제거

오류 응답 및 오류 코드

전체 예제