Google Colab에서 첫 요청: API 키를 Secrets에 보관하기

컴퓨터에 아무것도 설치하지 않고 Colab 노트북에서 첫 요청을 실행할 수 있습니다. 키를 Colab Secrets에 저장하고, userdata.get(...)로 읽어 들인 뒤, openai 패키지가 https://api.cheaptokens.dev/v1를 가리키도록 설정하고, choices[0].message.content와 usage를 출력하세요. 키는 셀에 남지 않으므로 노트북을 공유해도 키는 공유되지 않습니다.

바로 이 점이 이 방식을 택할 이유입니다. 노트북을 완성해서 링크를 동기에게 보낸다고 해봅시다. 키를 셀에 붙여 넣었다면 동기에게도 키가 넘어갑니다. Secrets에 두었다면 동기는 코드만 받습니다.

이 가이드는 일반 requests로 보내는 첫 요청을 이어서 다룹니다. 여기서 새로운 점은 키가 어디에 있는지와 노트북이 그것을 어떻게 읽는지뿐입니다. 노트북이 아닌 노트북 컴퓨터에서 같은 개념을 보려면 환경 변수에 키 저장하기를 참고하세요.

필요한 것#

• Google 계정과 colab.research.google.com에서 만든 새 노트북.
• CheapTokens API 키와 충전된 잔액. 키와 잔액은 계정에 있으며, 문서에 정확한 절차가 나와 있습니다.
• 5분.

API는 OpenAI Chat Completions와 호환되므로 표준 openai Python 패키지가 다른 base_url와 함께 동작합니다. openai-python README(2026년 11월 5일 확인)에는 Python 3.10 이상과 pip install openai이 명시되어 있습니다.

키를 Colab Secrets에 넣기#

노트북 왼쪽 사이드바에 열쇠 아이콘이 있고, 이것을 누르면 Secrets 패널이 열립니다. 새 시크릿을 추가하고 이름을 CHEAPTOKENS_KEY로 지정한 뒤 값에 키를 붙여 넣고, 작업 중인 노트북에 대해 노트북 접근을 켜세요. 버튼 문구는 바뀔 수 있으니 메뉴 경로보다 열쇠 아이콘을 찾으세요.

이름은 지금 정하세요. 코드에 넘길 문자열이 바로 이 이름입니다. 이름을 잘못 쓰기 쉬운데, 오류 섹션에서 어떻게 나타나는지 보여 줍니다.

첫 요청 실행하기#

Colab은 Google의 colabtools 모듈에 있는 함수 google.colab.userdata.get(name)로 시크릿을 읽습니다(docstring 2026년 11월 5일 확인). SDK를 설치하고, 시크릿을 읽고, 요청 하나를 보내세요.

!pip install -q openai

from google.colab import userdata
from openai import OpenAI

client = OpenAI(
    api_key=userdata.get('CHEAPTOKENS_KEY'),
    base_url='https://api.cheaptokens.dev/v1',
)

resp = client.chat.completions.create(
    model='deepseek-ai/DeepSeek-V4-Flash-0731',
    messages=[{'role': 'user', 'content': 'Explain a token in one sentence.'}],
    max_tokens=200,
)
print(resp.choices[0].message.content)
print(resp.usage.prompt_tokens, resp.usage.completion_tokens)

첫 번째 print는 모델의 답변을 보여 줍니다. 두 번째는 두 개의 숫자를 출력합니다. 보낸 토큰 수와 모델이 쓴 토큰 수입니다. 이것이 요청의 전체 청구 내역이므로 매번 출력합니다.

요청 비용#

비용을 지불하는 대상은 토큰이므로 출력의 두 번째 줄을 보세요. 위와 같은 짧은 질문이 입력 약 40토큰을 쓰고 답변이 출력 150토큰이라고 해봅시다. 현재 가격으로 이 요청은 $0.000016이고, 이런 요청 천 건은 $0.0156입니다. 40과 150은 노트북이 출력한 두 숫자로 바꾸세요.

여기서 DeepSeek-V4-Flash가 기본인 데는 이유가 있습니다. 380K 컨텍스트, 답변당 최대 32,768 출력 토큰, 그리고 하루 중 언제든 피크 시간 없이 동일한 가격입니다. 하나의 잔액으로 모든 모델을 쓸 수 있으므로 이 셀에서 모델만 바꾸고 다른 것은 그대로 두면 됩니다. zai-org/GLM-5.3-Flash(390K 컨텍스트, 최대 8,192 출력 토큰)를 시도하고 셀을 다시 실행해 보세요. 전체 목록은 모든 모델과 가격을 참고하세요.

셀이 실패할 때#

시크릿 쪽 오류는 요청이 Colab을 떠나기 전에 먼저 발생합니다. colabtools 소스(2026년 11월 5일 확인)에 따르면 userdata.get는 세 가지 오류를 발생시킬 수 있습니다.

• SecretNotFoundError: 해당 이름의 시크릿이 없습니다. userdata.get('...')의 문자열과 Secrets 패널의 이름을 글자 하나하나 비교하세요. 대소문자를 구분합니다.
• NotebookAccessError: 시크릿은 있지만 이 노트북에 접근 권한이 없습니다. Secrets 패널에서 접근 토글을 켜고 셀을 다시 실행하세요.
• TimeoutException: Colab이 시크릿 요청에 응답하지 않았습니다. 오류 메시지에 따르면 시크릿은 코드가 Colab UI에서 실행될 때만 가져올 수 있으므로, 내보낸 스크립트가 아니라 Colab 노트북 자체에서 셀을 실행하세요.

시크릿이 로드되는데도 요청이 실패하면 문제는 API 쪽에 있습니다. 401은 키가 잘못되었거나 없다는 뜻이고, 404은 보통 잘못된 base URL이나 모델 id를 가리킵니다. API 401 또는 404: 키, base URL, 모델 id에서 둘 다 살펴보고, GET /v1/models로 모델 목록 조회하기에서 정확한 id를 복사하는 방법을 보여 줍니다.

공유와 교체#

노트북을 공유하면 userdata.get를 호출하는 코드도 함께 공유됩니다. 키는 어떤 셀이나 출력에도 없으므로 유출될 것이 없습니다. 노트북을 여는 사람은 같은 이름의 자기 시크릿이 필요하며, 없으면 SecretNotFoundError가 발생합니다(위 참고).

새 키를 만들면 Secrets 패널의 값을 업데이트하세요. 코드는 시크릿 이름만 지정하므로 그대로 둡니다.

여전히 중요한 습관이 하나 있습니다. 키를 절대 출력하지 마세요. print(userdata.get('CHEAPTOKENS_KEY')) 같은 셀은 키를 출력에 넣고, 출력은 노트북과 함께 저장됩니다.

다음 단계: 답변을 루프, 채팅 또는 작은 도구에 넣어 보세요. 나머지 API는 문서에서 다룹니다.