API | Gemini 2.5 Flash API — 1M 컨텍스트 안정판

google/gemini-2.5-flash/chat

Gemini 2.5 Flash는 OpenAI 호환 chat 엔드포인트로 쓰는 Google의 하이브리드 추론 모델입니다. 최대 1,048,576 토큰을 읽고 65,535 토큰을 반환하며 추론 강도 3단계, 도구 128개, 텍스트·이미지·영상·오디오 입력을 지원합니다.

입력 $0.285출력 $2.375100만 토큰당캐시된 입력 $0.0285Google 공식 가격~~$0.30$2.50~~

모델 실행 API 보기

요청 보내기

예시는 선택한 엔드포인트의 공개 파라미터 정의를 사용합니다. API 키와 예시 미디어를 바꾼 뒤 서버에서 요청하세요.

SDK 및 연동

POSThttps://api.spicyapi.ai/v1/chat/completions

API 인증

API 키는 서버 환경 변수 SPICY_API_KEY에 보관하세요. Bearer 인증을 사용하고 JSON 요청에는 Content-Type: application/json을 지정하세요.

Authorization: Bearer $SPICY_API_KEY

curl --fail-with-body -sN https://api.spicyapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "model": "google/gemini-2.5-flash/chat",
  "messages": [
    {
      "role": "user",
      "content": "Summarise the following release notes into three bullet points."
    }
  ],
  "stream": true
}' \
  | jq --unbuffered -Rrj 'select(startswith("data: ")) | .[6:] | select(. != "[DONE]") | fromjson | if .error then "\n[error] \(.error.message)\n" else (.choices[0].delta.content? // empty) end'

이 모델의 입력 스키마에서 뽑아낸 예시입니다. API도 모든 요청을 같은 스키마로 검증합니다.

논리적으로 같은 요청 하나에는 같은 Idempotency-Key를 계속 쓰세요. 네트워크가 끊겼다고 새 키로 자동 재전송하지 말고, 접수된 요청을 나중에 확인할 수 있도록 request_id를 남겨 두세요. 앞서 받던 채팅 스트림이 다시 흘러나오지는 않습니다.

입력 파라미터

모델 파라미터는 JSON 요청 본문에서 model과 같은 수준에 넣습니다. 이 엔드포인트는 input으로 감싸지 않습니다.

messagesarray<object>필수

오래된 순서대로 놓은 턴입니다. 내용은 문자열이거나 text, image_url, video_url, audio_url, input_audio 파트의 배열입니다. 업로드한 동영상과 오디오는 요청 하나에 합계 14 MB까지 가능합니다. 계속 적용할 지시는 system에 두고 턴마다 한 번씩만 덧붙이세요.

기본값: 지정되지 않음
제약 조건: minItems:1

messages[].rolestring객체 내 필수

Role of the message author.

기본값: 지정되지 않음
허용 값: "system""developer""user""assistant""tool"

messages[].namestring선택

Optional name identifying the speaker within its role.

기본값: 지정되지 않음

messages[].contentstring | array | null선택

Message content, either plain text or a list of content parts.

기본값: 지정되지 않음

{
  "type": [
    "string",
    "array",
    "null"
  ],
  "items": {
    "oneOf": [
      {
        "type": "object",
        "required": [
          "type",
          "text"
        ],
        "properties": {
          "text": {
            "type": "string"
          },
          "type": {
            "const": "text"
          }
        }
      },
      {
        "type": "object",
        "required": [
          "type",
          "image_url"
        ],
        "properties": {
          "type": {
            "const": "image_url"
          },
          "image_url": {
            "type": "object",
            "required": [
              "url"
            ],
            "properties": {
              "url": {
                "type": "string"
              }
            }
          }
        }
      },
      {
        "type": "object",
        "required": [
          "type",
          "video_url"
        ],
        "properties": {
          "type": {
            "const": "video_url"
          },
          "video_url": {
            "type": "object",
            "required": [
              "url"
            ],
            "properties": {
              "url": {
                "type": "string"
              }
            }
          }
        }
      },
      {
        "type": "object",
        "required": [
          "type",
          "audio_url"
        ],
        "properties": {
          "type": {
            "const": "audio_url"
          },
          "audio_url": {
            "type": "object",
            "required": [
              "url"
            ],
            "properties": {
              "url": {
                "type": "string"
              }
            }
          }
        }
      },
      {
        "type": "object",
        "required": [
          "type",
          "input_audio"
        ],
        "properties": {
          "type": {
            "const": "input_audio"
          },
          "input_audio": {
            "type": "object",
            "required": [
              "data",
              "format"
            ],
            "properties": {
              "data": {
                "type": "string"
              },
              "format": {
                "enum": [
                  "wav",
                  "mp3"
                ],
                "type": "string"
              }
            }
          }
        }
      }
    ]
  },
  "description": "Message content, either plain text or a list of content parts."
}

messages[].tool_callsarray<object>선택

Tool calls the assistant requested in this message.

기본값: 지정되지 않음

messages[].tool_call_idstring선택

Identifier of the tool call this message answers. Required on tool messages.

기본값: 지정되지 않음

messages[].reasoning_contentstring선택

Reasoning text from a previous assistant reply, preserved when continuing a tool conversation.

기본값: 지정되지 않음

{
  "type": "array",
  "x-ui": {
    "order": 100,
    "widget": "chat-messages",
    "primary": true
  },
  "items": {
    "type": "object",
    "allOf": [
      {
        "if": {
          "required": [
            "reasoning_content"
          ]
        },
        "then": {
          "properties": {
            "role": {
              "const": "assistant"
            }
          }
        }
      }
    ],
    "required": [
      "role"
    ],
    "properties": {
      "name": {
        "type": "string",
        "description": "Optional name identifying the speaker within its role."
      },
      "role": {
        "enum": [
          "system",
          "developer",
          "user",
          "assistant",
          "tool"
        ],
        "type": "string",
        "description": "Role of the message author."
      },
      "content": {
        "type": [
          "string",
          "array",
          "null"
        ],
        "items": {
          "oneOf": [
            {
              "type": "object",
              "required": [
                "type",
                "text"
              ],
              "properties": {
                "text": {
                  "type": "string"
                },
                "type": {
                  "const": "text"
                }
              }
            },
            {
              "type": "object",
              "required": [
                "type",
                "image_url"
              ],
              "properties": {
                "type": {
                  "const": "image_url"
                },
                "image_url": {
                  "type": "object",
                  "required": [
                    "url"
                  ],
                  "properties": {
                    "url": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            {
              "type": "object",
              "required": [
                "type",
                "video_url"
              ],
              "properties": {
                "type": {
                  "const": "video_url"
                },
                "video_url": {
                  "type": "object",
                  "required": [
                    "url"
                  ],
                  "properties": {
                    "url": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            {
              "type": "object",
              "required": [
                "type",
                "audio_url"
              ],
              "properties": {
                "type": {
                  "const": "audio_url"
                },
                "audio_url": {
                  "type": "object",
                  "required": [
                    "url"
                  ],
                  "properties": {
                    "url": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            {
              "type": "object",
              "required": [
                "type",
                "input_audio"
              ],
              "properties": {
                "type": {
                  "const": "input_audio"
                },
                "input_audio": {
                  "type": "object",
                  "required": [
                    "data",
                    "format"
                  ],
                  "properties": {
                    "data": {
                      "type": "string"
                    },
                    "format": {
                      "enum": [
                        "wav",
                        "mp3"
                      ],
                      "type": "string"
                    }
                  }
                }
              }
            }
          ]
        },
        "description": "Message content, either plain text or a list of content parts."
      },
      "tool_calls": {
        "type": "array",
        "items": {
          "type": "object"
        },
        "description": "Tool calls the assistant requested in this message."
      },
      "tool_call_id": {
        "type": "string",
        "description": "Identifier of the tool call this message answers. Required on tool messages."
      },
      "reasoning_content": {
        "type": "string",
        "description": "Reasoning text from a previous assistant reply, preserved when continuing a tool conversation."
      }
    },
    "additionalProperties": false
  },
  "minItems": 1,
  "description": "Ordered conversation turns. Text content only on this endpoint."
}

response_formatobject선택

JSON 객체를 요구하고 키는 전부 system 메시지에서 이름으로 지정하세요. 응답이 파싱 가능한 형태로 돌아오는 이유입니다.

기본값: 지정되지 않음

tool_choicestring | object선택

auto, none, required 또는 함수 하나를 지정하는 객체입니다.

기본값: 지정되지 않음

toolsarray<object>선택

요청 하나에 함수 정의 최대 128개입니다.

기본값: 지정되지 않음
제약 조건: maxItems:128

top_pnumber선택

0.01에서 1입니다. 이것과 temperature 중 하나만 움직이고 같은 비교에서 둘 다 건드리지 마세요.

기본값: 1
제약 조건: minimum:0.01
maximum:1

temperaturenumber선택

0에서 2, 기본 1입니다. 응답을 코드가 파싱하면 0 쪽으로 내리고, 문장 말투를 풀고 싶으면 올리세요.

기본값: 1
제약 조건: minimum:0
maximum:2

seedinteger선택

임의의 정수입니다. 다른 조건이 같은 요청에 같은 seed를 쓰면 응답이 거의 그대로 재현되므로, 한 번에 한 가지만 바꿔 공정하게 비교할 수 있습니다. 다만 완전히 같은 출력을 보장하지는 않습니다. 기본값은 없으며 요청마다 새로 추첨합니다. 가격에는 영향이 없습니다.

기본값: 지정되지 않음

stopstring | array선택

최대 4개의 정지 시퀀스를 문자열 또는 배열로 지정합니다. 모델이 그중 하나를 쓰는 즉시 응답이 끝나며, 일치한 텍스트 자체는 반환되지 않습니다. 기본값은 없습니다. 단가는 달라지지 않으며, 일찍 끝난 응답은 실제로 생성된 토큰만큼만 과금됩니다.

기본값: 지정되지 않음
제약 조건: minLength:1
minItems:1
maxItems:4

reasoning_effortstring선택

low, medium, high이고 기본은 medium입니다. 평범한 작업은 low로 충분하고, 꼭 맞혀야 하는 요청만 따로 high로 올리면 됩니다. 단계마다 생각 토큰이 몇 개인지는 공개된 수치가 없어서 저희도 말하지 않습니다.

기본값: "medium"
허용 값: "low""medium""high"

max_tokensinteger선택

응답을 65,535에서 자릅니다. 기본값은 16,384입니다. 긴 자료에서 짧은 답만 받고 싶으면 낮추세요. 상한은 천장이지 목표가 아닙니다. 추론 토큰도 출력으로 과금되므로, 기대하는 보이는 응답보다 여유를 두세요.

기본값: 16384
제약 조건: minimum:1
maximum:65535

{
  "type": "object",
  "required": [
    "messages"
  ],
  "x-pricing": {
    "billingMode": "formula",
    "variantFields": []
  },
  "properties": {
    "seed": {
      "type": "integer",
      "x-ui": {
        "order": 55,
        "widget": "number",
        "affects_price": false
      },
      "description": "Seed for the sampler, so a repeated request comes back close to the same."
    },
    "stop": {
      "type": [
        "string",
        "array"
      ],
      "x-ui": {
        "order": 65,
        "widget": "text",
        "affects_price": false
      },
      "items": {
        "type": "string",
        "minLength": 1
      },
      "maxItems": 4,
      "minItems": 1,
      "minLength": 1,
      "description": "Sequences that end the reply as soon as the model writes one; the matched text is not returned."
    },
    "tools": {
      "type": "array",
      "x-ui": {
        "order": 35,
        "widget": "json"
      },
      "items": {
        "type": "object"
      },
      "maxItems": 128,
      "description": "Tool definitions the model may call."
    },
    "top_p": {
      "type": "number",
      "x-ui": {
        "step": 0.01,
        "order": 40,
        "widget": "slider"
      },
      "default": 1,
      "maximum": 1,
      "minimum": 0.01,
      "description": "Nucleus sampling threshold. Lower values keep only the most likely tokens."
    },
    "messages": {
      "type": "array",
      "x-ui": {
        "order": 100,
        "widget": "chat-messages",
        "primary": true
      },
      "items": {
        "type": "object",
        "allOf": [
          {
            "if": {
              "required": [
                "reasoning_content"
              ]
            },
            "then": {
              "properties": {
                "role": {
                  "const": "assistant"
                }
              }
            }
          }
        ],
        "required": [
          "role"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Optional name identifying the speaker within its role."
          },
          "role": {
            "enum": [
              "system",
              "developer",
              "user",
              "assistant",
              "tool"
            ],
            "type": "string",
            "description": "Role of the message author."
          },
          "content": {
            "type": [
              "string",
              "array",
              "null"
            ],
            "items": {
              "oneOf": [
                {
                  "type": "object",
                  "required": [
                    "type",
                    "text"
                  ],
                  "properties": {
                    "text": {
                      "type": "string"
                    },
                    "type": {
                      "const": "text"
                    }
                  }
                },
                {
                  "type": "object",
                  "required": [
                    "type",
                    "image_url"
                  ],
                  "properties": {
                    "type": {
                      "const": "image_url"
                    },
                    "image_url": {
                      "type": "object",
                      "required": [
                        "url"
                      ],
                      "properties": {
                        "url": {
                          "type": "string"
                        }
                      }
                    }
                  }
                },
                {
                  "type": "object",
                  "required": [
                    "type",
                    "video_url"
                  ],
                  "properties": {
                    "type": {
                      "const": "video_url"
                    },
                    "video_url": {
                      "type": "object",
                      "required": [
                        "url"
                      ],
                      "properties": {
                        "url": {
                          "type": "string"
                        }
                      }
                    }
                  }
                },
                {
                  "type": "object",
                  "required": [
                    "type",
                    "audio_url"
                  ],
                  "properties": {
                    "type": {
                      "const": "audio_url"
                    },
                    "audio_url": {
                      "type": "object",
                      "required": [
                        "url"
                      ],
                      "properties": {
                        "url": {
                          "type": "string"
                        }
                      }
                    }
                  }
                },
                {
                  "type": "object",
                  "required": [
                    "type",
                    "input_audio"
                  ],
                  "properties": {
                    "type": {
                      "const": "input_audio"
                    },
                    "input_audio": {
                      "type": "object",
                      "required": [
                        "data",
                        "format"
                      ],
                      "properties": {
                        "data": {
                          "type": "string"
                        },
                        "format": {
                          "enum": [
                            "wav",
                            "mp3"
                          ],
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              ]
            },
            "description": "Message content, either plain text or a list of content parts."
          },
          "tool_calls": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Tool calls the assistant requested in this message."
          },
          "tool_call_id": {
            "type": "string",
            "description": "Identifier of the tool call this message answers. Required on tool messages."
          },
          "reasoning_content": {
            "type": "string",
            "description": "Reasoning text from a previous assistant reply, preserved when continuing a tool conversation."
          }
        },
        "additionalProperties": false
      },
      "minItems": 1,
      "description": "Ordered conversation turns. Text content only on this endpoint."
    },
    "max_tokens": {
      "type": "integer",
      "x-ui": {
        "unit": "tokens",
        "order": 80,
        "widget": "number",
        "advanced": false,
        "affects_price": false
      },
      "default": 16384,
      "maximum": 65535,
      "minimum": 1,
      "description": "Maximum number of tokens to generate in the reply."
    },
    "temperature": {
      "type": "number",
      "x-ui": {
        "order": 50,
        "widget": "slider"
      },
      "default": 1,
      "maximum": 2,
      "minimum": 0,
      "description": "Sampling temperature. Higher values make the output more varied."
    },
    "tool_choice": {
      "type": [
        "string",
        "object"
      ],
      "x-ui": {
        "order": 30,
        "widget": "json"
      },
      "description": "Controls whether and which tool the model may call."
    },
    "response_format": {
      "type": "object",
      "x-ui": {
        "order": 25,
        "widget": "json"
      },
      "description": "Requested reply format, such as plain text or a JSON object."
    },
    "reasoning_effort": {
      "enum": [
        "low",
        "medium",
        "high"
      ],
      "type": "string",
      "x-ui": {
        "order": 70,
        "widget": "radio"
      },
      "default": "medium",
      "description": "How much the model works through the task before answering."
    }
  },
  "x-image-token-limit": 4500,
  "x-input-token-limit": 1048576,
  "additionalProperties": false,
  "x-max-tokens-includes-reasoning": true
}

결과 읽기

stream이 false이면 완성된 채팅 응답이 바로 반환됩니다. choices[].message를 읽으면 되며 작업을 폴링할 필요가 없습니다. Server-Sent Events를 지원하는 클라이언트에서는 stream을 true로 설정할 수 있습니다.

완료 응답 예시

{
  "id": "chatcmpl_example",
  "object": "chat.completion",
  "created": 1788652800,
  "model": "google/gemini-2.5-flash/chat",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Here is a concise summary of the release notes."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 32,
    "completion_tokens": 14,
    "total_tokens": 46
  }
}

응답은 구조를 보여 주는 예시입니다. usage는 토큰 수이며 실제 사용량과 요금은 요청에 따라 달라집니다.

SDK 및 연동

앱, 터미널, AI 어시스턴트 또는 시각적 워크플로에서 SpicyAPI를 사용하세요. 원하는 설정 가이드를 선택하세요.

SDKs

TypeScript · Python · Go · PHP · Java

CLI

터미널 명령과 자동화 스크립트.

MCP

Claude Code · Cursor · Codex

Agent Skill

AI 어시스턴트에서 재사용할 수 있는 지침.

n8n

자체 호스팅용 커뮤니티 노드와 n8n Cloud에서 가져올 수 있는 HTTP Request 템플릿

ComfyUI

노드 캔버스로 구성하는 이미지, 동영상, 오디오 워크플로.

더 많은 연동

SillyTavern Telegram / Discord App proxy OpenAI SDK LangChain Vercel AI SDK

바로 사용할 수 있는 워크플로 보기

채팅 모델이므로 OpenAI 챗 API가 통하는 곳이면 그대로 동작합니다. 쓰던 클라이언트는 그대로 두고 베이스 URL만 바꾼 뒤 이 모델 ID를 지정하세요.

OpenAI 호환 클라이언트를 이쪽으로 돌리세요

export OPENAI_BASE_URL="https://api.spicyapi.ai/v1"
export OPENAI_API_KEY="$SPICY_API_KEY"

aider --model openai/google/gemini-2.5-flash/chat

OpenAI 채팅 API를 사용하는 SDK, Vercel AI SDK, LangChain, aider, Cline 등에서 같은 방식으로 이용할 수 있습니다. MCP 서버와 spicyapi CLI는 비동기 미디어 작업을 지원합니다. 도구별 설정은 개발자 허브에서 확인하세요.

SillyTavern과 롤플레이 앱에서 사용하기

SillyTavern, RisuAI, Agnai 등 OpenAI 호환 설정이 있는 앱에 아래 기본 URL과 API 키를 붙여 넣고 모델로 google/gemini-2.5-flash/chat을(를) 선택합니다. 브라우저에서 바로 호출할 수 있으며, 이 모델이 받지 않는 슬라이더 값은 오류 없이 무시됩니다.

Base URL: https://api.spicyapi.ai/v1
Model: google/gemini-2.5-flash/chat

SillyTavern 가이드 RisuAI, Agnai 외 SillyTavern 확장 프로그램

ComfyUI에서 쓰기

ComfyUI Manager나 아래 명령으로 SpicyAPI 노드를 설치한 뒤 SpicyAPI Chat 노드에서 google/gemini-2.5-flash/chat을(를) 고르면 ComfyUI 그래프 안에서 이 모델을 쓸 수 있습니다.

cd ComfyUI/custom_nodes
git clone https://github.com/spicyapi-ai/comfyui-spicyapi

워크플로 예시 설정 가이드 GitHub 소스

삽입된 패널은 이 페이지와 같은 스키마를 참조하므로 API 사양과 어긋나지 않습니다. 문서 검색 대상에 포함하려면 /api/embed/models/의 JSON을 받아 직접 렌더링하세요.

<iframe src="https://spicyapi.ai/embed/ko/models/gemini-2-5-flash/api?model=google%2Fgemini-2.5-flash%2Fchat" width="100%" height="560" loading="lazy" title="요청 예시" style="border:1px solid rgba(0,0,0,.12)"></iframe>

패널 열기

플레이그라운드

요청 보내기

API 인증

입력 파라미터

결과 읽기

SDK 및 연동

SillyTavern과 롤플레이 앱에서 사용하기

ComfyUI에서 쓰기