AI

{ "ai": true }

runlot deploy

배포하면 워커에서 env.ai를 쓸 수 있습니다. 만드는 명령은 없습니다 — 선언이 곧 부여입니다.

env.ai는 워커 안에서만 닿습니다. 워커 진입점 없이 정적 자산만 올리는 프로젝트는 쓸 수 없습니다.

호출하기

const r = await env.ai.run("anthropic/claude-sonnet-5", {
  messages: [{ role: "user", content: "주문 확인 메일 문구를 써 주세요." }],
  maxTokens: 1024,
});

r.text        // 생성된 텍스트
r.usage       // { inputTokens, outputTokens, cachedInputTokens }
r.model       // 실제로 호출된 모델 ID
r.stopReason  // 생성이 끝난 이유

메시지가 하나뿐이면 prompt로 줄여 쓸 수 있습니다. 사용자 메시지 하나를 적는 것과 같습니다.

const r = await env.ai.run("@runlot/nova-micro", { prompt: "한 줄로 요약해 주세요." });

role은 user와 assistant 둘뿐입니다. 시스템 프롬프트는 messages가 아니라 system에 적습니다.

스트리밍

stream: true면 SSE 조각의 ReadableStream이 돌아옵니다. 그대로 Response에 실어 브라우저로 보낼 수 있습니다.

const stream = await env.ai.run("@runlot/nova-micro", { prompt, stream: true });
return new Response(stream, { headers: { "content-type": "text/event-stream" } });

조각의 모양은 이렇습니다.

data: {"delta":"안녕"}

data: {"delta":"하세요"}

event: done
data: {"model":"@runlot/nova-micro"}

생성이 도중에 끊기면 마지막 조각이 event: error입니다.

event: error
data: {"message":"…"}

스트림이 시작된 뒤의 실패는 예외가 아니라 이 조각입니다. 첫 조각과 함께 200이 이미 나갔기 때문입니다. 스트림을 읽는 쪽에서 event: error를 다뤄 주세요.

카탈로그

이 프로젝트가 실제로 부를 수 있는 모델 목록은 코드에서 읽습니다.

const models = await env.ai.models();

차선은 둘이고, 파는 방식이 다릅니다.

카탈로그에 없는 모델 ID는 400입니다. 목록은 저희가 고른 고정 목록입니다.

무료 사용량

조직마다 하루 $0.11이 가성비 모델에 쓰입니다. UTC 자정에 초기화됩니다. 크레딧이 한 푼도 없어도 @runlot/… 모델은 매일 여기까지 부를 수 있습니다.

프론티어 모델에는 무료 사용량이 없습니다. 하루치를 프론티어에 열면 호출 한 번에 사라집니다 — 그 경험은 무료 티어가 아니라 고장입니다. anthropic/…·openai/…·google/…은 조직에 크레딧이 있어야 부를 수 있고, 없으면 402입니다.

크레딧은 금액입니다

크레딧은 금액 잔액이지 토큰 묶음이 아닙니다. 한 호출에서 빠져나가는 금액은 그 호출 시점의 가격표를 따릅니다.

프로바이더 정가는 움직입니다. 예를 들어 Google의 정가는 2027년 1월 1일부터 두 배가 됩니다. 크레딧을 토큰 묶음으로 팔면 그날 이미 산 사람의 몫이 조용히 다시 매겨집니다. 금액 잔액이 그것을 막습니다 — 산 것은 금액이고, 무엇을 얼마에 살지는 부를 때 정해집니다.

두 차선의 값은 같은 통화로 매겨집니다. 다른 것은 값의 출처뿐입니다. 따로 배울 단위는 없습니다.

화면과 CLI는 USD로 보여 줍니다. API와 --json 출력의 정수는 마이크로센트입니다 (1 마이크로센트 = 1e-8 USD). 센트로 적으면 작은 호출이 반올림에서 0이 되어 조용히 공짜가 되기 때문입니다 — 천 토큰짜리 호출 하나는 1센트의 100분의 1에도 못 미칩니다.

한도

오류

거절되거나 실패한 호출은 예외를 던집니다. 오류가 싣는 것은 둘입니다 — e.status(HTTP 상태)와 e.code(짧은 문자열).

rate_limited와 upstream_rate_limited는 응답에 Retry-After 헤더가 함께 나갑니다. too_many_concurrent에는 없습니다 — 자리가 언제 비는지는 저희도 말할 수 없기 때문입니다. 진행 중인 호출이 끝나면 풀립니다.

크레딧 충전

대시보드 조직 화면의 결제 탭에서 충전합니다.

자동 충전

잔액이 정한 값 아래로 내려가면 저장된 카드에 자동으로 충전합니다. 기본은 꺼짐입니다.

• 첫 충전은 손으로 합니다. 카드가 저장되는 자리가 그 결제이기 때문입니다. 저장된 결제 수단이 없으면 자동 충전을 켤 수 없습니다.
• 켜는 것은 명시적인 동의입니다. 결제 화면에 없는 상태에서 저장된 카드에 청구하는 것이라, 화면이 청구 조건을 문장 그대로 보여 주고 확인을 받습니다.
• 하루 5회가 곧 지출 상한입니다. 하루 최대 청구액은 5 × 충전 금액입니다. 버그가 난 코드가 호출을 루프로 돌아도 청구는 거기서 멈춥니다. 이 횟수는 바꿀 수 없습니다 — 더 필요하면 충전 금액을 올리세요.
• 기준 잔액은 0보다 커야 합니다. 충전은 비동기라, 충전이 끝날 때까지 버틸 잔액이 남아 있어야 합니다. 0을 주면 거절합니다.
• 기준 잔액은 충전 금액보다 작아야 합니다. 그렇지 않으면 한 번 충전해도 여전히 기준 아래라 하루 상한까지 계속 충전합니다. 이것도 거절합니다.
• 거절이 세 번 연속되면 자동 충전을 끕니다. 실패마다 알림을 보내고, 세 번째에 설정을 끕니다. 사용자 카드에 조용히 영원히 재시도하지 않습니다.

CLI

runlot ai                 # 호출·토큰·쓴 금액과 상한
runlot ai models          # 모델 목록과 1M 토큰당 단가
runlot ai credit          # 조직의 크레딧 잔액과 자동 충전 설정
runlot ai delete          # 끕니다 (admin)

셋 다 --json을 받습니다. 모델을 부르는 명령은 없습니다 — CLI는 워커 밖이고, env.ai는 워커 안에서만 닿습니다.

없는 것

• 임의 모델 패스스루. 카탈로그는 저희가 고르고 관리하는 고정 목록입니다.
• 밖에서 부르는 길. env.ai는 배포된 워커 안에서만 닿습니다. API 키도 없고, 외부 엔드포인트도 없고, Runlot 밖에서 부를 방법도 없습니다. 빠진 기능이 아니라 정해 둔 경계입니다.
• BYOK. 자기 프로바이더 키를 넣어 우리를 통해 부르는 길은 없습니다.
• 임베딩·벡터 검색, 파인튜닝, 이미지·음성 모델. 아직 없습니다.