Skip to main content
비디오 생성이나 배치 이미지 생성 같은 요청은 일반적으로 한 번의 HTTP 연결에서 기다릴 수 있는 합리적인 시간을 넘깁니다. 또한 장문 생성 도중 클라이언트 연결이 끊기면 이미 생성된 응답도 다시 가져올 수 없습니다. 비동기 작업(Async Tasks)은 이 세 가지 시나리오를 동일한 작업 객체로 통합합니다. 이미지와 비디오는 생성 API로 작업을 만들고 즉시 task_id를 반환받으며, 클라이언트가 중단한 LLM 요청은 플랫폼이 계속 처리하여 최종 응답을 저장합니다. 세 가지 모두 동일한 작업 상태, 조회 API, 결과 다운로드 절차를 공유합니다.
작업을 생성할 때 사용한 것과 동일한 API Key로 작업을 조회하고 결과를 다운로드하세요. 작업은 API Key 단위로 격리되며, 두 Key가 같은 계정에 속하더라도 서로의 작업을 읽을 수 없습니다.

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

비동기 이미지 또는 비디오를 생성하기 전에 현재 계정에서 비동기 작업 기능을 먼저 활성화하세요. 콘솔에 해당 항목이 아직 표시되지 않으면 AIHubMix 기술 지원에 문의하세요.
비동기 작업 기능이 활성화되지 않은 상태에서는 미디어 작업 생성 요청이 403 async_not_enabled를 반환합니다. LLM 요청은 이로 인해 오류가 발생하지는 않지만, 클라이언트가 중단된 후 최종 응답을 되찾을 수 없습니다.

1. 빠른 시작

이미지와 비디오 비동기 작업의 전체 프로세스는 세 단계로 나뉩니다.

2. 동기 호출 vs 비동기 작업 비교

동기 호출은 한 번의 HTTP 응답 안에서 결과를 반환하며, 연결이 끊기면 결과를 다시 찾을 수 없습니다. 비동기 작업은 결과를 플랫폼 측에 저장하므로, 결과가 만료되기 전까지 동일한 API Key로 task_id를 다시 조회하고 다운로드할 수 있습니다. 시간이 오래 걸리는 생성 요청과, 중단 후 최종 응답을 회수해야 하는 장문 출력에 적합합니다.

3. API 개요

Base URL: https://aihubmix.com, 인증 방식은 Bearer Token 입니다.
/ai/v1/tasks는 읽기 전용 통합 조회 엔드포인트이며, POST /ai/v1/tasks는 제공하지 않습니다. 이미지와 비디오는 각각 대응하는 생성 API로 만듭니다. LLM 중단 복구 조건을 충족하는 요청은 클라이언트 중단 후 자동으로 llm 작업으로 기록됩니다.

4. 지원 모델

비동기 작업은 작업 유형별로 지원 범위가 나뉘며, 호출 시 추가 파라미터가 필요 없습니다.

4.1 비동기 이미지

4.2 비동기 비디오

4.3 LLM 중단 복구

지원 범위는 계속 확대되며, 이 표도 함께 업데이트됩니다.

5. 비동기 작업을 생성하는 방법

5.1 비동기 이미지

이미지 API는 기본적으로 동기 반환입니다. asynctrue로 설정하면 API가 즉시 작업 객체를 반환하고, 생성 과정은 백그라운드에서 계속 실행됩니다.
async는 불리언 값이어야 합니다. 전달하지 않거나 false로 설정하면 이미지 API는 동기 동작을 유지합니다.

5.2 비동기 비디오

비디오 API는 항상 비동기입니다. 생성에 성공하면 pending 또는 in_progress 상태를 반환하며, Prefer: wait로 동기 대기로 변경하는 방식은 지원하지 않습니다.

5.3 공통 파라미터

예시의 model, prompt, n, seconds, size는 일반적인 모델 파라미터이며, 각 모델이 지원하는 필드와 값은 해당 모델의 API 문서를 기준으로 합니다. 비디오 모델은 비디오 생성 문서를 참조하세요. 아래 표는 모든 비동기 작업이 공통으로 사용하는 파라미터만 설명합니다.
이미지 작업은 async: true일 때만 Webhook을 사용할 수 있습니다. webhook_events_filter를 생략하면 플랫폼이 completed, failed, cancelled 세 가지 최종 상태를 모두 푸시합니다. 전달할 때는 반드시 webhook_url과 함께 사용해야 하며, 비어 있거나 중복되어서는 안 됩니다.

6. LLM 중단 복구가 동작하는 방법

LLM 중단 복구는 클라이언트 연결이 끊긴 후의 최종 응답을 회수하는 데 사용합니다. 이 기능은 기존 LLM 요청 방식을 그대로 활용하며, 스트리밍 동작과 응답 형식은 변하지 않습니다. 별도의 생성 API를 호출할 필요가 없고, task_id도 미리 반환되지 않습니다.

6.1 적용 조건

다음 조건을 모두 충족해야 합니다. 지원되는 API:
호출 시 추가 필드를 전달할 필요가 없습니다. 지원 범위는 4.3 LLM 중단 복구를 참조하세요. 표에 없는 모델은 정식 연동 전에 저비용 요청 한 건으로 중단 복구를 검증할 수 있으며, 검증 요청도 정상적으로 과금됩니다. 조건 중 하나라도 충족되지 않으면 요청은 그대로 정상 실행되며, 클라이언트 중단 후 llm 작업이 생성되지 않습니다.

6.2 중단 후 실행 흐름

정상적으로 완료되어 클라이언트에 성공적으로 반환된 LLM 요청은 작업을 생성하지 않으며, 작업 목록에도 나타나지 않습니다. 중단된 요청은 최종 응답 저장이 완료된 후 목록에 나타나므로, 처리 중에는 일시적으로 조회되지 않을 수 있습니다.

6.3 해당 중단 요청 찾기

LLM 응답 헤더는 X-Aihubmix-Request-Id를 반환합니다. 클라이언트는 응답 헤더를 받으면 즉시 이 값을 저장해야 하며, 중단이 발생한 후 AIHubMix 콘솔의 비동기 작업 목록에서 이 요청 ID로 해당 작업을 찾을 수 있습니다. 공개 작업 API는 현재 요청 ID 기준 필터링을 지원하지 않습니다. 요청 ID를 저장하지 않은 경우, 요청을 생성할 때 사용한 것과 동일한 API Key로 모델과 생성 시간을 기준으로만 찾을 수 있습니다.
동일한 API Key로 같은 모델의 요청을 여러 개 동시에 보내는 경우, 모델과 생성 시간만으로는 정확한 대응을 보장할 수 없습니다. 안정적인 복구가 필요하면 X-Aihubmix-Request-Id를 저장하고 콘솔에서 찾으세요. 응답 헤더를 확보하지 못했다면 목록의 최신 작업을 이번 요청으로 단정하는 것은 피해야 합니다.
LLM 중단 복구 작업은 현재 Webhook을 전송하지 않으므로 작업 목록에서 결과를 조회하세요. 클라이언트 중단은 플랫폼의 요청 처리를 멈추지 않으며, 해당 호출은 기존 LLM API 규칙에 따라 과금됩니다.

7. 작업 객체와 상태

모든 작업은 통합된 응답 구조를 사용합니다.
output 안의 결과 필드:

7.1 상태 설명

15초마다 한 번씩 조회하여 상태가 completed, failed 또는 cancelled로 바뀔 때까지 확인하는 것을 권장합니다.
failed 또는 cancelled 작업에도 이미 생성된 일부 결과가 포함될 수 있습니다. 결과 유무를 판단할 때는 상태 외에 output이 비어 있는지도 확인해야 합니다.

8. 작업을 조회하는 방법

8.1 작업 상세 조회

이 API는 조회 시점의 최신 작업 정보를 반환합니다. 조회 동작은 작업을 변경하지 않으며, 작업 상태는 플랫폼이 자동으로 갱신합니다.

8.2 작업 목록 조회

생성 응답을 잃어버렸거나 과거 작업을 한꺼번에 확인해야 할 때는 목록 API로 task_id를 다시 찾을 수 있습니다.
응답 예시:
다음 페이지를 이어서 요청하기:

9. 작업 결과를 가져오는 방법

9.1 단일 결과물 작업

output에 파일이 하나만 있으면 바로 접근할 수 있습니다.
output[0].content_url을 직접 사용해도 됩니다. 다운로드 응답의 Content-Typeoutput[0].content_type과 동일합니다.

9.2 다중 결과물 작업

output에 파일이 여러 개 포함된 경우 해당 result_id를 반드시 지정해야 합니다.
다중 결과물 작업에서 result_id를 지정하지 않으면 API는 400 result_id_required를 반환합니다.

9.3 LLM 응답 작업

LLM 중단 복구 조건을 충족하여 응답이 저장되면, 작업의 objectllm이고 output 항목의 typeresponse입니다. 콘텐츠 유형은 다음과 같을 수 있습니다.
  • application/json: 일반 JSON 응답
  • text/event-stream: 저장된 SSE 스트리밍 응답
잘림 표시는 작업 상세의 output[0].truncated에 있습니다. 값이 true이면 저장된 응답이 크기 제한으로 잘렸음을 의미합니다. GET /ai/v1/tasks/{task_id}/content는 원본 JSON 또는 SSE 콘텐츠를 반환하며 콘텐츠 외부에 truncated 필드를 감싸지 않으므로, 작업 상세를 먼저 조회한 후 콘텐츠를 읽어야 합니다.
결과는 만료될 수 있고 다운로드 횟수 제한이 있을 수 있습니다. expires_at 이전에 저장하세요. 만료 시 410 artifact_expired, 다운로드 횟수 제한 초과 시 429 too_many_downloads를 반환합니다.

10. Webhook을 사용하는 방법

현재 비동기 작업 생성 시 작업 단위 Webhook 제출을 지원합니다. 작업 완료 후 AIHubMix가 능동적으로 통지하도록 하려면 비동기 이미지 또는 비디오 요청 본문에 webhook_url과 선택 항목인 webhook_events_filter를 전달하세요.
콜백 주소는 HTTPS를 사용해야 하며, 로컬 호스트, 사설망 또는 기타 제한된 주소를 가리킬 수 없습니다.

10.1 콜백 요청

AIHubMix는 콜백 주소로 POST 요청을 전송합니다.
results의 URL도 작업 생성 시 사용한 API Key를 함께 전달해야 접근할 수 있습니다.

10.2 재시도와 중복 제거

플랫폼은 콜백을 최소 한 번 전달하려고 시도하므로, 동일한 이벤트가 중복 전송될 수 있습니다.
  • HTTP 2xx는 수신 성공을 의미합니다.
  • HTTP 5xx, 네트워크 오류 또는 타임아웃은 재시도를 유발합니다.
  • HTTP 3xx4xx는 재시도하지 않습니다.
  • 최대 6회 전달하며, 재시도 간격은 순서대로 1, 4, 16, 64, 256초입니다.
수신 측은 event_id를 저장해야 합니다. 동일한 event_id를 다시 수신하면 비즈니스 로직을 건너뛰고 바로 2xx를 반환하세요.
현재 작업 단위 Webhook은 별도로 구성 가능한 서명 자격 증명을 제공하지 않습니다. 통지를 받은 후에는 작업 생성 시 사용한 API Key로 GET /ai/v1/tasks/{task_id}를 요청하여 조회 결과를 기준으로 삼아야 합니다.

11. 오류 응답과 오류 코드

오류 응답은 통합된 구조를 사용합니다.

12. 전체 예제

비디오 작업 생성, 상태 폴링, 전체 결과 다운로드까지의 전체 프로세스입니다.

자주 묻는 질문 (FAQ)

작업 상태는 얼마나 자주 조회하는 것이 좋나요? 15초마다 한 번씩 조회하고 고빈도 폴링은 피하는 것을 권장합니다. Webhook을 사용할 때도 저빈도 조회를 예비 수단으로 유지하는 것이 좋습니다. 생성 응답을 잃어버린 후 작업을 어떻게 찾나요? 작업을 생성할 때 사용한 것과 동일한 API Key로 GET /ai/v1/tasks를 요청하면 되며, object, model, status로 범위를 좁힐 수 있습니다. 같은 계정의 다른 API Key로는 왜 작업이 조회되지 않나요? 작업은 API Key 단위로 격리됩니다. 조회, 다운로드, 목록 요청 모두 작업을 생성할 때 사용한 것과 동일한 Key를 사용해야 합니다. 작업이 실패했는데 output이 빈 배열이 아닌 이유는 무엇인가요? 일부 모델은 전체 실패 또는 취소 전에 이미 사용 가능한 결과를 생성했을 수 있습니다. outputcontent_url 또는 b64_json이 있으면 해당 방식으로 획득할 수 있습니다. Webhook을 받지 못하면 어떻게 하나요? 콜백 주소가 공개적으로 접근 가능하고 HTTPS를 사용하며 10초 이내에 2xx를 반환하는지 확인하세요. Webhook 사용 여부와 관계없이 GET /ai/v1/tasks/{task_id}로 최종 상태를 조회할 수 있습니다. LLM 중단 복구를 위해 기존 코드를 수정해야 하나요? 필요 없습니다. 요청 방식, 스트리밍 동작, 응답 형식은 그대로 유지됩니다. 중단 후 콘솔에서 해당 작업을 정확히 찾을 수 있도록 응답 헤더 X-Aihubmix-Request-Id를 저장하는 것을 권장합니다.
마지막 업데이트: 2026-07-28