에이전트가 처음 보낼 호출 네 가지
한 번에 한 단계씩 열어 보세요. 1단계에서 설정한 TUTORFLOW_KEY와 CLASSROOM_ID를 나머지 단계에서 그대로 씁니다.
curl과 jq가 필요합니다. 실행하기 전에 slug와 이메일을 바꿔 주세요.
1에이전트 등록
키 없이 호출 한 번이면 됩니다. 응답에 contentApiKey, defaultClassroomId, 체험 크레딧 50개가 담겨 옵니다. 키는 한 번만 보여 주니 꼭 보관하세요.
RESPONSE=$(curl -s -X POST https://api.tutorflow.io/v1/platform/agent/register \
-H "Content-Type: application/json" \
-d '{"name":"My Agent","slug":"my-agent-2048","email":"you@example.com"}')
export TUTORFLOW_KEY=$(echo "$RESPONSE" | jq -r .contentApiKey)
export CLASSROOM_ID=$(echo "$RESPONSE" | jq -r .defaultClassroomId)2강의 생성 시작
튜터플로우가 백그라운드에서 강의를 만들고, runId와 함께 202로 응답합니다. 수업 하나짜리 강의는 6크레딧입니다.
RUN_ID=$(curl -s -X POST \
"https://api.tutorflow.io/v1/content/classrooms/$CLASSROOM_ID/courses/generate" \
-H "Authorization: Bearer $TUTORFLOW_KEY" \
-H "Content-Type: application/json" \
-d '{"topic":"Fractions for grade 4","lessonCount":1}' | jq -r .runId)3진행 상황 확인
status가 completed나 failed가 될 때까지 20~30초마다 run을 조회하세요. 완료되면 resourceId에 새 강의의 ID가 담겨 옵니다.
curl -s "https://api.tutorflow.io/v1/content/classrooms/$CLASSROOM_ID/runs/$RUN_ID" \
-H "Authorization: Bearer $TUTORFLOW_KEY" | jq '{status, resourceId, error}'4답안 채점
채점 결과는 바로 돌아옵니다. 점수와 잘한 점, 고칠 점이 함께 오고, 한 번에 1크레딧이 듭니다.
요청
curl -s -X POST "https://api.tutorflow.io/v1/content/classrooms/$CLASSROOM_ID/evaluations" \
-H "Authorization: Bearer $TUTORFLOW_KEY" \
-H "Content-Type: application/json" \
-d '{
"evaluationType": "open_ended",
"questionText": "Explain photosynthesis",
"learnerAnswer": "Plants use sunlight to convert CO2 and water into glucose.",
"maxScore": 10,
"language": "en",
"learnerExternalId": "learner-42"
}'응답
{
"id": "5023...",
"status": "COMPLETED",
"evaluationType": "open_ended",
"learner": { "externalId": "learner-42", "name": null },
"score": 7,
"maxScore": 10,
"normalizedScore": 70,
"strengths": ["Correctly identifies sunlight as key factor"],
"suggestions": ["Mention the role of chlorophyll", "Explain the chemical equation"],
"feedbackSummary": "Good foundational understanding. To improve, include the role of chlorophyll."
}터미널이 편하다면 CLI로
@tutorflow/cli로 같은 호출을 할 수 있습니다. agent register가 키를 ~/.tutorflow/config.json에 저장하므로, 이후 명령에는 키나 클래스룸 옵션을 따로 붙이지 않아도 됩니다.
npm install -g @tutorflow/cli
tutorflow agent register --name "My Agent" --slug my-agent-2048 --email you@example.com
tutorflow course generate "Fractions for grade 4" --lessons 1 --wait
tutorflow evaluate --type open-ended --question "Explain photosynthesis" \
--student-answer "Plants use sunlight to make glucose." --learner-id learner-42에이전트 혼자서도 일할 수 있도록
Content API 키 하나로 REST, MCP, CLI를 모두 쓸 수 있습니다. 모든 기능은 REST로, 가입·결제·강의·채점은 MCP로도 호출하세요.
학습자 답안 채점
답안과 함께 채점 기준이나 모범 답안을 보내면 점수와 잘한 점, 고칠 점을 필드별로 나눠 응답합니다.
수업 자료 만들기
강의, 시험, 슬라이드, 영상, 학습 모듈을 호출 한 번으로 시작하고, 끝날 때까지 진행 상황을 확인하세요.
MCP 도구로 호출
서버 URL과 키만 추가하면 Claude Code를 비롯한 MCP 클라이언트가 튜터플로우를 도구로 씁니다.
에이전트가 직접 가입
에이전트가 직접 계정을 만들면 키와 클래스룸, 체험 크레딧 50개를 한 번에 받습니다.
호출마다 정해진 비용
작업마다 정해진 크레딧이 잔액 하나에서 빠져나갑니다(1크레딧 2센트). 실행 전에 estimatedCredits로 비용을 먼저 확인하고, 속도 제한은 응답 헤더에서 살펴보세요.
용도별로 나누는 키
테스트 키와 라이브 키를 나눠 쓰고, 키마다 권한을 정하고 교체하세요. 테스트 키는 샌드박스 클래스룸에서 동작해 크레딧을 쓰지 않습니다.
작업이 끝나면 바로 알림
웹훅을 등록하면 생성 작업, 영상 렌더링, 채점이 끝나는 순간 서명된 요청을 받습니다.
에이전트가 고른 언어로
에이전트가 요청한 언어로 콘텐츠와 피드백을 만듭니다.
에이전트를 위해 설계했습니다. 사람만을 위한 도구가 아닙니다.
에이전트가 튜터플로우의 도구를 스스로 찾아 씁니다. 가입, 잔액 확인, 강의 생성, 진행 상황 확인, 답안 채점까지 HTTP 코드 없이 처리하세요.
- MCP 클라이언트 설정에 서버 한 줄만 넣으면 Claude, Gemini 등 어떤 클라이언트든 연결됩니다
- 에이전트가 직접 가입하고, 같은 호출로 키를 받습니다
- 크레딧이 부족하면 사람에게 결제 링크를 보내거나, x402가 켜져 있다면 USDC로 직접 결제합니다
- 입력 형식이 정해져 있어, 잘못 호출하면 무엇이 틀렸는지 바로 알려 줍니다
Claude Code
// .mcp.json: add to your project root
{
"mcpServers": {
"tutorflow": {
"type": "http",
"url": "https://mcp.tutorflow.io/api/mcp",
"headers": {
"Authorization": "Bearer tf_content_..."
}
}
}
}MCP SDK
import { Client } from '@modelcontextprotocol/sdk/client/index.js'
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'
const transport = new StreamableHTTPClientTransport(
new URL('https://mcp.tutorflow.io/api/mcp'),
{
requestInit: {
headers: { Authorization: 'Bearer tf_content_...' },
},
},
)
const client = new Client({ name: 'my-agent', version: '1.0.0' })
await client.connect(transport)
// Call tools directly
const result = await client.callTool('run_evaluation', {
evaluationType: 'open_ended',
questionText: 'Explain photosynthesis',
learnerAnswer: 'Plants use sunlight to make glucose...',
})직접 가입
// No auth needed: agents register themselves
POST https://api.tutorflow.io/v1/platform/agent/register
{
"name": "My AI Tutor",
"slug": "my-ai-tutor",
"email": "agent@example.com",
"agentIdentity": "claude-3-5-sonnet"
}
// Returns a Content API key and the classroom it works in
// { "contentApiKey": "tf_content_...", "defaultClassroomId": "...", "trialContentCredits": 50 }에이전트가 만든 만큼만 내세요
모든 호출은 계정의 크레딧 잔액 하나에서 차감되며, 크레딧 1개는 2센트입니다. 아래는 에이전트에 실제로 적용되는 실시간 요금표입니다.
| 만드는 것 | 크레딧 | 미국 달러 |
|---|---|---|
| 개요와 모든 수업을 갖춘 강의 | 3 크레딧 + 수업당 6 크레딧 | US$0.06 + 수업당 US$0.12 |
| 학습 모듈 1개 | 수업당 6 크레딧 | 수업당 US$0.12 |
| 자동 채점 문항이 담긴 시험 | 시험당 3 크레딧 | 시험당 US$0.06 |
| 슬라이드의 텍스트 페이지 | 텍스트 페이지당 1 크레딧 | 텍스트 페이지당 US$0.02 |
| AI 이미지가 들어간 슬라이드 페이지 | 이미지 페이지당 3 크레딧 | 이미지 페이지당 US$0.06 |
| 영상 장면 내레이션 | 장면당 1 크레딧 | 장면당 US$0.02 |
| 영상을 MP4로 렌더링 | 렌더링당 3 크레딧 | 렌더링당 US$0.06 |
| 바로 플레이할 수 있는 게임 | 게임당 41 크레딧 | 게임당 US$0.82 |
| 답안 하나 채점 | 요청당 1 크레딧 | 요청당 US$0.02 |
결제 방식
- 이메일 인증을 마치면 카드나 Base 네트워크의 USDC로 5달러부터 충전할 수 있습니다.
- 카드를 등록해 두면 크레딧이 떨어져도 작업이 이어지고, 그만큼 카드로 청구됩니다.
- 새 계정에는 무료 크레딧 50개가 들어 있습니다.
- 테스트 키는 샌드박스 클래스룸에서만 동작하며 크레딧을 쓰지 않습니다.