Step 5 Preview 사용법: 1M 컨텍스트 에이전트 API를 안전하게 시험하는 법

9월 21, 2026

Step 5 Preview는 StepFun이 2026년 9월 20일 공개한 에이전트 작업용 플래그십 모델이다. 100만 토큰 컨텍스트, 텍스트·이미지·영상 입력, 도구 호출을 앞세우지만, 긴 입력이 가능하다는 사실만으로 실제 업무 자동화가 안전해지는 것은 아니다. 이 글은 홍보용 벤치마크를 다시 나열하기보다 API를 작은 범위에서 연결하고, 비용·도구 실행·데이터 경계를 확인한 뒤 확대하는 방법에 집중한다.

핵심 요약

모델 ID는 step-5-preview, 컨텍스트는 최대 1M 토큰, 출력은 최대 64K 토큰이다.
표준 API와 Step Plan은 Base URL과 과금 체계가 다르다. 성공 응답만 보고 어느 채널에서 비용이 빠졌는지 판단하면 안 된다.
도구 호출은 모델이 요청을 만들 뿐이며, 실제 실행·권한·재시도·결과 검증은 애플리케이션이 맡는다.
공식 문서 사이에 프롬프트 캐시 지원 범위가 일치하지 않는다. 실제 응답의 사용량 필드와 콘솔 기록으로 확인해야 한다.

Step 5 Preview에서 달라진 점

공식 발표에 따르면 Step 5 Preview는 총 600B, 토큰당 27B가 활성화되는 희소 MoE 구조다. 긴 소프트웨어 작업, 여러 자료를 묶는 전문 분석, 이미지와 영상을 포함한 조사 흐름을 주요 용도로 제시한다. 현재 제품과 API로 사용할 수 있고, 가중치 공개는 10월 15일로 예고됐다. 따라서 지금 당장 로컬 모델을 내려받아 운영하는 제품이 아니라, 우선 API 프리뷰를 검증하는 단계로 보는 편이 정확하다.

공식 발표의 코딩·금융·장기 실행 결과는 제조사가 설계한 평가와 사례다. 모델 선택의 출발점은 될 수 있지만 독자의 저장소, 문서, 권한 구조에서 같은 결과를 보장하지 않는다. 특히 장시간 에이전트 작업은 한 번의 정답보다 중간 상태 저장, 도구 오류 복구, 비용 상한, 사람이 중단할 수 있는 지점이 더 중요하다.

무엇을 지원하고 무엇은 애플리케이션이 맡나

항목	공식 지원 범위	도입 전 확인
입출력	텍스트·이미지·영상 입력, 텍스트 출력	OCR·영상 요약의 근거 위치와 누락 여부
컨텍스트	최대 1M 입력, 최대 64K 출력	긴 입력의 비용, 지연, 핵심 정보 회수율
이미지	요청당 최대 60장, URL 또는 Base64	해상도·detail 설정과 토큰 증가
영상	MP4·QuickTime·Matroska, URL/Base64/Files API	URL 영상은 128MB 미만, 5분 미만 권장
도구 호출	함수 최대 128개 정의 가능	실행 권한·인자 검증·실패 복구는 앱 책임

긴 문서·코드·이미지·영상이 도구 경계와 사람 검토를 거쳐 처리되는 Step 5 Preview 장기 컨텍스트 흐름 — 1M 컨텍스트는 자료를 한 번에 담는 공간이다. 외부 도구 실행과 최종 검토 책임까지 모델에 자동으로 생기는 것은 아니다.

표준 API와 Step Plan부터 구분하기

StepFun에는 사용량 기반의 표준 API와 구독형 Step Plan이 있다. 표준 OpenAI 호환 Chat Completions Base URL은 https://api.stepfun.ai/v1이고, 요청은 POST /chat/completions로 보낸다. Step Plan에서 OpenAI SDK를 사용할 때는 https://api.stepfun.ai/step_plan/v1, Claude Code나 Anthropic SDK에는 https://api.stepfun.ai/step_plan을 넣는다.

두 채널은 잔액과 할당량이 분리된다. 표준 주소로 성공한 호출이 Step Plan 크레딧을 썼다는 뜻은 아니다. 반대로 구독이 있어도 표준 API 잔액이 자동으로 생기지 않는다. 첫 시험에서는 Base URL, 모델 ID, 요청 ID, 콘솔의 사용량 기록을 함께 남겨야 과금 경로를 확인할 수 있다.

Step Plan은 월별 Credits 방식이며 Flash Mini부터 Flash Max까지 네 단계가 있다. 월간 Credits는 이월되지 않고, 표준 API의 충전액 기반 RPM·TPM 표와는 별도로 운영된다. 구독이 무조건 더 싸다고 가정하기보다 월간 사용량, 긴 프롬프트 비중, 팀 공유 여부를 계산해야 한다.

시작 전 준비사항

시험 데이터: 공개 자료나 비식별 샘플을 준비한다. 처음부터 고객 문서, 소스 전체, 비밀키를 넣지 않는다.
완료 기준: 답변 품질뿐 아니라 인용 위치, JSON 유효성, 도구 인자, 테스트 통과, 비용 상한을 정한다.
권한 분리: 읽기 도구와 쓰기 도구를 나누고, 삭제·배포·결제·메시지 전송은 사람 승인을 거치게 한다.
관찰 항목: 요청 ID, 입력·출력 토큰, 지연, 오류 코드, 도구 호출과 반환값을 기록한다.
중단 조건: 연속 실패 횟수, 최대 호출 수, 최대 비용, 실행 시간을 미리 제한한다.

OpenAI 호환 API로 최소 호출 만들기

API 키를 만든 뒤 로컬 터미널의 환경 변수에 저장한다. 저장소나 노트북 셀에 실제 키를 직접 적지 않는다. 아래 예시는 응답 형식만 확인하는 최소 Python 코드다.

export STEP_API_KEY="your_key_here"

pip install -U openai

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["STEP_API_KEY"],
    base_url="https://api.stepfun.ai/v1"
)

response = client.chat.completions.create(
    model="step-5-preview",
    messages=[
        {"role": "system", "content": "Return concise, sourced analysis."},
        {"role": "user", "content": "List three risks in this sample policy."}
    ],
    reasoning_effort="low",
    max_tokens=800
)

print(response.choices[0].message.content)
print(response.usage)

완료 확인은 문장이 출력됐는지만 보는 것이 아니다. 응답의 model, usage, 종료 이유, 콘솔의 요청 기록이 예상과 일치하는지 확인한다. 프리뷰 모델은 문서와 계정 권한이 빠르게 바뀔 수 있으므로 model does not exist가 나오면 이름을 임의로 바꾸지 말고 현재 계정의 모델 목록과 공식 문서를 다시 확인한다.

도구 호출은 두 단계로 검증한다

도구 호출에서 모델은 함수 이름과 인자를 제안한다. 애플리케이션은 그 인자를 스키마로 검증하고 실제 함수를 실행한 뒤, 결과를 tool 메시지로 다시 전달해야 한다. 첫 번째 응답에 tool_calls가 들어왔다고 업무가 완료된 것이 아니다.

읽기 전용 계산기나 검색 함수 한 개만 등록한다.
허용된 인자와 최대 길이를 서버에서 다시 검사한다.
실행 결과에 상태 코드와 출처를 붙여 모델에 돌려준다.
모델의 최종 답변이 도구 결과와 일치하는지 비교한다.
그 뒤에만 파일 수정 같은 제한된 쓰기 도구를 추가한다.

공식 문서는 최대 128개 함수를 설명하지만, 처음부터 많은 도구를 노출하면 선택 오류와 권한 검토 범위가 커진다. 작은 도구 집합으로 성공률과 오호출을 측정한 뒤 늘리는 편이 안전하다.

문서 분석·코드 변경·멀티모달 증거 작업을 정확도·비용·도구 실행·데이터 처리 기준으로 시험하는 평가 흐름 — 운영 전 시험은 서로 다른 업무를 분리하고, 정확도·도구 실행·비용·데이터 처리 기준을 통과한 작업만 사람 승인 뒤 확장하는 방식이 좋다.

Claude Code에서 1M 컨텍스트를 쓰는 설정

공식 연동 가이드는 사용자 설정 파일 ~/.claude/settings.json에 Step API 정보를 합치도록 안내한다. Step Plan을 쓸 때 최소 핵심은 ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL, model이다. 기존 permissions, hooks, MCP 설정을 지우고 파일 전체를 덮어쓰면 안 된다.

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "YOUR_STEP_API_KEY",
    "ANTHROPIC_BASE_URL": "https://api.stepfun.ai/step_plan",
    "CLAUDE_CODE_MAX_CONTEXT_TOKENS": "1000000",
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "1000000"
  },
  "model": "step-5-preview"
}

Claude Code는 낯선 모델 ID를 기본 200K 컨텍스트로 취급할 수 있다. 저장 후 완전히 종료·재시작하고 /status에서 모델·인증·설정 파일을, /context에서 약 1M 창을 확인한다. 공식 설정 스크립트는 두 컨텍스트 환경 변수를 자동으로 쓰지 않는다고 명시돼 있으므로 직접 확인이 필요하다.

실용적인 파일럿 3가지

1. 여러 계약서의 조항 비교

입력: 비식별 계약서 10~20개와 비교 기준표. 진행: 문서별 조항 위치를 먼저 추출하고, 차이 표와 누락 목록을 별도로 생성한다. 검토: 모든 결론에 파일명·페이지·원문 구간이 연결되는지 확인한다. 법률 판단은 담당자가 한다.

2. 작은 저장소의 버그 수정 제안

입력: 복제 가능한 샘플 저장소, 실패 테스트, 읽기 전용 탐색 도구. 진행: 원인 가설, 수정 계획, 패치, 테스트 순서로 산출물을 나눈다. 검토: diff 범위, 기존 테스트, 새 테스트, 의존성 변경을 확인한다. 처음에는 자동 병합과 배포를 금지한다.

3. 이미지·영상 증거를 포함한 조사

입력: 출처가 확인된 이미지, 5분 미만의 샘플 영상, 질문 목록. 진행: 관찰 사실과 해석을 분리하고 시간 구간·이미지 번호를 붙인다. 검토: 사람이 원본을 다시 열어 핵심 장면과 수치를 대조한다. 압축·프레임 샘플링 때문에 놓친 구간이 없는지도 확인한다.

비용·캐시·속도는 실제 사용량으로 계산하기

표준 API 가격표에서 Step 5 Preview는 100만 토큰당 캐시 미스 입력 1달러, 캐시 적중 입력 0.05달러, 출력 2.70달러다. 출력 토큰에는 내부 추론과 최종 답변이 함께 포함된다고 설명한다. 긴 컨텍스트를 여러 번 보내면 출력보다 반복 입력이 비용을 키울 수 있으므로 고정 지침과 공통 자료를 앞부분에 두고 변하는 질문을 뒤에 배치하는 구조가 유리하다.

다만 공식 모델 페이지와 가격표는 Step 5 Preview의 캐시를 안내하지만, 별도의 프롬프트 캐시 가이드는 지원 모델 목록에서 Step 5 Preview를 빼고 있다. 이 불일치가 해소되기 전에는 할인 가격을 예산에 확정 반영하지 말고, 실제 응답의 cached_tokens와 청구 기록으로 확인한다.

무료 충전 등급 V0의 표준 API 표에는 동시성 5, 10 RPM, 5M TPM이 적혀 있다. 이는 계정·시점에 따라 달라질 수 있고, Step Plan에는 같은 표가 적용되지 않는다. 파일럿에서 지연 평균만 보지 말고 P95 지연, 재시도 횟수, 제한 오류를 함께 기록해야 한다.

데이터와 권한 경계

API 키는 환경 변수나 비밀 저장소에 두고 브라우저 프런트엔드에 넣지 않는다.
고객 정보, 의료·법률 자료, 비공개 코드에는 조직의 승인과 데이터 처리 계약을 먼저 확인한다.
StepFun 개인정보 정책은 서버가 미국에 있다고 밝히며, 사용 기록과 입력 정보를 처리할 수 있는 범위를 설명한다. 일부 초기 접근 프로그램에서는 약관과 법이 허용하는 범위에서 프롬프트·출력·로그를 평가와 개선에 사용할 수 있다고 적혀 있다.
도구에는 최소 권한을 부여하고, 삭제·외부 전송·배포 같은 동작은 별도 승인과 감사 로그를 둔다.
벤더 데모와 자체 벤치마크는 참고 자료다. 실제 도입 판단은 같은 입력 세트로 다른 모델과 재현 가능한 비교를 해야 한다.

자주 막히는 문제와 확인 순서

401 invalid_api_key: 키 값, 환경 변수 이름, 선택한 채널을 확인한다.
404 또는 model does not exist: Base URL과 모델 접근 권한을 확인한다. 프리뷰 이름을 추측해 바꾸지 않는다.
Claude Code가 200K로 표시: 두 컨텍스트 환경 변수를 숫자 문자열 1000000으로 넣고 완전히 재시작한다.
도구가 실행되지 않음: 첫 응답의 tool_calls, 함수명, JSON 인자, 서버 실행 결과, 두 번째 모델 호출 순서로 본다.
예상보다 비용이 큼: 반복된 전체 대화, reasoning effort, 출력 길이, 캐시 실제 적중, 재시도를 확인한다.
긴 문서에서 근거를 놓침: 문서를 단락·파일 단위로 인덱싱하고 중간 근거표를 먼저 만든 뒤 최종 요약을 요청한다.

도입 판단 체크리스트

모델 ID와 실제 과금 채널을 기록했는가?
공개·비식별 데이터로 시작했는가?
정확도, 근거, 도구 성공률, 비용, 지연의 합격 기준이 있는가?
읽기와 쓰기 권한이 분리됐는가?
중단 조건과 사람 승인 지점이 있는가?
1M 컨텍스트가 필요한 이유를 작은 컨텍스트 모델과 비교했는가?
캐시 지원과 할인은 실제 사용량에서 확인했는가?

Step 5 Preview의 매력은 큰 컨텍스트 자체보다 긴 작업을 API·도구·멀티모달 입력과 연결할 수 있다는 점이다. 그러나 운영 품질은 모델 크기가 아니라 검증 루프와 권한 설계에서 결정된다. 관리형 에이전트 실행 환경의 역할을 더 비교하려면 OpenAI Agents API 가이드도 함께 볼 수 있다.

English version: Step 5 Preview Guide: Pilot a 1M-Context Agent API Safely

공식 출처

자료 확인일: 2026년 9월 21일. 프리뷰 모델, 가격, 지원 범위와 약관은 변경될 수 있으므로 실제 연결 전에 공식 문서를 다시 확인해야 한다.

이 블로그 검색

스택핀치