task_id를 반환받으며, 클라이언트가 중단한 LLM 요청은 플랫폼이 계속 처리하여 최종 응답을 저장합니다. 세 가지 모두 동일한 작업 상태, 조회 API, 결과 다운로드 절차를 공유합니다.
작업을 생성할 때 사용한 것과 동일한 API Key로 작업을 조회하고 결과를 다운로드하세요. 작업은 API Key 단위로 격리되며, 두 Key가 같은 계정에 속하더라도 서로의 작업을 읽을 수 없습니다.
콘솔에서 비동기 작업 활성화하기
비동기 이미지 또는 비디오를 생성하기 전에 현재 계정에서 비동기 작업 기능을 먼저 활성화하세요. 콘솔에 해당 항목이 아직 표시되지 않으면 AIHubMix 기술 지원에 문의하세요.
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는 기본적으로 동기 반환입니다.async를 true로 설정하면 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 중단 후 실행 흐름
6.3 해당 중단 요청 찾기
LLM 응답 헤더는X-Aihubmix-Request-Id를 반환합니다. 클라이언트는 응답 헤더를 받으면 즉시 이 값을 저장해야 하며, 중단이 발생한 후 AIHubMix 콘솔의 비동기 작업 목록에서 이 요청 ID로 해당 작업을 찾을 수 있습니다.
공개 작업 API는 현재 요청 ID 기준 필터링을 지원하지 않습니다. 요청 ID를 저장하지 않은 경우, 요청을 생성할 때 사용한 것과 동일한 API Key로 모델과 생성 시간을 기준으로만 찾을 수 있습니다.
7. 작업 객체와 상태
모든 작업은 통합된 응답 구조를 사용합니다.output 안의 결과 필드:
7.1 상태 설명
15초마다 한 번씩 조회하여 상태가
completed, failed 또는 cancelled로 바뀔 때까지 확인하는 것을 권장합니다.
failed 또는 cancelled 작업에도 이미 생성된 일부 결과가 포함될 수 있습니다. 결과 유무를 판단할 때는 상태 외에 output이 비어 있는지도 확인해야 합니다.8. 작업을 조회하는 방법
8.1 작업 상세 조회
8.2 작업 목록 조회
생성 응답을 잃어버렸거나 과거 작업을 한꺼번에 확인해야 할 때는 목록 API로task_id를 다시 찾을 수 있습니다.
응답 예시:
다음 페이지를 이어서 요청하기:
9. 작업 결과를 가져오는 방법
9.1 단일 결과물 작업
output에 파일이 하나만 있으면 바로 접근할 수 있습니다.
output[0].content_url을 직접 사용해도 됩니다. 다운로드 응답의 Content-Type은 output[0].content_type과 동일합니다.
9.2 다중 결과물 작업
output에 파일이 여러 개 포함된 경우 해당 result_id를 반드시 지정해야 합니다.
result_id를 지정하지 않으면 API는 400 result_id_required를 반환합니다.
9.3 LLM 응답 작업
LLM 중단 복구 조건을 충족하여 응답이 저장되면, 작업의object는 llm이고 output 항목의 type은 response입니다. 콘텐츠 유형은 다음과 같을 수 있습니다.
application/json: 일반 JSON 응답text/event-stream: 저장된 SSE 스트리밍 응답
output[0].truncated에 있습니다. 값이 true이면 저장된 응답이 크기 제한으로 잘렸음을 의미합니다. GET /ai/v1/tasks/{task_id}/content는 원본 JSON 또는 SSE 콘텐츠를 반환하며 콘텐츠 외부에 truncated 필드를 감싸지 않으므로, 작업 상세를 먼저 조회한 후 콘텐츠를 읽어야 합니다.
10. Webhook을 사용하는 방법
현재 비동기 작업 생성 시 작업 단위 Webhook 제출을 지원합니다. 작업 완료 후 AIHubMix가 능동적으로 통지하도록 하려면 비동기 이미지 또는 비디오 요청 본문에webhook_url과 선택 항목인 webhook_events_filter를 전달하세요.
10.1 콜백 요청
AIHubMix는 콜백 주소로POST 요청을 전송합니다.
results의 URL도 작업 생성 시 사용한 API Key를 함께 전달해야 접근할 수 있습니다.
10.2 재시도와 중복 제거
플랫폼은 콜백을 최소 한 번 전달하려고 시도하므로, 동일한 이벤트가 중복 전송될 수 있습니다.- HTTP
2xx는 수신 성공을 의미합니다. - HTTP
5xx, 네트워크 오류 또는 타임아웃은 재시도를 유발합니다. - HTTP
3xx와4xx는 재시도하지 않습니다. - 최대 6회 전달하며, 재시도 간격은 순서대로 1, 4, 16, 64, 256초입니다.
event_id를 저장해야 합니다. 동일한 event_id를 다시 수신하면 비즈니스 로직을 건너뛰고 바로 2xx를 반환하세요.
11. 오류 응답과 오류 코드
오류 응답은 통합된 구조를 사용합니다.12. 전체 예제
비디오 작업 생성, 상태 폴링, 전체 결과 다운로드까지의 전체 프로세스입니다.자주 묻는 질문 (FAQ)
작업 상태는 얼마나 자주 조회하는 것이 좋나요? 15초마다 한 번씩 조회하고 고빈도 폴링은 피하는 것을 권장합니다. Webhook을 사용할 때도 저빈도 조회를 예비 수단으로 유지하는 것이 좋습니다. 생성 응답을 잃어버린 후 작업을 어떻게 찾나요? 작업을 생성할 때 사용한 것과 동일한 API Key로GET /ai/v1/tasks를 요청하면 되며, object, model, status로 범위를 좁힐 수 있습니다.
같은 계정의 다른 API Key로는 왜 작업이 조회되지 않나요?
작업은 API Key 단위로 격리됩니다. 조회, 다운로드, 목록 요청 모두 작업을 생성할 때 사용한 것과 동일한 Key를 사용해야 합니다.
작업이 실패했는데 output이 빈 배열이 아닌 이유는 무엇인가요?
일부 모델은 전체 실패 또는 취소 전에 이미 사용 가능한 결과를 생성했을 수 있습니다. output에 content_url 또는 b64_json이 있으면 해당 방식으로 획득할 수 있습니다.
Webhook을 받지 못하면 어떻게 하나요?
콜백 주소가 공개적으로 접근 가능하고 HTTPS를 사용하며 10초 이내에 2xx를 반환하는지 확인하세요. Webhook 사용 여부와 관계없이 GET /ai/v1/tasks/{task_id}로 최종 상태를 조회할 수 있습니다.
LLM 중단 복구를 위해 기존 코드를 수정해야 하나요?
필요 없습니다. 요청 방식, 스트리밍 동작, 응답 형식은 그대로 유지됩니다. 중단 후 콘솔에서 해당 작업을 정확히 찾을 수 있도록 응답 헤더 X-Aihubmix-Request-Id를 저장하는 것을 권장합니다.
마지막 업데이트: 2026-07-28