비동기 작업 - AIHubMix

AIHubMix는 세 가지 작업 API를 제공합니다. 이미지는 /ai/v1/images, 비디오는 /ai/v1/videos, 통합 작업 기록은 /ai/v1/tasks를 사용합니다.

이미지 생성은 기본적으로 동기 방식이며, async: true를 전달하면 비동기로 실행됩니다.
비디오 생성은 항상 비동기로 실행됩니다.
이미지 및 비디오 상세 API는 미디어 작업의 최신 상태를 가져오는 데 사용합니다.
/ai/v1/tasks는 이미지, 비디오 및 LLM 작업에 대한 통합 읽기 전용 보기를 제공합니다.

Doubao Seedance 비디오에서 실존 인물 에셋을 참조해야 한다면 Doubao 실존 인물 에셋 사용 가이드에 따라 본인 확인과 에셋 준비를 완료한 후 비디오 작업을 생성하세요.

영상 튜토리얼: 비동기 작업

비동기 작업의 전체 구조를 설명하고, 비동기 이미지 생성을 예로 전체 호출 절차를 시연합니다.

콘솔에서 비동기 작업 활성화

/ai/v1 미디어 작업 API를 사용하기 전에 현재 계정에서 비동기 작업 기능을 활성화하세요.

비동기 작업 기능이 활성화되지 않은 경우 이미지 및 비디오 작업 생성 요청은 403 async_not_enabled를 반환합니다.

빠른 시작

다음 예시는 wan2.6-t2v로 비디오를 생성합니다. 이 모델은 duration과 size를 지원하며, 유효한 필드는 모델마다 다를 수 있습니다.

# 1. 비디오 작업을 생성하고 응답의 id 저장
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 cat playing jazz on a piano, warm lighting, cinematic shot",
    "duration": 5,
    "size": "1280x720"
  }'

# 2. 15초마다 미디어 상세 정보 조회
curl https://aihubmix.com/ai/v1/videos/{task_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

# 3. completed 상태가 되면 비디오 다운로드
curl https://aihubmix.com/ai/v1/videos/{task_id}/content \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  --output result.mp4

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

세 가지 API를 어떻게 선택하나요?

사용 사례	메서드	경로	동작
이미지 생성	POST	`/ai/v1/images/generations`	기본 동기 방식이며, `async: true`로 비동기 전환 가능
이미지 상세 조회	GET	`/ai/v1/images/{id}`	이미지 작업 상태 반환, 활성 작업은 조회 시 상태가 갱신될 수 있음
이미지 목록 조회	GET	`/ai/v1/images`	이미지 작업 스냅샷 반환
지정 이미지 다운로드	GET	`/ai/v1/images/{id}/content/{result_id}`	다중 이미지 작업에서 지정한 결과 다운로드
비디오 생성	POST	`/ai/v1/videos`	항상 비동기
비디오 상세 조회	GET	`/ai/v1/videos/{id}`	비디오 작업 상태 반환, 활성 작업은 조회 시 상태가 갱신될 수 있음
비디오 목록 조회	GET	`/ai/v1/videos`	비디오 작업 스냅샷 반환
비디오 다운로드	GET	`/ai/v1/videos/{id}/content`	작업의 기본 비디오 결과 다운로드
비동기 미디어 모델 목록 조회	GET	`/api/v1/models?type={type}&schema_checked=true`	요청 Schema가 있는 텍스트 이미지 또는 텍스트 비디오 모델 반환
모델 요청 Schema 조회	GET	`/call/schema/models/{model}/endpoints`	텍스트 이미지 또는 텍스트 비디오 엔드포인트와 JSON Schema 반환
통합 작업 목록 조회	GET	`/ai/v1/tasks`	이미지, 비디오 및 LLM 작업 읽기 전용 조회
통합 작업 상세 조회	GET	`/ai/v1/tasks/{id}`	조회 시점의 읽기 전용 작업 스냅샷 반환
통합 작업 결과 가져오기	GET	`/ai/v1/tasks/{id}/content`	단일 결과물 다운로드 또는 LLM 저장 응답 읽기
지정 통합 작업 결과 가져오기	GET	`/ai/v1/tasks/{id}/content/{result_id}`	다중 결과물 작업에서 지정한 결과 다운로드

Base URL은 https://aihubmix.com이며, Bearer Token으로 인증합니다.

Authorization: Bearer $AIHUBMIX_API_KEY

모델 목록과 모델 Schema API는 공개 검색 API이므로 Bearer Token이 필요하지 않습니다. 나머지 API는 인증이 필요합니다.

/ai/v1/tasks는 생성 API를 제공하지 않습니다. 이미지와 비디오는 해당 미디어 생성 API로 생성해야 합니다. LLM 복구 작업은 클라이언트 중단 후 플랫폼이 자동으로 저장합니다.

미디어 API와 통합 작업 API의 차이

미디어 상세 API와 통합 작업 API는 동일한 작업 최상위 필드를 반환하지만, output 항목과 조회 동작은 다릅니다.

비교 항목	미디어 상세 `/images/{id}`, `/videos/{id}`	통합 작업 상세 `/tasks/{id}`
작업 유형	이미지 또는 비디오	이미지, 비디오 또는 LLM
조회 동작	활성 작업은 조회 시 상태가 갱신될 수 있음	조회 시점의 읽기 전용 작업 스냅샷 반환
미디어 출력 필드	`index`, `type`, `content_url`, `b64_json`	`index`, `result_id`, `type`, `content_type`, `content_url`
LLM 출력 필드	해당 없음	`index`, `type=response`, `content_type`, `content_url`, `truncated`
접근 범위	현재 계정에서 생성한 해당 미디어 작업	현재 Bearer Token으로 생성한 작업

따라서 미디어 생성 상태를 폴링할 때는 이미지 또는 비디오 상세 API를 사용하세요. 작업을 통합 필터링하거나 결과 메타데이터를 읽거나 LLM 응답을 복구하려면 /ai/v1/tasks를 사용하세요.

비동기 미디어 모델을 찾고 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를 반환합니다.

지원 모델 및 필드

이미지와 비디오 프로토콜은 모델 간 공통 표준 필드를 정의하지만, 각 모델은 실제 기능에 따라 필드, 열거형 및 값 범위를 제한합니다. 호출하기 전에 모델 Schema API에서 해당 모델의 현재 제약 조건을 조회하세요. 예시:

wan2.6-t2v는 duration, size, seed를 지원하며, resolution, aspect_ratio, frame_images, input_references, generate_audio는 지원하지 않습니다.
qwen-image-2.0은 n, size, seed, negative_prompt, image, images를 지원하며, aspect_ratio와 mask는 지원하지 않습니다.

표준 필드 집합이 모든 모델에서 모든 필드를 지원한다는 의미는 아닙니다. 현재 모델이 지원하지 않는 필드를 전달하면 파라미터 오류가 반환됩니다.

LLM 중단 복구 모델

현재 다음 모델을 지원합니다.

gpt-5.6-sol
gpt-5.5-pro
gpt-5.4-pro
gpt-5.2-pro
claude-fable-5
claude-opus-5

지원 범위는 변경될 수 있으므로 이 페이지의 목록을 기준으로 확인하세요. 중단 복구를 사용하려면 현재 계정에서 비동기 작업 기능도 활성화해야 합니다. 어느 조건이든 충족하지 않으면 원래 LLM 요청은 정상적으로 실행되지만, 클라이언트 연결이 끊어진 후 복구 작업은 저장되지 않습니다.

이미지 작업을 생성하는 방법

동기 이미지

async를 생략하거나 false로 설정하면 API는 생성이 완료될 때까지 기다린 후 작업 객체를 반환합니다.

curl -X POST https://aihubmix.com/ai/v1/images/generations \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.0",
    "prompt": "A flower shop with delicate windows, warm sunlight streaming in",
    "n": 1,
    "size": "1024x1024",
    "response_format": "url"
  }'

동기 이미지 작업도 작업 기록에 저장됩니다. 클라이언트 연결이 끊어지거나 생성 응답을 잃은 경우 GET /ai/v1/images로 해당 작업을 찾을 수 있습니다.

비동기 이미지

async를 불리언 값 true로 설정하면 API가 작업 객체를 즉시 반환하고 생성은 백그라운드에서 계속됩니다.

curl -X POST https://aihubmix.com/ai/v1/images/generations \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.0",
    "prompt": "A flower shop with delicate windows, warm sunlight streaming in",
    "n": 2,
    "size": "1024x1024",
    "async": true
  }'

GET /ai/v1/images/{id}로 비동기 이미지 작업을 조회하세요. 완료 후 각 output 항목의 content_url을 직접 요청할 수 있습니다. 이 URL에는 해당 이미지의 result_id가 포함되어 있습니다.

이미지 요청의 async는 불리언 값이어야 합니다. webhook_url과 webhook_events_filter는 async: true와 함께만 사용할 수 있습니다.

이미지 표준 필드

필드	타입	필수	설명
`model`	string	예	모델 이름
`prompt`	string	예	이미지 설명, 빈 문자열은 허용되지 않음
`n`	integer/null	아니요	이미지 수, 최솟값 `1`, 기본값 `1`
`size`	string/null	아니요	`{width}x{height}`, 예: `1024x1024`
`aspect_ratio`	string/null	아니요	화면 비율, `size`와 함께 사용할 수 없음
`seed`	integer/null	아니요	난수 시드
`negative_prompt`	string/null	아니요	네거티브 프롬프트
`image`	string/object	아니요	단일 입력 이미지, URL, Data URI, Base64 또는 `{url}` 객체 사용 가능
`images`	array/null	아니요	여러 입력 이미지
`mask`	string/object	아니요	이미지 편집 마스크
`output_format`	string/null	아니요	`png`, `jpeg` 또는 `webp`, 기본값 `png`
`response_format`	string/null	아니요	`url` 또는 `b64_json`, 기본값 `url`
`async`	boolean	아니요	`true`로 설정하면 비동기 실행
`webhook_url`	string	아니요	HTTPS 콜백 주소, 최대 512자
`webhook_events_filter`	string[]	아니요	`completed`, `failed`, `cancelled`의 비어 있지 않은 부분 집합
`extra`	object/null	아니요	특정 모델의 확장 파라미터

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

비디오 요청은 항상 비동기이며, 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로는 해당 작업을 읽을 수 없습니다.

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

이미지 다운로드

이미지가 완료되면 미디어 작업 객체의 output[].content_url을 각 항목별로 요청하세요.

curl "{content_url}" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  --output result.png

이미지 미디어 다운로드 경로는 /ai/v1/images/{id}/content/{result_id}입니다. 미디어 작업 객체는 result_id를 별도로 공개하지 않으므로 클라이언트는 content_url을 직접 사용하면 됩니다. b64_json이 비어 있지 않으면 해당 필드를 직접 Base64 디코딩할 수 있습니다.

비디오 다운로드

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 구독을 설정하고 작업 상세 조회를 결과 확인 방법으로 유지하세요.

LLM 중단 복구 동작 방식

LLM 중단 복구는 클라이언트 연결이 끊어진 후 최종 응답을 가져오는 데 사용합니다. 요청 방식, 스트리밍 동작 및 응답 형식은 그대로 유지되며 요청 시작 시 작업 ID를 미리 반환하지 않습니다. 다음 조건을 모두 충족해야 합니다.

조건	설명
계정에서 비동기 작업 기능 활성화	AIHubMix 콘솔에서 현재 계정에 대해 활성화
모델에서 중단 복구 지원	현재 모델이 LLM 중단 복구 모델 목록에 포함됨
지원되는 API	Chat Completions, Anthropic Messages, Responses API 또는 Gemini `generateContent` / `streamGenerateContent`
클라이언트 중단	클라이언트 취소, 네트워크 연결 끊김 또는 호출 측의 요청 취소

플랫폼은 응답이 완전히 전달되지 않았고 클라이언트 연결이 끊어진 것을 감지한 경우에만 복구 작업을 생성하고 최종 JSON 또는 SSE를 저장합니다. 정상적으로 완료되어 클라이언트에 모두 전달된 LLM 요청은 복구 작업을 생성하지 않습니다. LLM 응답 헤더에는 X-Aihubmix-Request-Id가 포함됩니다. 클라이언트는 콘솔에서 해당 요청을 찾을 수 있도록 이 값을 가능한 한 빨리 저장해야 합니다. 공개 작업 API는 현재 요청 ID 필터링을 지원하지 않습니다. 모델과 생성 시간을 기준으로 최근 LLM 작업을 조회할 수 있습니다.

curl "https://aihubmix.com/ai/v1/tasks?object=llm&model={model}&order=desc&limit=20" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

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

LLM 작업의 통합 output 항목에는 type=response, content_type, content_url, truncated가 포함됩니다. GET /ai/v1/tasks/{id}/content는 저장된 원본 JSON 또는 SSE를 반환합니다.

LLM 중단 복구 작업은 현재 작업 단위 Webhook을 전송하지 않습니다. 클라이언트 중단은 플랫폼의 요청 처리를 중지하지 않으며 해당 호출은 원래 API 규칙에 따라 과금됩니다.

오류 응답 및 오류 코드

이 절은 /ai/v1/images/*, /ai/v1/videos/* 및 /ai/v1/tasks/*에서 object=image 또는 object=video인 미디어 작업에 적용됩니다. 클라이언트는 HTTP 비 2xx 응답과 HTTP 200, status=failed인 작업의 최종 상태를 모두 처리해야 합니다.

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

HTTP 5xx 오류 피드백 제출

HTTP 5xx 오류가 발생한 경우에만 피드백을 제출하고 error.tid를 함께 제공하세요.

HTTP 비 2xx 오류

invalid_request와 schema_violation 행에 표시된 message는 대체 템플릿입니다. 서비스가 구체적인 필드 또는 파라미터 제약 조건을 식별할 수 있으면 동적 message를 반환합니다. 클라이언트는 message 문자열을 고정 비교하지 말고 code로 오류 유형을 판단해야 합니다.

HTTP	`code`	`message`	설명
400	`invalid_request`	`Invalid request. Check the request body and parameters.` (대체 템플릿, 실제 message는 동적으로 반환될 수 있음)	공통 요청 본문, 필드 유형 또는 목록 파라미터가 올바르지 않음. 이 code의 message는 고정 값이 아니며, 필드를 특정할 수 있으면 더 구체적인 동적 message가 반환됨
400	`model_not_found`	`The requested model is not available. Check the model name and your account access.`	모델이 존재하지 않거나 사용할 수 없거나 현재 계정에 접근 권한이 없음
400	`schema_violation`	`Invalid request: one or more parameters are invalid.` (대체 템플릿, 실제 message는 동적으로 반환될 수 있음)	요청이 현재 모델의 파라미터 Schema와 일치하지 않음. 이 code의 message는 고정 값이 아니며, 필드 또는 제약 조건을 특정할 수 있으면 필드 수준의 동적 message가 반환됨
400	`capability_not_supported`	`The requested parameters are not supported for this model.`	현재 모델이 요청의 필드, 개수 또는 파라미터 한도를 지원하지 않음
400	`media_form_unsupported`	동적 미디어 안내, 아래 참조	이미지, 비디오, 참조 이미지 또는 시작 및 종료 프레임의 형식, 데이터, URL 또는 크기를 처리할 수 없음
400	`result_id_required`	`This task has multiple results. Specify result_id.`	작업에 여러 결과가 있지만 다운로드할 때 `result_id`를 지정하지 않음
400	`upstream_rejected`	`Upstream service rejected the request.`	모델 프로바이더가 생성 요청을 거부함
401	`authentication_failed`	`Authentication failed: invalid or missing API key.`	API Key가 없거나 유효하지 않음
402	`insufficient_quota`	`Insufficient quota.`	AIHubMix 계정의 사용 가능 잔액이 부족함
403	`permission_denied`	`You do not have permission to access this resource.`	현재 계정, API Key 또는 접근 출처에 해당 리소스 사용 권한이 없음
403	`async_not_enabled`	`Asynchronous tasks are not enabled. Please go to <console-url>/async-tasks to activate.`	현재 계정에서 비동기 작업 기능이 활성화되지 않음. 콘솔 주소는 요청 사이트에 따라 생성됨
404	`task_not_found`	`Task not found.`	작업이 없거나 페이지네이션 커서가 유효하지 않거나 현재 계정에 조회 권한이 없음
404	`result_not_found`	`Result not found.`	결과가 없거나 아직 준비되지 않았거나 결과 ID가 일치하지 않거나 현재 계정에 다운로드 권한이 없음
410	`artifact_expired`	`The result has expired.`	결과의 보관 기간이 만료됨
413	`request_too_large`	`Request body is too large. Reduce the request size and try again.`	전체 요청 본문이 32 MiB를 초과함
413	`image_too_large`	`Image is too large. Reduce the image size and try again.`	이미지 API에서 디코딩한 단일 이미지가 모델의 처리 한도를 초과함
422	`image_not_generated`	`The expected image was not generated.`	모델 프로바이더가 요청을 완료했지만 전달 가능한 이미지를 반환하지 않음
429	`rate_limited`	`Too many requests. Please slow down and retry.`	AIHubMix가 현재 계정 또는 API Key의 요청을 제한함
429	`upstream_rate_limited`	`Upstream service is rate limiting. Please retry later.`	모델 프로바이더가 요청 제한 오류를 반환함
429	`too_many_downloads`	`Download limit exceeded for this result.`	단일 결과의 다운로드 횟수가 한도에 도달함
500	`internal_error`	`Internal error. Please retry.`	호출자가 해결할 수 없는 내부 서비스 오류가 발생함
502	`upstream_unreachable`	`Upstream service is temporarily unavailable. Please retry.`	모델 프로바이더에 연결할 수 없거나 응답 전체를 읽을 수 없음
502	`upstream_bad_response`	`Upstream service returned an invalid response.`	모델 프로바이더가 플랫폼에서 처리할 수 없는 응답을 반환함
502	`upstream_error`	`Upstream service is temporarily unavailable. Please retry.`	모델 프로바이더가 서비스 오류를 반환함
503	`model_unavailable`	`The requested model is temporarily unavailable.`	선택한 모델을 일시적으로 사용할 수 없음
503	`service_unavailable`	`Service is temporarily unavailable. Please retry.`	조회, 다운로드 또는 결과 서비스를 일시적으로 사용할 수 없음
504	`sync_timeout`	`Generation timed out. Please retry.`	동기 생성이 대기 시간 내에 완료되지 않음

media_form_unsupported의 message는 확인된 원인에 따라 생성되며, 일반적인 템플릿은 다음과 같습니다.

상황	`message`
지원하지 않는 형식	`Unsupported <media-kind> format: <detected-format>. Supported formats for this model: <allowed-formats>.`
이미지 또는 비디오 데이터가 유효하지 않음	`The <media-kind> data is invalid. Provide a valid <media-kind>.`
미디어 유형을 확인할 수 없을 때 데이터가 유효하지 않음	`The media data is invalid. Provide valid media data.`
미디어 URL에 접근할 수 없음	`The <media-kind> URL could not be accessed. Make sure it is publicly accessible and returns a valid <media-kind>.`
미디어를 디코딩할 수 없음	`Unable to process the <media-kind>. Check that the <media-kind> data or URL is valid and supported.`
이미지 작업 이외의 미디어가 한도를 초과함	`The <media-kind> is too large. Reduce the <media-kind> size and try again.`
구체적인 원인을 안전하게 확인할 수 없음	`Unable to process the media. Check that the media data or URL is valid and supported.`

예를 들어 모델이 PNG, JPEG, WebP, HEIC 및 HEIF를 허용하는 경우 GIF 이미지는 다음 message를 반환합니다.

Unsupported image format: GIF. Supported formats for this model: PNG, JPEG, WebP, HEIC, and HEIF.

HTTP 200 + Task `status=failed`

조회 요청이 성공해도 생성 성공을 의미하지는 않습니다. 작업이 failed이면 클라이언트는 작업 객체의 error.code와 error.message에서 실패 원인을 읽어야 합니다.

{
  "id": "task_01K0ABCDEF",
  "status": "failed",
  "error": {
    "code": "media_form_unsupported",
    "message": "Unsupported image format: GIF. Supported formats for this model: PNG, JPEG, WebP, HEIC, and HEIF."
  }
}

Task `code`	`message`	설명
`media_form_unsupported`	동적 미디어 안내, 위 참조	비동기 작업의 미디어 형식, 데이터, URL, 디코딩 또는 크기 오류
`image_too_large`	`Image is too large. Reduce the image size and try again.`	비동기 이미지 작업의 입력 이미지가 한도를 초과함
`image_not_generated`	`The expected image was not generated.`	모델 프로바이더가 전달 가능한 이미지를 반환하지 않음
`upstream_rejected`	`Upstream service rejected the request.`	모델 프로바이더가 생성 요청을 거부함
`upstream_rate_limited`	`Upstream service is rate limiting. Please retry later.`	모델 프로바이더가 요청 제한 오류를 반환함
`upstream_unreachable`	`Upstream service is temporarily unavailable. Please retry.`	작업 생성 시 모델 프로바이더에 연결할 수 없거나 응답 전체를 읽을 수 없음
`upstream_bad_response`	`Upstream service returned an invalid response.`	모델 프로바이더의 응답을 처리할 수 없음
`upstream_error`	`Upstream service is temporarily unavailable. Please retry.`	모델 프로바이더의 작업 생성 또는 실행이 실패함
`upstream_empty_output`	`The upstream service completed without producing a usable result. Please retry.`	모델 프로바이더가 작업을 완료했지만 전달 가능한 결과를 생성하지 않음
`output_policy_violation`	`Generated content was rejected by the content policy.`	생성된 콘텐츠가 콘텐츠 안전 정책을 통과하지 못함
`sync_timeout`	`Generation timed out. Please retry.`	생성 결과 대기 시간이 초과됨
`internal_error`	`Internal error. Please retry.`	비동기 작업 처리 중 내부 오류가 발생함

전체 비디오 예시

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));
}

자주 묻는 질문

미디어 작업은 /ai/v1/tasks/{id}와 미디어 상세 API 중 어디에서 조회해야 하나요? 생성 상태를 폴링할 때는 미디어 상세 API를 사용하세요. 이미지는 /ai/v1/images/{id}, 비디오는 /ai/v1/videos/{id}로 조회합니다. /ai/v1/tasks/{id}는 읽기 전용 스냅샷을 반환합니다. 비디오 요청에서 seconds를 사용하면 파라미터 오류가 발생하는 이유는 무엇인가요? /ai/v1/videos 표준 프로토콜은 정수 duration을 초 단위로 사용합니다. 구체적인 허용 값은 해당 모델이 지원하는 파라미터에 따라 결정됩니다. 일부 비디오 모델에서 resolution을 사용하면 파라미터 오류가 발생하는 이유는 무엇인가요? 표준 비디오 프로토콜에는 resolution과 size가 포함되지만, 각 모델은 지원 필드를 제한할 수 있습니다. 예를 들어 wan2.6-t2v는 size를 사용하며 resolution을 지원하지 않습니다. 생성 응답을 잃은 후 미디어 작업을 어떻게 찾나요? 이미지는 GET /ai/v1/images, 비디오는 GET /ai/v1/videos를 요청하세요. 목록은 after, limit, order 페이지네이션 파라미터를 지원합니다. 두 상세 API의 output 필드가 다른 이유는 무엇인가요? 미디어 상세 API는 직접 다운로드에 필요한 간소화된 필드를 제공합니다. 통합 작업 API는 result_id와 content_type을 추가로 제공하며, LLM 저장 응답에는 truncated도 제공합니다. Webhook을 받지 못한 경우 어떻게 해야 하나요? 콜백 주소가 외부에서 접근 가능하고 즉시 2xx를 반환하는지 확인한 후 미디어 상세 API로 최종 상태를 조회하세요.

마지막 업데이트: 2026-08-12

영상 튜토리얼: 비동기 작업

콘솔에서 비동기 작업 활성화

​빠른 시작

​세 가지 API를 어떻게 선택하나요?

​미디어 API와 통합 작업 API의 차이

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

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

​단일 모델의 요청 Schema 조회

​지원 모델 및 필드

​LLM 중단 복구 모델

​이미지 작업을 생성하는 방법

​동기 이미지

​비동기 이미지

​이미지 표준 필드

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

​비디오 표준 필드

​미디어 작업 객체

​상태 설명

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

​미디어 상세 조회

​미디어 목록 조회

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

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

​이미지 다운로드

​비디오 다운로드

​Webhook 사용 방법

​콜백 요청

​재시도 및 중복 제거

​LLM 중단 복구 동작 방식

​오류 응답 및 오류 코드

HTTP 5xx 오류 피드백 제출

​HTTP 비 2xx 오류

​HTTP 200 + Task status=failed

​전체 비디오 예시

​자주 묻는 질문

빠른 시작

세 가지 API를 어떻게 선택하나요?

미디어 API와 통합 작업 API의 차이

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

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

단일 모델의 요청 Schema 조회

지원 모델 및 필드

LLM 중단 복구 모델

이미지 작업을 생성하는 방법

동기 이미지

비동기 이미지

이미지 표준 필드

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

비디오 표준 필드

미디어 작업 객체

상태 설명

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

미디어 상세 조회

미디어 목록 조회

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

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

이미지 다운로드

비디오 다운로드

Webhook 사용 방법

콜백 요청

재시도 및 중복 제거

LLM 중단 복구 동작 방식

오류 응답 및 오류 코드

HTTP 비 2xx 오류

HTTP 200 + Task `status=failed`

전체 비디오 예시

자주 묻는 질문