Documentation Index
Fetch the complete documentation index at: https://docs.fim.ai/llms.txt
Use this file to discover all available pages before exploring further.
API 참조 문서는 현재 영어로만 제공됩니다. 다른 언어로 이 페이지를 보고 있다면 영어 버전으로 전환하세요 — 왼쪽 사이드바에 전체 API 엔드포인트 목록이 표시됩니다.
기본 URL
인증
모든 API 요청은 API 키 또는 JWT 토큰을 통한 인증이 필요합니다.API 키 사용
Authorization 헤더에 API 키를 포함하세요:
JWT 토큰 사용
SSE 스트리밍 엔드포인트(/api/react 및 /api/dag)의 경우, 요청 본문에 토큰을 전달할 수 있습니다:
응답 형식
성공 응답
모든 성공적인 API 응답은 다음 구조를 따릅니다:오류 응답
오류 응답에는 오류 코드와 사람이 읽을 수 있는 메시지가 포함됩니다:페이지 매김 응답
목록 엔드포인트는 페이지 매김된 결과를 반환합니다:스트리밍 (Server-Sent Events)
채팅 엔드포인트 (POST /api/react 및 POST /api/dag)는 실시간 스트리밍을 위해 Server-Sent Events를 반환합니다. 각 이벤트는 콘텐츠를 나타내는 type 필드를 가집니다:
| 이벤트 타입 | 설명 |
|---|---|
step | ReAct 추론 단계 (도구 호출, 사고). 확장 사고 기능이 있는 모델(Claude, o-series, DeepSeek-R1)의 경우 도구 결정 단계 중 실시간 thinking_delta 콘텐츠 포함 |
step_progress | DAG 단계 진행 상황 (시작됨/반복/완료됨). 기본 에이전트가 추론 토큰을 스트리밍할 때 thinking_delta 콘텐츠 포함 가능 |
phase | 파이프라인 단계 전환 (계획/실행/분석) |
compact | 컨텍스트 압축 발생 |
answer | 스트리밍된 답변 텍스트 (시작/델타/완료) |
done | 최종 결과 페이로드 |
suggestions | 제안된 후속 질문 |
title | 자동 생성된 대화 제목 |
end | 스트림 종료자 (항상 마지막) |
SSE 스트림 예제
커서 기반 재개
모든 SSE 이벤트는 대화에 범위가 지정된 단조cursor 정수를 전달합니다. 클라이언트는 가장 높은 커서를 추적해야 합니다. 연결이 턴 중간에 끊어지면(네트워크 오류, 프록시 타임아웃, 서버 재시작), 클라이언트는 에이전트를 다시 실행하지 않고 다시 구독할 수 있습니다:
cursor > 42인 캐시된 이벤트를 재생하고 터미널 event: resume_done 프레임으로 끝나는 SSE 스트림입니다. cursor: -1을 전달하여 처음부터 전체 재생을 요청합니다.
오류 응답:
404 conversation_not_found— 대화 ID가 유효하지 않거나 인증된 사용자가 소유하지 않음404 no_recent_assistant_message— 대화에 재개할 지속된 어시스턴트 턴이 없음(예: 사용자 메시지가 없는 새로운 대화)400 invalid_cursor— 커서가 음이 아닌 정수 또는-1이 아님
useSseResume 훅)은 지수 백오프(300ms → 1s → 3s, 최대 3회 시도)로 네트워크 연결 끊김을 자동으로 재시도하고 의도하지 않은 재연결을 피하기 위해 사용자 시작 중단과 네트워크 오류를 구분합니다. 전체 패턴은 playground-page.tsx 통합을 참조하세요.
재개는 상태 비저장입니다 — 어시스턴트 메시지의 저장된
sse_events 배열에서 재생합니다. 에이전트의 턴이 어시스턴트 메시지가 지속되기 전에 중단된 경우(예: done 전에 충돌), 매달린 tool_use 블록은 다음 턴에 DbMemory._repair_dangling_tool_calls에 의해 자동으로 복구됩니다. 합성 tool_result 행은 metadata_.synthetic=true 및 metadata_.reason="interrupted"로 감사를 위해 지속됩니다.속도 제한
키별 속도 제한은 향후 릴리스에서 계획되어 있습니다. 현재는 강제된 키별 요청 제한이 없지만, API를 책임감 있게 사용해 주시기 바랍니다.페이지네이션
목록 엔드포인트는 쿼리 매개변수를 통한 페이지네이션을 지원합니다:page(기본값: 1) — 페이지 번호, 1부터 시작size(기본값: 20) — 페이지당 항목 수, 최대 100
타임스탬프
모든 타임스탬프는 UTC 시간대의 ISO 8601 형식입니다:오류 코드
일반적인 오류 코드 및 그 의미:| 오류 코드 | HTTP 상태 | 의미 |
|---|---|---|
unauthorized | 401 | 잘못되었거나 누락된 인증 |
forbidden | 403 | 사용자가 이 리소스에 대한 권한이 없음 |
not_found | 404 | 리소스가 존재하지 않음 |
bad_request | 400 | 잘못된 요청 매개변수 |
rate_limit_exceeded | 429 | 너무 많은 요청 (계획됨) |
internal_error | 500 | 서버 오류 |
API 플레이그라운드
각 엔드포인트 페이지에는 다음을 수행할 수 있는 대화형 API 플레이그라운드가 포함되어 있습니다:- 브라우저에서 직접 요청 테스트
- 실제 응답 보기
- 여러 언어로 요청 코드 복사
- API 키로 인증
API 플레이그라운드는 브라우저에서 요청을 실행하므로, API 키에 적절한 CORS 권한이 있는지 확인하세요(일반적으로 동일 출처 요청에 대해 기본적으로 활성화됨).
SDK 가용성
FIM One API는 완전히 REST 기반이지만, 인기 있는 언어로 SDK를 사용할 수 있습니다(또는 곧 출시될 예정입니다):- Python: 곧 출시 예정
- JavaScript/TypeScript: 곧 출시 예정
- Go: 곧 출시 예정
버전 관리
현재 API 버전은v0.8.0입니다. 버전은 URL 경로에 포함되지 않으며, 주요 변경 사항은 메이저 버전 업그레이드와 마이그레이션 기간을 통해 알려집니다.
지원
API 문제 또는 질문의 경우:- 문서: 각 엔드포인트에 대한 자세한 가이드 참조
- GitHub Issues: https://github.com/fim-ai/fim-one/issues에서 버그 보고
- Discord Community: 커뮤니티에 참여하여 토론