빠른 시작
Comfy 워크스페이스에서 키를 생성하고COMFY_API_KEY로 내보내세요. Python과 TypeScript 스니펫은 Comfy SDK(pip install comfy-sdk, npm install @comfyorg/sdk)를 사용하며, cURL 스니펫은 동일한 호출을 원시 HTTP로 수행합니다.
모델 ID: vertexai/gemini-3.1-flash-image
엔드포인트: POST https://api.comfy.org/v2/models/vertexai/gemini-3.1-flash-image
- 결과 기다리기
- 대기열에 넣고 나중에 수집
동일한 본문을
POST https://api.comfy.org/v2/models/vertexai/gemini-3.1-flash-image/requests로 전송합니다. Router는 실행이 접수되는 즉시 request_id와 함께 201로 응답하며, 결과는 준비가 되면 이 프로세스 또는 다른 프로세스에서 수집합니다. 큐 전송에서 상태, 취소, 수집 과정을 자세히 다룹니다.제공 공급자
이 모델은 요청에서 다른 공급자를 지정하지 않는 한 Comfy Router가 직접 제공합니다. 아래 공급자들도 동일한 엔드포인트와 동일한 모델 ID로 이 모델을 제공하며,model_provider 쿼리 매개변수로 선택합니다.
- Comfy(기본값):
POST https://api.comfy.org/v2/models/vertexai/gemini-3.1-flash-image - fal,
fal/fal-nano-banana-2로:POST https://api.comfy.org/v2/models/vertexai/gemini-3.1-flash-image?model_provider=fal - MiniMax,
minimax/minimax-nano-banana-2로:POST https://api.comfy.org/v2/models/vertexai/gemini-3.1-flash-image?model_provider=minimax - Pika,
pika/pika-nano-banana-2로:POST https://api.comfy.org/v2/models/vertexai/gemini-3.1-flash-image?model_provider=pika - Runware,
runware/runware-nano-banana-2로:POST https://api.comfy.org/v2/models/vertexai/gemini-3.1-flash-image?model_provider=runware - WaveSpeed,
wavespeed/wavespeed-nano-banana-2로:POST https://api.comfy.org/v2/models/vertexai/gemini-3.1-flash-image?model_provider=wavespeed
strict_mode의 기본값은 false이므로, Router는 이 페이지에 문서화된 네이티브 요청 본문을 공급자 자체 스키마로 변환하고 응답을 다시 변환합니다. API 레퍼런스의 model_provider, strict_mode, fallback_provider와 이렇게 라우팅되는 모든 모델을 다루는 제공 공급자를 참조하세요.
스키마
입력
data 또는 fileUri 필드에 지정된 파일의 미디어 유형입니다. 허용되는 값은 다음과 같습니다. gemini-2.0-flash-lite 및 gemini-2.0-flash의 경우 오디오 파일의 최대 길이는 8.4시간이고 비디오 파일(오디오 없음)의 최대 길이는 1시간입니다. 자세한 내용은 Gemini 오디오 및 비디오 요구 사항을 참조하세요. 텍스트 파일은 UTF-8로 인코딩되어야 합니다. 텍스트 파일의 내용은 토큰 제한에 포함됩니다. 이미지 해상도에는 제한이 없습니다.가능한 값:
application/pdf, audio/mpeg, audio/mp3, audio/wav, image/png, image/jpeg, image/webp, text/plain, video/mov, video/mpeg, video/mp4, video/mpg, video/avi, video/wmv, video/mpegps, video/flv, image/heic, image/heif, audio/flac, video/webm원시 바이트 형식의 인라인 데이터입니다. gemini-2.0-flash-lite 및 gemini-2.0-flash의 경우 inlineData를 사용하여 최대 3000개의 이미지를 지정할 수 있습니다.
프롬프트에 인라인으로 포함할 이미지, PDF 또는 비디오의 base64 인코딩입니다. 미디어를 인라인으로 포함할 때는 해당 데이터의 미디어 유형(mimeType)도 함께 지정해야 합니다. 크기 제한: 20MB형식:
bytedata 또는 fileUri 필드에 지정된 파일의 미디어 유형입니다. 허용되는 값은 다음과 같습니다. gemini-2.0-flash-lite 및 gemini-2.0-flash의 경우 오디오 파일의 최대 길이는 8.4시간이고 비디오 파일(오디오 없음)의 최대 길이는 1시간입니다. 자세한 내용은 Gemini 오디오 및 비디오 요구 사항을 참조하세요. 텍스트 파일은 UTF-8로 인코딩되어야 합니다. 텍스트 파일의 내용은 토큰 제한에 포함됩니다. 이미지 해상도에는 제한이 없습니다.가능한 값:
application/pdf, audio/mpeg, audio/mp3, audio/wav, image/png, image/jpeg, image/webp, text/plain, video/mov, video/mpeg, video/mp4, video/mpg, video/avi, video/wmv, video/mpegps, video/flv, image/heic, image/heif, audio/flac, video/webm모델이 이 파트의 비디오를 읽는 방식입니다. 고정 비율 프레임 샘플링 대신 모델이 검사할 세그먼트를 직접 결정하도록 하려면 “AGENTIC”으로 설정하세요. 기본 고정 비율 샘플링을 사용하려면 생략하세요. gemini-3.7-flash 및 최신 Flash 모델에서 지원됩니다.
생성에 대한 샘플링, 길이 및 출력 설정입니다. 모든 필드는 선택 사항입니다. 아래에서
default를 선언한 필드는 생략 시 해당 기본값이 적용되고, 나머지는 모델 자체 동작으로 대체됩니다.선택 사항입니다. 출력이 저장되어야 하는 이미지 형식이며, Vertex AI 경로에 적용됩니다. 즉 Comfy 자체 자격 증명으로 처리되는 요청과 GCP 서비스 계정으로 인증된 BYOK 요청입니다. 해당 경로에서 허용되는 값은
image/png와 image/jpeg이며, 대소문자를 구분하지 않고 일치시킨 뒤 요청이 전달되기 전에 소문자로 정규화됩니다. 그 밖의 값은 이 필드를 지목한 400 오류와 함께 거부됩니다. 생략 시 기본값은 image/png입니다. Google AI Studio API 키로 인증된 BYOK 요청은 예외입니다. 해당 업스트림에는 이런 속성이 없으며 이 속성이 존재하면 전체 호출을 거부하므로, 이 필드는 존중되거나 거부되는 대신 요청에서 제거되며, 출력 형식은 AI Studio가 선택하는 값이 됩니다. 모든 경로에서 보낸 값을 가정하지 말고, 제공받은 응답 파트에서 미디어 유형을 다시 읽어 확인하세요(inlineData.mimeType, 또는 uploadImagesToStorage가 설정된 경우 fileData.mimeType).시드가 특정 값으로 고정되면, 모델은 반복 요청에 대해 동일한 응답을 제공하기 위해 최선을 다합니다. 결정적 출력은 보장되지 않습니다. 또한 temperature와 같은 모델이나 파라미터 설정을 변경하면 동일한 시드 값을 사용하더라도 응답에 변동이 발생할 수 있습니다. 기본적으로는 무작위 시드 값이 사용됩니다. 다음 모델에서 사용할 수 있습니다: gemini-2.5-flash, gemini-2.5-pro, gemini-2.5-flash-preview-04-1, gemini-2.5-pro-preview-05-0, gemini-2.0-flash-lite-00, gemini-2.0-flash-001
temperature는 topP와 topK가 적용되는 응답 생성 중 샘플링에 사용됩니다. temperature는 토큰 선택의 무작위성 정도를 제어합니다. 낮은 temperature는 덜 개방적이거나 창의적인 응답이 필요한 프롬프트에 적합하고, 높은 temperature는 더 다양하거나 창의적인 결과로 이어질 수 있습니다. temperature가 0이면 항상 확률이 가장 높은 토큰이 선택됩니다. 이 경우 주어진 프롬프트에 대한 응답은 대부분 결정적이지만, 약간의 변동은 여전히 가능합니다. 모델이 너무 일반적이거나 너무 짧은 응답을 반환하거나 대체 응답을 제공하는 경우 temperature를 높여 보세요범위:
0 ~ 2형식: floatTop-K는 모델이 출력할 토큰을 선택하는 방식을 변경합니다. Top-K가 1이면 다음에 선택되는 토큰은 모델 어휘의 모든 토큰 중 가장 확률이 높은 토큰입니다. Top-K가 3이면 temperature를 사용하여 확률이 가장 높은 3개의 토큰 중에서 다음 토큰이 선택됩니다.범위:
1 ~ …지정하면 nucleus 샘플링이 사용됩니다.
Top-P는 모델이 출력할 토큰을 선택하는 방식을 변경합니다. 확률의 합이 top-P 값과 같아질 때까지 확률이 가장 높은 토큰(top-K 참조)부터 가장 낮은 토큰까지 선택됩니다. 예를 들어 토큰 A, B, C의 확률이 각각 0.3, 0.2, 0.1이고 top-P 값이 0.5이면, 모델은 temperature를 사용하여 A 또는 B를 다음 토큰으로 선택하고 C는 후보에서 제외합니다.
무작위성이 낮은 응답에는 더 낮은 값을, 무작위성이 높은 응답에는 더 높은 값을 지정하세요.범위:
0 ~ 1형식: float가능한 값:
HARM_CATEGORY_SEXUALLY_EXPLICIT, HARM_CATEGORY_HATE_SPEECH, HARM_CATEGORY_HARASSMENT, HARM_CATEGORY_DANGEROUS_CONTENT모델을 더 나은 성능으로 이끌기 위한 지침입니다. 예: “Answer as concisely as possible” 또는 “Don’t use technical terms in your response”. 텍스트 문자열은 토큰 한도에 포함됩니다. systemInstruction의 role 필드는 무시되며 모델의 성능에 영향을 주지 않습니다. 참고: parts에는 텍스트만 사용해야 하며, 각 part의 콘텐츠는 별도의 문단으로 구성해야 합니다.
하나의 메시지를 구성하는 순서가 지정된 part 목록입니다. part마다 서로 다른 IANA MIME 타입을 가질 수 있습니다. 최대 토큰 수나 이미지 수 같은 입력 제한은 Google 모델 페이지의 모델 사양을 참조하세요.
메시지를 생성하는 주체의 식별자입니다. 다음 값이 지원됩니다: user: 메시지가 실제 사람에 의해 전송되었음을 나타내며, 일반적으로 사용자가 생성한 메시지입니다. model: 메시지가 모델에 의해 생성되었음을 나타냅니다. model 값은 다중 턴 대화 중에 모델의 메시지를 대화에 삽입할 때 사용됩니다. 다중 턴이 아닌 대화에서는 이 필드를 비워 두거나 설정하지 않아도 됩니다.가능한 값:
user, model비디오 입력의 경우, 비디오의 시작 및 종료 오프셋을 Duration 형식으로 지정합니다. 예를 들어 1:00에서 시작하는 10초 클립을 지정하려면 “startOffset”: { “seconds”: 60 } 및 “endOffset”: { “seconds”: 70 }으로 설정합니다. 메타데이터는 비디오 데이터가 inlineData 또는 fileData로 제공되는 동안에만 지정해야 합니다.
시간 범위의 초(부호 있음). -315,576,000,000부터 +315,576,000,000까지 포함이어야 합니다.범위:
-315576000000부터 315576000000까지시간 범위의 초(부호 있음). -315,576,000,000부터 +315,576,000,000까지 포함이어야 합니다.범위:
-315576000000부터 315576000000까지GET /v2/models/vertexai/gemini-3.1-flash-image/openapi.json에서 제공하는 스키마로부터 생성되었으며, 이 문서는 요청이 공급자에 도달하기 전에 호출을 검증하는 데 사용하는 것과 동일한 문서입니다.
출력
data 또는 fileUri 필드에 지정된 파일의 미디어 타입입니다. 허용되는 값은 다음과 같습니다. gemini-2.0-flash-lite 및 gemini-2.0-flash의 경우 오디오 파일의 최대 길이는 8.4시간이고, 비디오 파일(오디오 없음)의 최대 길이는 1시간입니다. 자세한 내용은 Gemini 오디오 및 비디오 요구 사항을 참조하세요. 텍스트 파일은 UTF-8로 인코딩되어야 합니다. 텍스트 파일의 내용은 토큰 한도에 포함됩니다. 이미지 해상도에는 제한이 없습니다.가능한 값:
application/pdf, audio/mpeg, audio/mp3, audio/wav, image/png, image/jpeg, image/webp, text/plain, video/mov, video/mpeg, video/mp4, video/mpg, video/avi, video/wmv, video/mpegps, video/flv, image/heic, image/heif, audio/flac, video/webm원시 바이트 형식의 인라인 데이터입니다. gemini-2.0-flash-lite 및 gemini-2.0-flash의 경우 inlineData를 사용하여 최대 3000개의 이미지를 지정할 수 있습니다.
프롬프트에 인라인으로 포함할 이미지, PDF 또는 비디오의 base64 인코딩입니다. 미디어를 인라인으로 포함할 때는 데이터의 미디어 타입(mimeType)도 함께 지정해야 합니다. 크기 제한: 20MB형식:
bytedata 또는 fileUri 필드에 지정된 파일의 미디어 타입입니다. 허용되는 값은 다음과 같습니다. gemini-2.0-flash-lite 및 gemini-2.0-flash의 경우 오디오 파일의 최대 길이는 8.4시간이고, 비디오 파일(오디오 없음)의 최대 길이는 1시간입니다. 자세한 내용은 Gemini 오디오 및 비디오 요구 사항을 참조하세요. 텍스트 파일은 UTF-8로 인코딩되어야 합니다. 텍스트 파일의 내용은 토큰 한도에 포함됩니다. 이미지 해상도에는 제한이 없습니다.가능한 값:
application/pdf, audio/mpeg, audio/mp3, audio/wav, image/png, image/jpeg, image/webp, text/plain, video/mov, video/mpeg, video/mp4, video/mpg, video/avi, video/wmv, video/mpegps, video/flv, image/heic, image/heif, audio/flac, video/webm모델이 이 파트의 비디오를 읽는 방식을 지정합니다. 고정 비율 프레임 샘플링 대신 모델이 검사할 세그먼트를 직접 결정하도록 하려면 “AGENTIC”으로 설정합니다. 기본 고정 비율 샘플링을 사용하려면 생략합니다. gemini-3.7-flash 및 그 이후 Flash 모델에서 지원됩니다.
가능한 값:
HARM_CATEGORY_SEXUALLY_EXPLICIT, HARM_CATEGORY_HATE_SPEECH, HARM_CATEGORY_HARASSMENT, HARM_CATEGORY_DANGEROUS_CONTENT가능한 값:
HARM_CATEGORY_SEXUALLY_EXPLICIT, HARM_CATEGORY_HATE_SPEECH, HARM_CATEGORY_HARASSMENT, HARM_CATEGORY_DANGEROUS_CONTENT예시
입력
출력
inlineData.data에 base64 바이트가, inlineData.mimeType에 미디어 타입이 포함됩니다. 바이트를 디코딩하여 파일로 저장하세요. uploadImagesToStorage: true인 경우, 업로드된 이미지는 대신 서명된 URL에 fileData.fileUri를, 미디어 타입에 fileData.mimeType을 사용합니다. 이 이미지들은 생성된 후 24시간 뒤 URL이 만료되므로 그 이전에 다운로드하세요. 업로드에 실패하면 해당 이미지는 인라인으로 남으므로 각 파트에서 inlineData 또는 fileData를 확인하세요. 텍스트 파트도 나타날 수 있으며, 이미지가 첫 번째 파트라고 보장되지는 않습니다. 위의 퀵스타트 샘플에 있는 candidates[0].content.parts[0].inlineData.data 경로는 이 페이지의 샘플 응답에서 단일 인라인 파트를 읽습니다. 실제 응답에서는 위치 0을 인덱싱하는 대신 parts를 스캔하여 원하는 키를 찾으세요.
배포 전 확인
SDK는Idempotency-Key를 생성하고 자동 재시도에 재사용합니다. 수동으로 재시도할 때는 원본 키를 재사용하세요. Router는 연결을 최대 10분간 유지할 수 있습니다.
요청이 실패하면 Router는 그 이유를 설명하는 X-Comfy-Error-Type 응답 헤더를 보냅니다. 422는 Router가 공급자를 호출하기 전에 입력을 거부했음을 의미하고, 413은 요청 본문이 Router가 허용하는 크기보다 컸음을 의미합니다. 결과 URL이 만료될 수 있으므로 생성된 에셋은 즉시 다운로드하세요.
위의 필드 설명에 명시된 크기 제한은 해당 필드에 대한 공급자 자체의 한도이며, 공급자 사양에서 인용한 것입니다. Router는 전체 요청 본문에 별도의 상한을 적용하며, base64로 인코딩된 미디어도 여기에 포함됩니다. 요청 본문 크기를 참고하세요.
이 페이지는 Comfy Router를 통해 호출하는 하나의 파트너 모델을 설명합니다. 동일한 comfy-sdk / @comfyorg/sdk 패키지에는 Comfy Cloud에서 전체 ComfyUI 워크플로 그래프를 실행하기 위한 두 번째 클라이언트도 포함되어 있습니다: Comfy(api_key=...) / new Comfy({ apiKey }), 그리고 client.workflows, client.assets, client.jobs가 있습니다. Comfy SDKs를 참조하세요.
헤더
인증, 멱등성, 요청 ID, 오류 분류, 재시도 간격, 지출 한도.
Router API 사용
모델 검색, 검증 오류, 재시도, 과금.
제한 사항
Router가 현재 지원하지 않는 기능과 대신 사용할 방법.