이미지 생성

빠른 시작

네이티브 이미지 엔드포인트는 기본적으로 동기입니다. Boolean async를 true로 설정하면 백그라운드 작업을 만듭니다. 예제는 qwen-image-2.0을 사용합니다.

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",
    "async": true
  }'

{
  "id": "task_01K0ABCDEF",
  "object": "image",
  "model": "qwen-image-2.0",
  "status": "in_progress",
  "output": [],
  "error": null,
  "created_at": 1784707200,
  "completed_at": null,
  "expires_at": null
}

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

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

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

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

동기 이미지

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	아니요	특정 모델의 확장 파라미터

미디어 작업 객체

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

{
  "id": "task_01K0ABCDEF",
  "object": "image",
  "model": "qwen-image-2.0",
  "status": "completed",
  "output": [
    {
      "index": 0,
      "type": "file",
      "b64_json": null,
      "content_url": "https://aihubmix.com/ai/v1/images/task_01K0ABCDEF/content/result_01K0XYZ"
    }
  ],
  "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/images/{task_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

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

미디어 목록 조회

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

curl "https://aihubmix.com/ai/v1/images?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": "image",
      "model": "qwen-image-2.0",
      "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=image&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": "image/png",
  "content_url": "https://aihubmix.com/ai/v1/tasks/task_01K0ABCDEF/content/result_01K0XYZ"
}

단일 결과물은 /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 디코딩할 수 있습니다.

Webhook 사용 방법

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

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 tranquil garden at sunrise",
    "n": 1,
    "async": true,
    "size": "1024x1024",
    "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": "qwen-image-2.0",
    "results": [
      {
        "url": "https://aihubmix.com/ai/v1/tasks/task_01K0ABCDEF/content/result_01K0XYZ"
      }
    ]
  }
}

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

오류 응답 및 오류 코드

이 절은 /ai/v1/images/* 및 이미지 작업에 적용됩니다. 동영상 오류는 동영상 API를 참조하세요.

현재 요청 실패: 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	`request_too_large`	`The request body exceeds the 32 MiB limit. Reduce the request size and try again.`	전체 HTTP 요청 본문이 32 MiB를 초과했습니다. 텍스트, 매개변수 및 인라인 미디어 인코딩을 포함한 실제 전송 본문의 크기를 줄이세요.

크기 제한

미디어 크기: 이미지 작업이 한도를 초과하면 image_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.`	작업이 없거나 현재 계정에 속하지 않습니다. 작업 ID를 확인하고 API Key가 작업을 생성한 계정에 속하는지 확인하세요.
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": "image_not_generated",
    "message": "The model provider completed the request but did not return an image. Adjust the request or choose another model, then submit a new task."
  }
}

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.`	모델 프로바이더가 요청을 완료했지만 사용 가능한 이미지를 반환하지 않았습니다. 요청을 조정하거나 다른 모델을 선택한 후 새 작업을 제출하세요. 무조건 자동 재생성하지 마세요.
`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을 발생시키지 않습니다. 이미지 및 동영상 목록은 이미 가져온 expires_at을 유지합니다. 통합 /ai/v1/tasks 목록의 읽기 실패 행은 expires_at=null을 반환할 수 있지만 결과에는 기존 보관 기간이 그대로 적용됩니다. 이 처리는 개별 행의 결과를 읽을 수 없고 사용 가능한 대체 결과도 없는 경우에만 적용됩니다. 통합 tasks API에서 목록 전체 조회가 실패하면 HTTP 오류를 반환하며, 상세 조회에서 같은 장애가 발생하면 HTTP 500을 반환합니다. 관련 문서: 이미지 API · 동영상 API · 비동기 작업

전체 예제

비동기 작업을 만들고 폴링한 뒤 반환된 이미지를 모두 저장합니다.

import base64
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/images/generations",
    headers=headers,
    json={
        "model": "qwen-image-2.0",
        "prompt": "A flower shop with delicate windows, warm sunlight streaming in",
        "n": 1,
        "size": "1024x1024",
        "async": True,
    },
    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/images/{task['id']}",
        headers=headers,
        timeout=30,
    )
    response.raise_for_status()
    task = response.json()

if task["status"] != "completed":
    raise RuntimeError(task.get("error") or task["status"])

for output in task["output"]:
    filename = f"result-{output['index']}.png"
    if output.get("b64_json"):
        content = base64.b64decode(output["b64_json"])
    else:
        result = requests.get(output["content_url"], headers=headers, timeout=120)
        result.raise_for_status()
        content = result.content
    with open(filename, "wb") as file:
        file.write(content)

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/images/generations`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    model: "qwen-image-2.0",
    prompt: "A flower shop with delicate windows, warm sunlight streaming in",
    n: 1,
    size: "1024x1024",
    async: true,
  }),
});
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/images/${task.id}`, { headers });
  if (!polled.ok) throw new Error(await polled.text());
  task = await polled.json();
}

if (task.status !== "completed") {
  throw new Error(JSON.stringify(task.error ?? task.status));
}

for (const output of task.output) {
  let content;
  if (output.b64_json) {
    content = Buffer.from(output.b64_json, "base64");
  } else {
    const result = await fetch(output.content_url, { headers });
    if (!result.ok) throw new Error(await result.text());
    content = Buffer.from(await result.arrayBuffer());
  }
  await writeFile(`result-${output.index}.png`, content);
}

시작하기

게이트웨이 기능

모델 기능

프로토콜 참조

플랫폼 관리

빠른 시작

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

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

단일 모델의 요청 Schema 조회

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

동기 이미지

비동기 이미지

이미지 표준 필드

미디어 작업 객체

상태 설명

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

미디어 상세 조회

미디어 목록 조회

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

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

이미지 다운로드

Webhook 사용 방법

콜백 요청

재시도 및 중복 제거

오류 응답 및 오류 코드

HTTP 5xx 오류 신고

HTTP 요청 실패

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

생성 요청 및 반환 결과

계정 및 권한

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

작업 조회 및 결과 다운로드

작업 실행 실패

목록의 개별 결과 읽기 실패

전체 예제

​빠른 시작

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

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

​단일 모델의 요청 Schema 조회

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

​동기 이미지

​비동기 이미지

​이미지 표준 필드

​미디어 작업 객체

​상태 설명

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

​미디어 상세 조회

​미디어 목록 조회

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

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

​이미지 다운로드

​Webhook 사용 방법

​콜백 요청

​재시도 및 중복 제거

​오류 응답 및 오류 코드

HTTP 5xx 오류 신고

​HTTP 요청 실패

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

​생성 요청 및 반환 결과

​계정 및 권한

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

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

​작업 실행 실패

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

​전체 예제

빠른 시작

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

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

단일 모델의 요청 Schema 조회

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

동기 이미지

비동기 이미지

이미지 표준 필드

미디어 작업 객체

상태 설명

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

미디어 상세 조회

미디어 목록 조회

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

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

이미지 다운로드

Webhook 사용 방법

콜백 요청

재시도 및 중복 제거

오류 응답 및 오류 코드

HTTP 요청 실패

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

생성 요청 및 반환 결과

계정 및 권한

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

작업 조회 및 결과 다운로드

작업 실행 실패

목록의 개별 결과 읽기 실패

전체 예제