HTTP 연결을 20–50초 동안 열어 두어야 하는 경우에는 이 API를 사용하십시오. 이미 정상적으로 작동하는 동기식 통합이 있다면 마이그레이션하기 전에
동기식 또는 비동기식 선택을 참조하십시오.
엔드포인트
생성 시 경로는 복수형이고 조회 시에는 단수형이라는 점에 유의하십시오. 목록 조회, 취소 또는 삭제 엔드포인트는 없습니다.
작업 생성
요청 본문은 항상 동일한 세 키로 구성된 엔벌로프입니다.model, input 및 선택 사항인 callback_url입니다.
엔벌로프 필드
현재 엔벌로프 수준의 알 수 없는 키는 허용되고 무시됩니다. 하지만 이에
의존하지 말고 생성 매개변수를 해당 위치에 넣지 마십시오. 생성 매개변수는
input에
포함해야 합니다.
input 객체
input에는 생성 매개변수가 포함되며, 허용되는 필드는 모델에 따라 다릅니다. 엔벌로프는
고정되어 있지만 내부 내용은 고정되어 있지 않습니다.
input 내부의 유효성 검사는 엄격하게 수행됩니다. 모델이 인식하지 못하는 키는 모두
즉시 거부되므로 오타를 조용히 넘어가지 않고 명확하게 확인할 수 있습니다.
Nano Banana 시리즈
전체 필드 목록, 해상도 등급, 가로세로 비율 및 이미지 편집입니다.
결과 폴링
작업 필드
작업이 진행됨에 따라 응답이 확장됩니다. 작업이 아직 실행 중인 동안에는
outputs 및 expires_at가
단순히 존재하지 않습니다. 고정된 형태를 가정하지 말고 필드를 방어적으로 읽으며,
먼저 status를 기준으로 분기하십시오.
상태 흐름
얼마나 기다려야 하는가
제출에는 1초 미만이 걸리며 부하가 걸려도 이 수준을 유지합니다. 동시 실행 수 12로 30개 작업을 처리했을 때 측정된 p50은 0.88초, p95는 0.92초였습니다. 실제 시간은 생성에 소요됩니다. 모델과 해상도에 따라 대략 12출력 다운로드
outputs에는 서명이나 쿼리 문자열이 없는 일반 https URL이 포함되어 있으며, API와 호스트 이름이 다른 WideRouter의 전송 CDN에서 제공됩니다. 이에 따라 다음 두 가지 사항이 적용됩니다.
1
인증되지 않습니다
API 키를 전송하지 말고 URL 자체를 비밀로 취급해야 합니다.
링크를 보유한 사람은 링크가 유효한 동안 이미지를 가져올 수 있습니다.
2
24시간 후 만료됩니다
expires_at는 항상 created_at에 86400을 더한 값입니다. 보관해야 하는 항목은
자체 스토리지에 복사하십시오. 출력 URL을 영구 참조로 저장하지 마십시오.1K에서 약 0.4–0.7MB, 2K에서 2.4–3.0MB, 4K에서 7.5–8.2MB입니다.
파일 확장자를 추정하지 말고 응답에서 Content-Type을 읽으십시오.
콜백
생성 시callback_url를 설정하면 WideRouter가 완료된 작업을 해당 주소로 게시하므로,
폴링을 완전히 건너뛸 수 있습니다.
https이어야 합니다. 그 외의 값 — http, 단순 호스트 이름, 문자열이 아닌 값 —
은 제출 시점에 invalid_callback_url와 함께 거부되므로, 오타가 조용히 전달되지 않는 대신 즉시 실패합니다.
WideRouter는 작업 객체를 application/json로 게시하며, 본문을 파싱하기 전에 라우팅에 사용할 수 있는
헤더를 함께 전송합니다.
본문은 해당 시점에
GET /v1/task/{task_id}이 반환하는 내용과 바이트 단위로 동일합니다 —
필드와 값이 모두 동일하므로 하나의 핸들러로 두 경로를 모두 처리할 수 있습니다.
테스트에서는 전달이 즉시 이루어졌습니다. 세 작업의 콜백이 모두 작업이
completed에 도달한 후 1초 이내에 도착했습니다. 엔드포인트가 5xx로 응답하면
WideRouter가 재시도하며, 관찰된 시도 시점은 대략 0초, 10초, 70초였습니다.
콜백은 전달을 보장하는 기능이 아니라 지연 시간을 줄이기 위한 최적화입니다. 콜백이 도착하지 않는
작업에 대비해 폴링 대체 경로를 유지하고, 핸들러를 멱등적으로 구현하십시오. 재시도로 인해 동일한
작업이 두 번 이상 도착할 수 있으므로 작업
id를 기준으로 처리해야 합니다.작업이 실패하는 경우
failed 작업은 읽기 엔드포인트에서 여전히 200입니다. 실패는 HTTP 상태가
아니라 본문에 있습니다.
outputs도 없고 expires_at도 없다는 점에 유의하십시오. 입력 가져오기 실패는 모델 작업이
시작되기 전에 발생하므로 빠르게 처리되며, 1초 이내입니다.
제출 시 오류
어떤 항목도 대기열에 추가되기 전에 검증이 수행되므로, 여기서400이 발생해도 비용이 들지 않습니다.
오류는 한 번에 하나의 필드를 가리키며,
param은 배열 인덱스(input.images[0])를 포함한 전체 경로를 사용하므로 오류를 요청에 바로 매핑할 수 있습니다.
여기에서 작동하는 모델
모델 ID는 정확히 일치해야 합니다. 별칭은 없으며,-preview 접미사가 붙은
이름은 허용되지 않습니다. 비동기 API에서 제공하지 않는 ID를 전송하면 대기열에
추가되기 전에 제출 시점에 model_not_supported가 반환됩니다.
Nano Banana 시리즈
Google의 이미지 모델 — 각 환경에서의 사용 가능 여부, 매개변수 및 측정된 지연 시간입니다.
동기 또는 비동기 선택
두 방식 모두 제공되며 어느 쪽도 더 이상 사용되지 않는 방식이 아닙니다.
서버리스 함수, 리버스 프록시 또는 모바일 클라이언트 뒤에서 실행되는 작업에는 비동기 방식이 기본 선택으로 더 적합합니다. 이러한 환경은 50초 동안의 요청을 안정적으로 유지하지 못하기 때문입니다. 단순히 바이트를 반환받으려는 스크립트에는 동기 호출이 여전히 더 간단합니다.
다음 단계
Nano Banana 시리즈
매개변수 매트릭스, 해상도 등급 및 두 모델의 차이점입니다.
빠른 시작
약 5분 안에 전체 과정을 처음부터 끝까지 진행합니다.