Dify API 가이드 2026: REST로 앱에 AI 통합하기
Dify REST API를 사용하면 자체 코드에서 모든 Dify 앱을 호출할 수 있습니다 — 웹사이트에 챗봇을 임베드하거나, 문서 처리를 자동화하거나, SaaS 제품에 AI 기능을 통합하세요. 이 가이드는 API 키부터 스트리밍 응답 및 셀프 호스팅 설정까지 모든 것을 다룹니다.
Dify API란 무엇인가요?
Dify API는 모든 프로그래밍 언어나 플랫폼에서 Dify로 만든 모든 앱을 프로그래밍 방식으로 호출할 수 있게 하는 REST API입니다. Dify 앱(챗봇, 에이전트, 워크플로우 또는 완성 앱)을 게시하면 Secret Key로 호출할 수 있는 자체 API 엔드포인트를 받습니다.
Dify Cloud의 기본 URL은 https://api.dify.ai/v1입니다. 셀프 호스팅 시 자체 도메인으로 대체합니다: https://your-server.com/v1.
일반적인 사용 사례
웹사이트 챗봇
Dify 위젯 없이 모든 웹사이트에 AI 채팅을 임베드합니다.
문서 자동화
PDF 또는 텍스트를 Dify 워크플로우로 보내고 구조화된 출력을 받습니다.
SaaS AI 기능
기존 제품에 AI 작성, 요약 또는 Q&A를 추가합니다.
백엔드 파이프라인
cron 작업, 웹훅 또는 큐 프로세서에서 Dify 에이전트를 트리거합니다.
모바일 앱
표준 HTTP를 통해 iOS 또는 Android 앱에서 Dify를 호출합니다.
노코드 도구
HTTP 요청 노드를 통해 n8n, Make 또는 Zapier와 Dify를 연결합니다.
API 키 만들기
각 Dify 앱은 자체 API 키를 가집니다. API를 통해 액세스하려는 각 앱에 대해 하나를 만들어야 합니다. 방법은 다음과 같습니다:
Studio에서 Dify 앱 열기
cloud.dify.ai(또는 셀프 호스팅 URL)로 이동하여 API를 통해 호출하려는 앱을 엽니다.
오른쪽 상단의 "API Access" 클릭
이렇게 하면 해당 앱의 API 참조 패널이 열립니다.
"API 키 만들기" 클릭
나중에 식별하기 위해 이름을 지정합니다(예: "production" 또는 "test").
Secret Key를 즉시 복사
키는 한 번만 표시됩니다. 환경 변수로 저장하세요 — 소스 코드에 직접 절대 포함하지 마세요.
Authorization 헤더에서 사용
모든 API 요청에는 이 헤더가 필요합니다: Authorization: Bearer YOUR_API_KEY
API 엔드포인트 개요
Dify API는 메시지 보내기, 대화 관리, 파일 업로드 등을 위한 엔드포인트를 제공합니다. 모든 엔드포인트는 기본 URL https://api.dify.ai/v1 기준입니다.
| 메서드 | 엔드포인트 | 설명 |
|---|---|---|
| POST | /chat-messages | 채팅 메시지를 보내고 응답을 받습니다. blocking 및 streaming을 지원합니다. |
| POST | /completion-messages | 완성 앱에 프롬프트를 보냅니다. 생성된 텍스트를 반환합니다. |
| POST | /files/upload | RAG 또는 비전 앱용 파일을 업로드합니다(PDF, 이미지 등). |
| GET | /conversations | 사용자의 모든 대화를 나열합니다. 필터링에 user 매개변수를 사용합니다. |
| GET | /messages | 특정 대화의 메시지 기록을 가져옵니다. |
| DELETE | /conversations/:id | 대화와 모든 메시지를 영구적으로 삭제합니다. |
| POST | /messages/:id/feedbacks | 특정 메시지에 평가(좋아요/싫어요)를 제출합니다. |
| GET | /parameters | 앱의 입력 매개변수, 소개 텍스트, 제안 질문을 가져옵니다. |
첫 번째 API 호출
실제 API 호출을 해봅시다. YOUR_API_KEY를 실제 키로 교체하세요. user 필드는 최종 사용자의 고유 식별자입니다 — 시스템에서 이 사용자를 식별하는 임의의 문자열을 사용하세요.
curl 예제
curl -X POST 'https://api.dify.ai/v1/chat-messages' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"inputs": {},
"query": "안녕하세요! 무엇을 도와드릴까요?",
"response_mode": "blocking",
"conversation_id": "",
"user": "user-123"
}'응답 예제
{
"event": "message",
"task_id": "abc123",
"id": "msg_456",
"message_id": "msg_456",
"conversation_id": "conv_789",
"mode": "chat",
"answer": "안녕하세요! 질문, 텍스트 작성, 분석 등 다양한 것을 도와드릴 수 있습니다. 무엇이 궁금하신가요?",
"metadata": { "usage": { "prompt_tokens": 12, "completion_tokens": 22 } },
"created_at": 1711234567
}Python 예제 (requests 사용)
import requests
API_KEY = "your_api_key_here"
BASE_URL = "https://api.dify.ai/v1"
def chat(query, conversation_id="", user="user-123"):
response = requests.post(
f"{BASE_URL}/chat-messages",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json={
"inputs": {},
"query": query,
"response_mode": "blocking",
"conversation_id": conversation_id,
"user": user,
}
)
response.raise_for_status()
return response.json()
# 첫 번째 메시지
result = chat("Dify란 무엇인가요?")
print(result["answer"])
conversation_id = result["conversation_id"]
# 같은 대화에서 후속 질문
result2 = chat("더 자세히 설명해 주시겠어요?", conversation_id=conversation_id)
print(result2["answer"])conversation_id를 저장하고 후속 호출에서 전달하세요. 이렇게 하면 대화 기록이 유지되고 AI가 이전에 말한 내용을 기억합니다.
스트리밍 응답 (SSE)
스트리밍을 사용하면 생성 중에 토큰을 표시할 수 있습니다 — ChatGPT의 타이핑 효과처럼. Dify는 스트리밍을 위해 서버 전송 이벤트(SSE)를 사용합니다. 요청 본문에 "response_mode": "streaming"을 설정하세요.
각 이벤트는 data: 접두사가 있는 줄로 도착합니다. 이벤트 유형에는 message(토큰 청크), message_end(메타데이터가 포함된 완료 메시지), error가 포함됩니다.
스트리밍 curl 예제
curl -X POST 'https://api.dify.ai/v1/chat-messages' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--no-buffer \
-d '{
"inputs": {},
"query": "AI에 관한 짧은 시를 써주세요.",
"response_mode": "streaming",
"conversation_id": "",
"user": "user-123"
}'Python 스트리밍 예제
import requests
import json
def stream_chat(query, user="user-123"):
with requests.post(
"https://api.dify.ai/v1/chat-messages",
headers={
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
},
json={
"inputs": {},
"query": query,
"response_mode": "streaming",
"conversation_id": "",
"user": user,
},
stream=True,
) as response:
for line in response.iter_lines():
if line and line.startswith(b"data: "):
data = json.loads(line[6:])
if data.get("event") == "message":
print(data["answer"], end="", flush=True)
elif data.get("event") == "message_end":
print()
break
stream_chat("양자 컴퓨팅을 쉽게 설명해 주세요.")셀프 호스팅 설치에서 Dify API 사용
자체 서버에 Dify를 호스팅하는 경우 API는 동일하게 작동합니다 — 기본 URL만 교체하면 됩니다. 이것이 셀프 호스팅의 주요 장점입니다: 인프라를 제어하고, 데이터가 서버에 유지되며, 메시지 크레딧 제한이 없습니다.
Dify Cloud
BASE_URL = "https://api.dify.ai/v1"셀프 호스팅
BASE_URL = "https://your-server.com/v1"나머지 모든 것 — API 키 형식, 요청 본문, 응답 형식, 스트리밍 — 은 동일하게 유지됩니다. 이를 통해 Dify Cloud에 대해 개발하고 환경 변수 하나만 변경하여 프로덕션의 셀프 호스팅 인스턴스로 쉽게 전환할 수 있습니다.
API 집약적 워크로드를 위한 최고의 호스팅 옵션
자주 묻는 질문
Dify API 키를 어떻게 얻나요?
Dify 앱을 열고 오른쪽 상단의 'API Access'를 클릭한 후 새 API 키를 만듭니다. Secret Key를 복사하세요 — 한 번만 표시됩니다. Authorization 헤더에서 'Bearer YOUR_KEY'로 사용하세요.
Dify API는 무료인가요?
Dify API 자체는 무료입니다 — 소비된 LLM 토큰(OpenAI, Anthropic 등)에 대해서만 비용을 지불합니다. 셀프 호스팅 Dify는 API 비용이 없습니다. Dify Cloud는 메시지 크레딧에 따라 청구됩니다.
Dify API 응답을 스트리밍할 수 있나요?
예. 요청 본문에 'response_mode':'streaming'을 설정하여 서버 전송 이벤트(SSE)를 받으세요. ChatGPT처럼 토큰이 생성되는 동안 표시할 수 있습니다.
어떤 프로그래밍 언어가 Dify API와 함께 작동하나요?
HTTP 요청을 지원하는 모든 언어: Python, JavaScript/Node.js, PHP, Ruby, Go, Java, C# 등. Dify는 Python과 Node.js용 공식 SDK와 각 엔드포인트에 대한 curl 예제를 제공합니다.
Dify를 셀프 호스팅할 준비가 되셨나요?
셀프 호스팅으로 Dify API를 최대한 활용하세요: 크레딧 제한 없음, 완전한 데이터 프라이버시, 자체 도메인, 동일한 API 인터페이스. 필요에 맞는 최고의 호스팅 옵션을 비교해 보세요.