모델 목록

GET /v1/models — 이 키로 쓸 수 있는 모델을 확인합니다.

호출하기

내 키가 쓸 수 있는 모델만 내려옵니다. 키가 살아 있는지 확인하는 일과 모델을 고르는 일을 이 호출 하나로 끝낼 수 있습니다.

curl https://ai.cubion.kr/v1/models -H "Authorization: Bearer $GATEWAY_KEY"
# 200 이면 키가 살아 있는 것입니다.

import os
from openai import OpenAI

ai = OpenAI(base_url="https://ai.cubion.kr/v1", api_key=os.environ["GATEWAY_KEY"])

models = ai.models.list()
chat = [m for m in models.data if getattr(m, "mode", None) == "chat"]
print([m.id for m in chat])

import OpenAI from "openai";

const ai = new OpenAI({ baseURL: "https://ai.cubion.kr/v1", apiKey: process.env.GATEWAY_KEY });

// 드롭다운을 손으로 채우지 말고 이 목록으로 만드세요 —
//   모델이 늘거나 빠져도 앱을 고칠 필요가 없습니다.
const models = await ai.models.list();
const chat = models.data.filter((m) => (m as { mode?: string }).mode === "chat");

인증에 실패하면 401 이 옵니다 — 앱의 “연결 테스트” 버튼을 이 호출로 만들면 됩니다.

응답 읽기

OpenAI 와 같은 { object, data[] } 형태에, 이 키에 대한 정보가 key 로 덧붙습니다.

응답

{
  "object": "list",
  "data": [
    { "id": "gpt-4o", "object": "model", "owned_by": "openai", "mode": "chat" },
    { "id": "gemini/gemini-2.5-flash", "object": "model", "owned_by": "gemini", "mode": "chat" },
    { "id": "gpt-image-1", "object": "model", "owned_by": "openai", "mode": "image_generation" },
    { "id": "fish/s1", "object": "model", "owned_by": "fish", "mode": "audio_speech" }
  ],
  "key": { "name": "내 키", "scopes": ["ai"], "restricted": false }
}

mode 로 용도 구분

mode 는 OpenAI 스펙에는 없는 부가 정보입니다. 채팅용 드롭다운에 이미지 모델이 섞여 들어가지 않게, 목록을 mode 로 걸러 쓰세요.

mode	엔드포인트	참고
`chat`	`POST /v1/chat/completions`	채팅·응답
`image_generation`	`POST /v1/images/generations`	`image.sizes` 가 함께 옵니다 — 이미지 생성
`audio_speech`	`POST /v1/audio/speech`	`audio.voices`·`formats` 가 함께 옵니다 — 음성 합성

모델명 표기 규칙

목록을 보면 gpt-4o 처럼 이름만 있는 모델과 gemini/gemini-2.5-flash 처럼 앞에 한 토막이 붙은 모델이 섞여 있습니다. 앞에 붙은 gemini/·fish/ 는 게이트웨이가 어느 제공자로 보낼지 고르는 표시이고, 없는 이름은 그럴 필요가 없는 모델입니다.

규칙을 외울 필요는 없습니다

목록에 적힌 id 를 그대로 요청의 model 에 넣으면 됩니다. 접두사를 임의로 떼거나 붙이면 다른 이름이 되어 403 model_not_allowed 가 납니다.

목록의 id 를 그대로 쓴다

{ "model": "gpt-4o", ... }                      // 접두사 없음
{ "model": "claude-sonnet-4-5", ... }           // 접두사 없음
{ "model": "gemini/gemini-2.5-flash", ... }     // gemini/ 가 이름의 일부다
{ "model": "fish/s1", ... }                     // fish/ 가 이름의 일부다

알아 둘 점

모델명을 앱에 박아 두지 마세요. 쓸 수 있는 모델은 바뀔 수 있습니다. 목록으로 드롭다운을 채우면 모델이 늘거나 빠져도 앱을 고칠 일이 없습니다.
목록에 없는 모델을 부르면 403 model_not_allowed 입니다 — 키에 허용 목록이 걸려 있으면 그 안의 모델만 내려옵니다.
key.scopes 가 ["ai"] 면 포털에서 발급한 키입니다. /v1/* 호출에만 쓸 수 있고, 다른 경로를 부르면 403 scope_forbidden 입니다.
목록 호출 자체에는 요금이 붙지 않습니다. 그래도 앱 켤 때 한 번 받아 두고 쓰는 편이 빠릅니다.
키 발급·폐기는 API 키 에서 합니다. 상태 코드 전체는 오류 처리 를 보세요.

이전음성 합성 다음기능 프로필