비동기 작업 - 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/*에 적용됩니다. LLM 작업은 기존 오류 규약을 유지합니다. 미디어 유형이 지정되지 않았고 Task도 아직 가져오지 못한 조회에는 일반 오류 규약이 계속 적용됩니다.

현재 요청 실패: HTTP 상태가 2xx가 아니면 현재 생성, 조회 또는 다운로드 요청이 실패한 것입니다. HTTP 요청 실패를 참조하세요.
작업 실행 실패: 조회는 HTTP 200을 반환하지만 작업의 status=failed이며 원인은 작업 내 error에 기록됩니다. 작업 실행 실패를 참조하세요.
목록의 개별 결과 읽기 실패: 목록은 HTTP 200을 반환하지만 일부 작업에 output_error가 포함됩니다. 목록의 개별 결과 읽기 실패를 참조하세요.

아래 표의 message 열은 API가 반환하는 영어 메시지이며, 설명 열은 의미와 조치 방법을 안내합니다. 매개변수 검증 오류에는 일반 메시지를 표시하며, 실제 응답에는 구체적인 필드와 제약 조건이 포함될 수 있습니다. 클라이언트는 code로 오류 유형을 판단하고 message 전체 문자열의 일치 여부에 의존하지 않아야 합니다.

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

HTTP 5xx 오류 신고

요청이 HTTP 5xx를 반환하면 error.tid를 첨부하여 신고해 주세요.

HTTP 요청 실패

아래 HTTP 상태는 현재 요청 자체가 실패한 경우에 적용됩니다. 이미 생성된 작업의 실행 실패는 아래 작업 실행 실패 표를 참조하세요.

요청 매개변수 및 미디어 입력

HTTP	`code`	`message`	설명
400	`invalid_request`	`Invalid request. Check the request body and parameters.`	요청 본문, 쿼리 매개변수 또는 매개변수 유형이 올바르지 않습니다. 오류 메시지에 따라 요청 형식, 유형 및 값을 확인하세요.
404	`model_not_found`	`The requested model was not found. Check the model name.`	요청한 모델이 없습니다. 모델 이름을 확인하세요.
400	`schema_violation`	`One or more model parameters are invalid. Check the model schema and request values.`	매개변수가 선택한 모델의 입력 요구 사항을 충족하지 않습니다. 모델의 schema를 확인하고 오류에 표시된 필드를 수정하세요.
400	`unsupported_input_combination`	`This model does not support this operation or media input combination. Change the inputs or choose another model.`	현재 모델이 이 작업과 미디어 입력의 조합을 지원하지 않습니다. 입력 조합을 바꾸거나 해당 조합을 지원하는 모델을 선택하세요.
400	`capability_not_supported`	`One or more requested parameters are not supported by this model. Change the parameters or choose another model.`	요청 매개변수가 모델의 지원 범위를 벗어납니다. 오류 메시지에 따라 매개변수를 조정하거나 다른 모델을 선택하세요.
400	`unsupported_media_format`	`The {media_kind} format is not supported for this model.`	모델이 현재 미디어 형식을 지원하지 않습니다. 오류 메시지 또는 `error.details.allowed_mime_types`에 나열된 형식을 사용하세요. 목록이 없으면 모델의 입력 요구 사항을 확인하세요.
400	`invalid_media_data`	`The media data is invalid. Provide valid media data.`	손상된 base64 또는 잘못된 data URI 구조 등으로 미디어 데이터가 유효하지 않음이 확인되었습니다. 데이터의 무결성과 인코딩을 확인하고 유효한 미디어를 제공하세요.
400	`media_url_unreachable`	`The media URL could not be accessed. Make sure it is publicly accessible and returns valid media data.`	미디어 링크에 접근하거나 내용을 읽을 수 없습니다. 링크가 유효하고 인터넷에서 접근 가능하며 유효한 미디어를 반환하는지 확인하세요.
400	`invalid_media`	`The media input could not be processed. Check that its data or URL is valid and uses a supported format.`	미디어 입력을 처리할 수 없으며 더 구체적인 원인은 확인되지 않았습니다. 데이터 또는 링크가 유효하고 모델이 해당 형식을 지원하는지 확인하세요.
413	`image_too_large`	`The image is too large. Reduce the image size to {max_bytes} bytes or less and try again.`	이미지 작업의 미디어 내용이 현재 처리 한도를 초과했습니다. `error.details.max_bytes` 또는 오류 메시지의 한도에 맞게 크기를 줄인 후 다시 시도하세요.
413	`media_too_large`	`The {media_kind} exceeds the allowed size of {max_bytes} bytes. Reduce its size and try again.`	다른 미디어 작업의 내용이 현재 처리 한도를 초과했습니다. `error.details.max_bytes` 또는 오류 메시지의 한도에 맞게 크기를 줄인 후 다시 시도하세요.
413	`request_too_large`	`The request body exceeds the 32 MiB limit. Reduce the request size and try again.`	전체 HTTP 요청 본문이 32 MiB를 초과했습니다. 텍스트, 매개변수 및 인라인 미디어 인코딩을 포함한 실제 전송 본문의 크기를 줄이세요.

크기 제한

미디어 크기: 이미지 작업이 한도를 초과하면 image_too_large, 다른 미디어 작업은 media_too_large를 반환합니다. 동영상 작업에 참조 이미지를 업로드할 때도 media_too_large를 사용합니다. 구체적인 한도는 오류 메시지 또는 error.details.max_bytes를 확인하세요.
전체 요청 크기: request_too_large는 텍스트, 매개변수 및 인라인 미디어 인코딩을 포함한 HTTP 본문이 32 MiB를 초과했음을 의미합니다. URL만 전송하면 링크 자체가 본문에 포함되며, 링크가 가리키는 파일은 모델의 미디어 제한을 충족해야 합니다.
실제 크기: error.details.actual_bytes는 전체 크기가 확인된 경우에만 제공됩니다. URL에서 미디어를 읽다가 읽기 한도에 도달해 중단되면 이 필드가 생략될 수 있습니다.

지원 형식 선택한 모델에 따라 다릅니다. 먼저 error.details.allowed_mime_types 또는 오류 메시지의 형식 목록을 확인하세요. 목록이 없으면 모델의 Schema를 참조하세요. 메시지의 자리표시자

{media_kind}: 실제 미디어 유형입니다. 유형이 확인되면 invalid_media_data 및 media_url_unreachable 메시지에도 image 또는 video가 사용됩니다.
{max_bytes}: 바이트 단위 한도입니다. 이미지 한도를 알 수 없으면 The image is too large. Reduce the image size and try again.을 반환합니다.
{allowed_formats}: 허용되는 형식 목록입니다. 형식 오류 메시지에 Use one of: {allowed_formats}.가 추가될 수 있습니다.

생성 요청 및 반환 결과

HTTP	`code`	`message`	설명
502	`image_not_generated`	`The model provider completed the request but did not return an image. Adjust the request or choose another model, then try again. If the problem persists, contact support with the request ID.`	모델 프로바이더가 요청을 완료했지만 사용 가능한 이미지를 반환하지 않았습니다. 요청을 조정하거나 다른 모델을 선택한 후 다시 시도하세요. 계속 실패하면 요청 ID와 함께 지원팀에 문의하세요. HTTP 502라는 이유만으로 무조건 자동 재생성하지 마세요.
422	`output_blocked`	`The model provider blocked the generated output. Change the prompt or input content and try again.`	모델 프로바이더가 생성된 콘텐츠를 차단했으며 사용 가능한 이미지를 반환하지 않았습니다. 프롬프트 또는 입력 내용을 수정한 후 다시 시도하세요. 이번 생성에는 요금이 부과되지 않습니다.
400	`upstream_rejected`	`The model provider rejected the request. Check the request parameters and content.`	모델 프로바이더가 요청을 거부했습니다. 이 코드만으로 콘텐츠 위반이라고 판단할 수 없습니다. 요청 매개변수와 입력 내용을 확인하고 수정한 후 다시 시도하세요.
502	`upstream_bad_response`	`The model provider response could not be processed. Contact support with the request ID.`	모델 프로바이더가 응답했지만 플랫폼이 처리하지 못했습니다. 생성 결과가 없다고 확인된 것은 아닙니다. 요청 ID와 함께 지원팀에 문의하고, 매개변수 오류나 빈 결과로 임의 판단하지 마세요.
400	`doubao_real_person_required`	`This request uses a real-person image. Complete real-person verification and use an active asset reference. See https://docs.aihubmix.com/cn/api/doubao-real-person-assets.`	Doubao가 실제 인물 이미지의 개인정보 보호와 관련된 특정 거부 코드를 반환했습니다. 실제 인물 인증을 완료하고 활성화된 `asset://` 소재를 사용하세요. 실제 인물 소재 문서를 참조하세요.
504	`sync_timeout`	`Generation did not complete within the waiting period. Contact support with the request ID.`	대기 시간 내에 생성이 완료되지 않았습니다. 시간 초과는 요청이 실행되지 않았음을 증명하지 않습니다. 요청 ID와 함께 지원팀에 문의하세요. 반환받지 않은 작업 ID를 조회하지 마세요.
502	`task_status_unavailable`	`The model provider task state could not be confirmed. Do not submit it again. Contact support with the task ID or request ID.`	작업이 모델 프로바이더에 제출되었지만 이후 상태를 확인할 수 없습니다. 다시 제출하지 마세요. 요청 ID와, 있는 경우 작업 ID를 함께 제공하여 지원팀에 문의하세요.

계정 및 권한

HTTP	`code`	`message`	설명
401	`authentication_failed`	`Authentication failed: invalid or missing API key.`	API Key가 없거나 유효하지 않습니다. `Authorization` 헤더와 API Key를 확인하세요.
402	`insufficient_quota`	`Your account has insufficient quota. Add credits and try again.`	계정 할당량이 부족합니다. 크레딧을 충전한 후 다시 시도하세요.
403	`permission_denied`	`You do not have permission to access this resource. Check the account, API key permissions, and IP restrictions.`	계정 또는 API Key에 접근 권한이 없습니다. 계정 권한, API Key 권한 및 IP 제한을 확인하세요.
403	`async_not_enabled`	`Asynchronous tasks are not enabled. Please go to https://console.aihubmix.com/async-tasks to activate.`	계정에서 비동기 작업 기능을 활성화하지 않았습니다. 응답의 콘솔 링크에서 활성화한 후 다시 시도하세요.

서비스 가용성 및 요청 속도 제한

HTTP	`code`	`message`	설명
429	`rate_limited`	`Too many requests. Reduce the request rate and try again later.`	요청 빈도가 너무 높습니다. 요청 빈도를 낮춘 후 다시 시도하세요.
429	`upstream_rate_limited`	`Upstream service is rate limiting. Please retry later.`	모델 프로바이더가 요청 속도를 제한하고 있습니다. 나중에 다시 시도하고 즉시 반복 제출하지 마세요.
500	`internal_error`	`An internal error occurred. Contact support with the request ID.`	플랫폼 내부 오류가 발생했습니다. 요청 ID와 함께 지원팀에 문의하세요. 올바른 입력을 반복해서 수정할 필요는 없습니다.
502	`upstream_unreachable`	`Upstream service is temporarily unavailable. Please retry.`	모델 프로바이더를 일시적으로 사용할 수 없습니다. 연결 실패, 프로바이더 서비스 오류 또는 응답 읽기 실패가 원인일 수 있습니다. 이 코드만으로 결과 생성 여부를 확인할 수 없습니다. 계속 실패하면 요청 ID와 함께 지원팀에 문의하세요.
502	`provider_unavailable`	`The model provider is unavailable. Contact support with the request or task ID.`	모델 프로바이더를 사용할 수 없습니다. 표에는 기본 메시지를 표시하며 실제 응답에는 더 구체적인 안내가 포함될 수 있습니다. 오류 유형은 `code`로 판단하고 요청 ID와 함께 지원팀에 문의하세요.
503	`model_unavailable`	`The requested model is temporarily unavailable. Try again later or choose another model. If the problem persists, contact support with the request ID.`	현재 모델을 일시적으로 사용할 수 없습니다. 나중에 다시 시도하거나 다른 모델을 선택하세요. 계속 실패하면 요청 ID와 함께 지원팀에 문의하세요.
503	`service_unavailable`	`The service is temporarily unavailable. Try again later. If the problem persists, contact support with the request ID.`	현재 서비스를 일시적으로 사용할 수 없습니다. 나중에 해당 작업을 다시 시도하세요. 다운로드가 실패한 경우 다운로드만 다시 시도하면 되며 재생성할 필요는 없습니다.

provider_unavailable은 모델 프로바이더의 장애가 명확히 확인되었음을 의미합니다. 일반적인 429 또는 4xx만으로 계정 할당량, 콘텐츠 심사 또는 매개변수 문제를 확인할 수 없습니다.

작업 조회 및 결과 다운로드

HTTP	`code`	`message`	설명
404	`task_not_found`	`The task was not found.`	작업이 없거나 조회 권한이 없습니다. 이미지 및 동영상 전용 API는 계정 단위로 소유권을 확인하며, 통합 `/ai/v1/tasks` API는 작업 생성 시 사용한 API Key가 필요합니다. 작업 ID와 인증 정보를 확인하세요.
404	`result_not_found`	`The result was not found.`	결과가 없거나 읽기 권한이 없습니다. 작업 ID, 결과 ID 및 API Key를 확인하세요. 이미 유효하지 않다고 확인된 결과 ID는 작업이 실행 중이라는 이유로 409로 바뀌지 않습니다.
400	`invalid_cursor`	`The cursor is invalid or expired. Start a new list request.`	페이지네이션 커서가 유효하지 않거나 만료되었습니다. `after`를 제거하고 첫 페이지부터 다시 조회한 후 해당 목록에서 반환된 새 커서를 사용하세요.
400	`result_id_required`	`This task has multiple results. Specify result_id.`	작업에 여러 결과가 있지만 `result_id`가 지정되지 않았습니다. 작업 출력에서 결과를 선택하고 해당 `result_id`를 지정하세요.
409	`result_not_ready`	`The result is not available yet. Check the task status before downloading.`	작업이 대기 또는 실행 중이며 결과가 아직 준비되지 않았습니다. 상태 조회를 계속하고 결과가 준비되면 다운로드하세요. 재생성할 필요는 없습니다.
410	`artifact_expired`	`The result has expired and is no longer available. Submit a new generation request.`	결과의 보관 기간이 지났습니다. 만료된 결과는 다운로드할 수 없습니다. 필요한 경우 새 생성 요청을 제출하세요.
429	`too_many_downloads`	`Download limit exceeded for this result.`	다운로드 횟수 제한에 도달했습니다. 이미 저장한 결과를 확인하세요. 기다리기만 한다고 다운로드 횟수가 복구되는 것은 아닙니다.

작업 실행 실패

작업이 생성된 후 발생한 생성 실패는 status=failed와 작업 내 error로 표시됩니다. 조회가 성공하면 HTTP 200을 반환합니다.

{
  "id": "task_01K0ABCDEF",
  "object": "image",
  "status": "failed",
  "output": [],
  "error": {
    "code": "result_delivery_failed",
    "message": "The generated result could not be delivered. Do not resubmit automatically. Contact support with the task ID."
  }
}

Task `code`	`message`	설명
`image_not_generated`	`The model provider completed the request but did not return an image. Adjust the request or choose another model, then submit a new task.`	모델 프로바이더가 요청을 완료했지만 사용 가능한 이미지를 반환하지 않았습니다. 요청을 조정하거나 다른 모델을 선택한 후 새 작업을 제출하세요. 무조건 자동 재생성하지 마세요.
`provider_empty_output`	`The model provider completed the task without a usable result. Adjust the request or choose another model, then submit a new task.`	동영상 또는 다른 미디어 생성이 완료되었으나 사용 가능한 결과가 없음이 확인되었습니다. 요청을 조정하거나 다른 모델을 선택한 후 새 작업을 제출하세요.
`output_blocked`	`The model provider blocked the generated output. Change the prompt or input content and try again.`	모델 프로바이더가 생성된 콘텐츠를 차단했으며 사용 가능한 이미지를 반환하지 않았습니다. 프롬프트 또는 입력 내용을 수정한 후 새 작업을 제출하세요. 이번 생성에는 요금이 부과되지 않습니다.
`output_policy_violation`	`Generated content was rejected by the content policy.`	생성된 콘텐츠가 심사를 통과하지 못했습니다. 프롬프트 또는 입력 내용을 수정한 후 새 작업을 제출하세요. 기존 콘텐츠 심사 과금 규칙이 적용되며 과거 요금은 청구 기록을 확인하세요.
`upstream_rejected`	`The model provider rejected the request. Check the request parameters and content.`	모델 프로바이더가 요청을 거부했습니다. 이 코드만으로 콘텐츠 위반이라고 판단할 수 없습니다. 요청 매개변수와 입력 내용을 확인하고 수정한 후 새 작업을 제출하세요.
`upstream_bad_response`	`The model provider response could not be processed. Contact support with the task ID.`	플랫폼이 모델 프로바이더의 응답을 처리하지 못했습니다. 생성 결과가 없다고 확인된 것은 아닙니다. 작업 ID와 함께 지원팀에 문의하세요.
`task_status_unavailable`	`The model provider task state could not be confirmed. Do not submit it again. Contact support with the task ID.`	작업이 모델 프로바이더에 제출되었지만 이후 상태를 확인할 수 없습니다. 다시 제출하지 말고 작업 ID와 함께 지원팀에 문의하세요.
`result_delivery_failed`	`The generated result could not be delivered. Do not resubmit automatically. Contact support with the task ID.`	생성된 결과가 있지만 플랫폼이 저장 또는 전달을 완료하지 못했습니다. 자동으로 재생성하지 마세요. 작업 ID와 함께 지원팀에 문의하여 기존 결과를 먼저 확인하세요.
`upstream_rate_limited`	`Upstream service is rate limiting. Please retry later.`	모델 프로바이더가 요청 속도를 제한하고 있습니다. 나중에 다시 시도하고 즉시 반복 제출하지 마세요.
`upstream_unreachable`	`Upstream service is temporarily unavailable. Please retry.`	작업 실행 중 모델 프로바이더 연결 실패, 프로바이더 서비스 오류 또는 응답 읽기 실패가 발생했습니다. 이 코드만으로 결과 생성 여부를 확인할 수 없습니다. 계속 실패하면 작업 ID와 함께 지원팀에 문의하세요.
`provider_unavailable`	`The model provider is unavailable. Contact support with the request or task ID.`	모델 프로바이더를 사용할 수 없습니다. 표에는 기본 메시지를 표시하며 실제 응답에는 더 구체적인 안내가 포함될 수 있습니다. 오류 유형은 `code`로 판단하고 작업 ID와 함께 지원팀에 문의하세요.
`doubao_real_person_required`	`This request uses a real-person image. Complete real-person verification and use an active asset reference. See https://docs.aihubmix.com/cn/api/doubao-real-person-assets.`	Doubao가 실제 인물 이미지의 개인정보 보호와 관련된 특정 거부 코드를 반환했습니다. 실제 인물 인증을 완료하고 활성화된 `asset://` 소재를 사용하세요. 실제 인물 소재 문서를 참조하세요.
`sync_timeout`	`Generation timed out. Contact support with the task ID.`	생성 작업 시간이 초과되었습니다. 작업 ID와 함께 지원팀에 문의하세요.
`internal_error`	`An internal error occurred. Contact support with the task ID.`	플랫폼 내부 오류가 발생했습니다. 작업 ID와 함께 지원팀에 문의하세요. 올바른 입력을 반복해서 수정할 필요는 없습니다.

미디어 입력 오류는 실패한 Task에도 나타날 수 있으며 코드의 의미는 위 입력 오류 표와 같습니다. 이 경우에도 조회 성공 시 HTTP 상태는 200입니다. 크기 오류의 message는 submit a new task.로 끝나며 미디어 크기를 줄여 새 작업을 제출하도록 안내합니다. output_blocked는 명확한 차단이 발생했고 사용 가능한 이미지가 반환되지 않았음을 의미하며 이번 생성에는 요금이 부과되지 않습니다. output_policy_violation에는 기존 콘텐츠 심사 과금 규칙이 적용됩니다. 과거 요금은 청구 기록을 확인하세요.

목록의 개별 결과 읽기 실패

이미지 및 동영상 작업 목록의 일부 행에 output_error가 포함될 수 있습니다.

{
  "output_error": {
    "code": "internal_error",
    "type": "server_error",
    "message": "The task output could not be read. Contact support with the request ID.",
    "tid": "req_01K0ABCDEF"
  }
}

이 필드는 이번 조회에서 해당 행의 결과를 읽지 못했음을 의미합니다. 목록은 HTTP 200을 반환하고 해당 행은 output=[]가 됩니다. 기존 id, status, error 및 페이지네이션은 유지되며 정상적으로 읽을 수 있는 다른 작업에는 영향이 없습니다. status=completed여도 output_error를 확인한 후 결과를 읽을 수 있는지 판단하세요. output_error.tid를 제공하여 지원팀에 문의하세요. 해당 필드에 tid가 없으면 현재 응답 헤더의 요청 ID를 제공할 수 있습니다. 이 오류는 작업 상태나 요금을 변경하지 않으며 Webhook을 발생시키지 않습니다. 통합 /ai/v1/tasks 목록의 읽기 실패 행은 expires_at=null을 반환할 수 있지만 결과에는 기존 보관 기간이 그대로 적용됩니다. 이미지 및 동영상 전용 목록은 이미 가져온 만료 시간을 유지합니다. 이 처리는 개별 행의 결과를 읽을 수 없고 사용 가능한 대체 결과도 없는 경우에만 적용됩니다. 통합 tasks API에서 목록 전체 조회가 실패하면 HTTP 오류를 반환하며, 상세 조회에서 같은 장애가 발생하면 HTTP 500을 반환합니다. 관련 문서: 이미지 API · 동영상 API · 비동기 작업

전체 비디오 예시

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 요청 실패

​요청 매개변수 및 미디어 입력

​생성 요청 및 반환 결과

​계정 및 권한

​서비스 가용성 및 요청 속도 제한

​작업 조회 및 결과 다운로드

​작업 실행 실패

​목록의 개별 결과 읽기 실패

​전체 비디오 예시

​자주 묻는 질문

빠른 시작

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

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

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

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

단일 모델의 요청 Schema 조회

지원 모델 및 필드

LLM 중단 복구 모델

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

동기 이미지

비동기 이미지

이미지 표준 필드

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

비디오 표준 필드

미디어 작업 객체

상태 설명

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

미디어 상세 조회

미디어 목록 조회

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

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

이미지 다운로드

비디오 다운로드

Webhook 사용 방법

콜백 요청

재시도 및 중복 제거

LLM 중단 복구 동작 방식

오류 응답 및 오류 코드

HTTP 요청 실패

요청 매개변수 및 미디어 입력

생성 요청 및 반환 결과

계정 및 권한

서비스 가용성 및 요청 속도 제한

작업 조회 및 결과 다운로드

작업 실행 실패

목록의 개별 결과 읽기 실패

전체 비디오 예시

자주 묻는 질문