채팅 API

마인드에 메시지를 보내고 AI가 생성한 응답을 받으세요. 채팅 API는 상태 비저장(stateless) 완료와 자동 기록 관리가 포함된 상태 저장(stateful) 멀티턴 대화를 모두 지원합니다.

상태 저장 채팅 (권장)

서버가 대화 기록, 컨텍스트 압축, 롤링 요약을 자동으로 관리하는 영구적인 대화를 생성합니다. 요청할 때마다 전체 메시지 기록을 보낼 필요가 없습니다.

채팅 생성

마인드에 연결된 새로운 상태 저장 대화를 생성합니다.

엔드포인트: POST /api/v1/chats

헤더:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

요청 본문:

{
  "name": "My Conversation",
  "sparkId": "your-spark-id"
}

응답 (201):

{
  "data": {
    "id": "601af953-3837-49c1-a31e-4fdbfa82ac04",
    "name": "My Conversation",
    "description": null,
    "createdAt": "2026-04-04T12:45:24.078Z",
    "sparks": [
      {
        "id": "4774888e-0a03-40d7-979b-39b47c4c049c",
        "name": "Ada Lovelace",
        "discipline": "mathematician and computer scientist"
      }
    ]
  }
}

메시지 보내기

기존 채팅에 메시지를 보냅니다. 서버가 대화 기록, 컨텍스트 창 압축, 롤링 요약을 자동으로 처리합니다.

엔드포인트: POST /api/v1/chats/{chatId}/messages

헤더:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

요청 본문:

{
  "content": "What are the latest advancements in solar panel technology?"
}

상태 저장 채팅 모델 선택은 다음 순서를 따릅니다: 요청별 재정의, 팀의 선호 제공자(설정 및 자격이 있는 경우), 제품 기본값. 이 엔드포인트에서는 부분 재정의가 400 Bad Request로 거부됩니다. model와 provider를 모두 보내거나 둘 다 생략해야 합니다.

응답:

{
  "content": "Recent advancements in solar panel technology include perovskite cells with 30%+ efficiency...",
  "messageId": "cmnkbsddh00033v01ptk9t4et"
}

멀티턴 예시

상태 저장 채팅에서는 매번 새 메시지만 보내면 됩니다. 서버가 모든 것을 기억합니다:

# Step 1: Create a chat
CHAT=$(curl -s -X POST "https://getminds.ai/api/v1/chats" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Research Session", "sparkId": "your-spark-id" }')

CHAT_ID=$(echo $CHAT | jq -r '.data.id')

# Step 2: Send messages (server manages history automatically)
curl -X POST "https://getminds.ai/api/v1/chats/$CHAT_ID/messages" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "content": "What are the top marketing trends?" }'

# Step 3: Follow up (the mind remembers the previous exchange)
curl -X POST "https://getminds.ai/api/v1/chats/$CHAT_ID/messages" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Which of those would work best on a small budget?" }'

내부 동작 방식:

• 모든 메시지는 데이터베이스에 영구 저장됩니다
• 최근 8개 메시지는 전체 컨텍스트로 전송됩니다
• 오래된 메시지는 롤링 LLM 요약으로 압축됩니다
• 컨텍스트 제한에 도달하지 않고 몇 주 또는 몇 달 동안 대화를 이어갈 수 있습니다

상태 비저장 완료

단일 요청이나 대화 기록을 직접 관리하고 싶을 때 사용합니다.

메시지 보내기

마인드에 메시지를 보내고 응답을 받습니다.

엔드포인트: POST /api/v1/sparks/{sparkId}/completion

헤더:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

요청 본문

{
  "messages": [
    {
      "role": "user",
      "content": "What are the latest advancements in solar panel technology?"
    }
  ]
}

파라미터

응답

{
  "messageId": "msg_550e840029b141d4a716446655440000",
  "content": "Recent advancements in solar panel technology include perovskite cells with 30%+ efficiency, bifacial panels that capture light from both sides, and integrated storage systems...",
  "metadata": {
    "ragCitations": [
      {
        "id": "abc123",
        "displaySource": "Spark knowledge",
        "similarity": 0.89
      }
    ]
  }
}

단일 메시지 예시

단일 질문하기:

curl -X POST "https://getminds.ai/api/v1/sparks/spark-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What are the top 3 marketing trends for 2025?"
      }
    ]
  }'

멀티턴 대화

이전 메시지를 포함하여 대화 컨텍스트를 유지합니다:

curl -X POST "https://getminds.ai/api/v1/sparks/spark-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What are the top marketing trends?"
      },
      {
        "role": "assistant",
        "content": "The top trends are AI personalization, short-form video, and community building..."
      },
      {
        "role": "user",
        "content": "How can I implement AI personalization on a budget?"
      }
    ]
  }'

멀티턴 대화 팁:

• 각 요청에 전체 대화 기록을 포함하세요
• 순서가 중요합니다: 메시지는 시간순이어야 합니다
• user와 assistant 역할을 번갈아 사용하세요
• 마지막 메시지는 항상 user 역할이어야 합니다

파일 첨부

파일, 문서, 이미지, 링크를 첨부하여 마인드에 컨텍스트를 제공하세요. 마인드는 처리된 콘텐츠를 대화의 일부로 받습니다.

파일 첨부하기

사용자 메시지의 metadata.attachedFiles 배열을 통해 파일을 추가하세요:

curl -X POST "https://getminds.ai/api/v1/sparks/spark-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Please review this document and summarize the key points",
        "metadata": {
          "attachedFiles": [
            {
              "url": "https://example.com/quarterly-report.pdf",
              "name": "Q4 2025 Report",
              "type": "application/pdf"
            },
            {
              "path": "uploads/meeting-notes.docx",
              "name": "Strategy Meeting Notes"
            }
          ]
        }
      }
    ]
  }'

첨부 파일 형식

각 첨부 파일 객체는 다음을 지원합니다:

참고: url 또는 path 중 하나만 제공해야 하며, 둘 다 제공할 수는 없습니다.

지원 파일 형식

문서:

• PDF (.pdf) - 텍스트 추출 + 스캔된 페이지 OCR
• Word (.docx) - 전체 텍스트 추출
• Text (.txt, .md) - 직접 텍스트 콘텐츠
• CSV/Excel (.csv, .xlsx) - 표 추출

이미지:

• PNG, JPG, WEBP - OCR + 시각적 분석
• 이미지 이해를 위한 비전 기능

외부 URL:

• Firecrawl로 가져온 웹 페이지 (JS 렌더링 + 스크린샷)
• 자동 마크다운 변환

처리

파일은 마인드에 전송되기 전에 자동으로 처리됩니다:

1. 다운로드 - URL 또는 Supabase 스토리지에서 파일 가져오기
2. 추출 - 콘텐츠 추출 (PDF에서 텍스트, 이미지에서 OCR 등)
3. 주입 - 처리된 콘텐츠를 대화 컨텍스트에 추가
4. 응답 - 마인드가 메시지와 파일 콘텐츠를 모두 확인

처리 제한:

• 타임아웃: 파일당 30초
• 파일 병렬 처리
• 실패한 파일은 정상적인 대체 메시지 표시

다중 파일 예시

{
  "messages": [
    {
      "role": "user",
      "content": "Compare these two proposals and recommend which one to pursue",
      "metadata": {
        "attachedFiles": [
          {
            "url": "https://example.com/proposal-a.pdf",
            "name": "Proposal A - Cloud Migration",
            "type": "application/pdf"
          },
          {
            "url": "https://example.com/proposal-b.pdf",
            "name": "Proposal B - On-Prem Upgrade",
            "type": "application/pdf"
          },
          {
            "path": "uploads/budget-analysis.xlsx",
            "name": "Budget Comparison"
          }
        ]
      }
    }
  ]
}

대화 기록의 파일 첨부

파일 첨부가 있는 대화를 계속할 때, 원본 메시지와 첨부 파일을 기록에 포함하세요:

{
  "messages": [
    {
      "role": "user",
      "content": "Analyze this sales data",
      "metadata": {
        "attachedFiles": [
          {
            "url": "https://example.com/sales-q4.csv",
            "name": "Q4 Sales Data"
          }
        ]
      }
    },
    {
      "role": "assistant",
      "content": "Based on the Q4 sales data, I can see that revenue increased by 23% compared to Q3..."
    },
    {
      "role": "user",
      "content": "What were the top 3 performing products?"
    }
  ]
}

참고: 파일은 처음 첨부될 때 한 번만 처리됩니다. 동일한 대화의 후속 메시지는 이미 처리된 콘텐츠를 참조합니다.

웹 링크

웹 페이지 및 외부 콘텐츠의 경우 url 필드를 사용하세요:

{
  "messages": [
    {
      "role": "user",
      "content": "Summarize the key findings from this research paper",
      "metadata": {
        "attachedFiles": [
          {
            "url": "https://arxiv.org/pdf/2103.12345.pdf",
            "name": "AI Research Paper",
            "type": "application/pdf"
          }
        ]
      }
    }
  ]
}

특히 웹 페이지의 경우:

• JavaScript가 많은 사이트는 Firecrawl로 렌더링됩니다
• 시각적 컨텍스트를 위해 스크린샷이 캡처됩니다
• 콘텐츠가 깔끔한 마크다운으로 변환됩니다

오류 처리

파일 처리가 실패하는 경우:

• 마인드는 파일이 첨부되었지만 처리에 실패했다는 대체 메시지를 받습니다
• 대화는 정상적으로 계속됩니다
• 타임아웃 오류는 [Processing timeout - file may be too large]를 표시합니다
• 기타 오류는 [Processing failed - file uploaded but analysis unavailable]를 표시합니다

이를 통해 처리가 실패하더라도 마인드가 첨부 시도를 인지할 수 있습니다.

초기 메시지 (인사말)

메시지 배열을 비우거나 메시지를 보내지 않으면 마인드가 자신을 소개합니다:

curl -X POST "https://getminds.ai/api/v1/sparks/spark-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": []
  }'

응답:

{
  "content": "Hi! I'm Sarah, a marketing director with 15 years of experience in B2B SaaS. I specialize in growth marketing and data-driven strategies. What can I help you with today?"
}

모델 재정의

model 파라미터를 전달하여 상태 비저장 완료 요청에 사용되는 AI 모델을 선택적으로 재정의할 수 있습니다. 이는 벤치마킹, 비용 최적화 또는 다른 모델 동작을 테스트하는 데 유용합니다. 상태 저장 채팅 및 패널 엔드포인트는 더 엄격한 재정의 유효성 검사를 사용합니다: model와 provider를 함께 보내야 합니다.

curl -X POST "https://getminds.ai/api/v1/sparks/spark-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What are your thoughts on sustainable packaging?"
      }
    ],
    "model": "gpt-4o-mini"
  }'

model가 지정되지 않은 경우 서버 기본값이 사용됩니다.

제공자

제공자가 지원하는 모든 모델 문자열을 전달할 수 있습니다. 제공자는 일반적인 모델 이름 접두사(claude- → Anthropic, gemini- → Google, gpt-/o1/o3/o4 → OpenAI)에서 자동 감지됩니다.

이름이 모호한 모델의 경우 provider를 명시적으로 지정하세요:

{
  "messages": [...],
  "model": "my-custom-fine-tune",
  "provider": "openai"
}

제공자를 결정할 수 없는 경우 API는 이를 지정하라는 400 Bad Request 오류를 반환합니다.

구조화된 출력

response_format 파라미터를 사용하여 특정 스키마와 일치하는 보장된 JSON 응답을 요청합니다. 이는 OpenAI 스타일의 구조화된 출력 패턴을 따르며 대화에서 구조화된 데이터를 추출하는 데 유용합니다.

JSON 스키마 모드

모델이 스키마와 일치하는 유효한 JSON을 출력하도록 강제합니다:

curl -X POST "https://getminds.ai/api/v1/sparks/spark-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Analyze the sentiment of this text: I love this product, it exceeded all my expectations!"
      }
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "sentiment_analysis",
        "description": "Sentiment analysis result",
        "schema": {
          "type": "object",
          "properties": {
            "sentiment": {
              "type": "string",
              "enum": ["positive", "negative", "neutral"]
            },
            "confidence": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            },
            "keywords": {
              "type": "array",
              "items": { "type": "string" }
            }
          },
          "required": ["sentiment", "confidence", "keywords"]
        }
      }
    }
  }'

응답:

{
  "content": "{\"sentiment\": \"positive\", \"confidence\": 0.95, \"keywords\": [\"love\", \"exceeded\", \"expectations\"]}",
  "parsed": {
    "sentiment": "positive",
    "confidence": 0.95,
    "keywords": ["love", "exceeded", "expectations"]
  }
}

JSON 객체 모드

스키마 유효성 검사 없이 JSON 출력을 강제합니다:

curl -X POST "https://getminds.ai/api/v1/sparks/spark-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "List 3 marketing ideas as JSON"
      }
    ],
    "response_format": {
      "type": "json_object"
    }
  }'

응답 형식 유형

JSON 스키마 필드

지원되는 스키마 기능

다음 JSON 스키마 기능이 지원됩니다:

• 타입: string, number, integer, boolean, array, object, null
• 제약 조건: enum, minimum, maximum, minLength, maxLength, minItems, maxItems
• 구조: properties, required, items, additionalProperties
• 메타데이터: description (모델을 안내하는 데 사용됨)

참고

• 도구(RAG, 웹 검색 등)는 구조화된 출력과 함께 작동합니다. 마인드는 구조화된 응답을 생성하기 전에 지식 베이스를 검색할 수 있습니다.
• parsed 필드는 편의를 위해 파싱된 JSON 객체를 포함합니다. content는 원시 JSON 문자열을 포함합니다.
• 모든 주요 제공자(OpenAI, Anthropic, Google)는 구조화된 출력을 지원합니다.
• 복잡한 스키마의 경우, description 필드를 추가하여 모델의 출력을 유도하는 것을 고려하세요.

도구 호출

대화 중에 마인드가 사용자 지정 함수를 호출할 수 있도록 합니다. 이는 OpenAI 호환 함수 호출 패턴을 따르며 외부 도구 및 API로 마인드의 기능을 확장할 수 있게 해줍니다.

작동 방식

1. 도구 정의: 이름, 설명, JSON 스키마 파라미터로 도구 정의를 전달합니다.
2. 마인드 결정: 마인드는 대화에 따라 언제 도구를 호출할지 결정합니다 (또는 tool_choice로 강제할 수 있습니다).
3. API가 도구 호출 반환: 응답에는 도구 이름과 생성된 인수가 포함된 tool_calls가 포함됩니다.
4. 도구 실행: 애플리케이션에서 도구를 실행하고 결과를 얻습니다.
5. 결과 다시 보내기: role: "tool"를 사용하여 다음 메시지에 도구 결과를 포함합니다.
6. 마인드 응답: 마인드는 도구 결과를 최종 응답에 통합합니다.

기본 예시

도구가 포함된 요청:

curl -X POST "https://getminds.ai/api/v1/sparks/spark-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is the weather in Berlin?"
      }
    ],
    "tools": [
      {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "description": "City name"
            },
            "units": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"],
              "description": "Temperature units"
            }
          },
          "required": ["city"]
        }
      }
    ]
  }'

응답:

{
  "content": "",
  "tool_calls": [
    {
      "id": "call_abc123",
      "name": "get_weather",
      "arguments": {
        "city": "Berlin",
        "units": "celsius"
      }
    }
  ]
}

도구를 실행하고 결과를 다시 보냅니다:

curl -X POST "https://getminds.ai/api/v1/sparks/spark-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is the weather in Berlin?"
      },
      {
        "role": "assistant",
        "content": "",
        "tool_calls": [
          {
            "id": "call_abc123",
            "name": "get_weather",
            "arguments": {
              "city": "Berlin",
              "units": "celsius"
            }
          }
        ]
      },
      {
        "role": "tool",
        "tool_call_id": "call_abc123",
        "content": "{\"temperature\": 18, \"condition\": \"partly cloudy\", \"humidity\": 65}"
      }
    ],
    "tools": [
      {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": { "type": "string" },
            "units": { "type": "string", "enum": ["celsius", "fahrenheit"] }
          },
          "required": ["city"]
        }
      }
    ]
  }'

최종 응답:

{
  "content": "The current weather in Berlin is 18°C and partly cloudy, with 65% humidity."
}

도구 정의 스키마

각 도구는 다음 구조를 따라야 합니다:

{
  "name": "tool_name",
  "description": "Clear description of when and how to use this tool",
  "parameters": {
    "type": "object",
    "properties": {
      "param1": {
        "type": "string",
        "description": "What this parameter does"
      }
    },
    "required": ["param1"]
  },
  "strict": true
}

필수 필드:

선택적 필드:

도구 선택 모드

tool_choice 파라미터를 사용하여 마인드가 언제, 어떻게 도구를 호출할지 제어합니다:

예시:

// Let the mind decide
{
  "messages": [...],
  "tools": [...],
  "tool_choice": "auto"
}

// Force a specific tool
{
  "messages": [...],
  "tools": [...],
  "tool_choice": {
    "name": "search_database"
  }
}

// Require at least one tool call
{
  "messages": [...],
  "tools": [...],
  "tool_choice": "required"
}

병렬 도구 호출

기본적으로 마인드는 효율성을 위해 한 턴에 여러 도구를 호출할 수 있습니다:

{
  "content": "",
  "tool_calls": [
    {
      "id": "call_1",
      "name": "get_customer",
      "arguments": { "id": "CUST-001" }
    },
    {
      "id": "call_2",
      "name": "get_customer",
      "arguments": { "id": "CUST-002" }
    }
  ]
}

병렬 호출을 비활성화하고 순차적 실행을 강제하려면:

{
  "messages": [...],
  "tools": [...],
  "parallel_tool_calls": false
}

도구 메시지 형식

도구 결과를 다시 보낼 때 tool 역할을 사용하세요:

{
  "role": "tool",
  "tool_call_id": "call_abc123",
  "content": "{\"result\": \"success\", \"data\": {...}}"
}

내부 도구 vs 사용자 도구

Minds에는 자동으로 실행되는 내장 서버 측 도구가 있습니다:

주요 차이점:

• 내부 도구: 서버 측에서 실행되며, 결과는 content 및 metadata에 포함됩니다. tool_calls에는 절대 반환되지 않습니다.
• 사용자 도구: 사용자가 실행할 수 있도록 tool_calls로 반환됩니다. 결과는 tool 메시지로 다시 보내야 합니다.

내부 도구를 재정의하거나 비활성화할 수 없습니다. 사용자 도구는 추가적입니다 - 마인드의 기능을 확장합니다.

전체 다중 도구 예시

여러 사용자 지정 도구를 갖춘 법률 보조 마인드:

curl -X POST "https://getminds.ai/api/v1/sparks/spark-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Create a new case for Schmidt vs. Mueller and search for similar precedents"
      }
    ],
    "tools": [
      {
        "name": "create_case",
        "description": "Create a new legal case in the system",
        "parameters": {
          "type": "object",
          "properties": {
            "title": {
              "type": "string",
              "description": "Case title (parties involved)"
            },
            "practice_area": {
              "type": "string",
              "enum": ["corporate", "litigation", "employment", "ip"],
              "description": "Legal practice area"
            },
            "client_id": {
              "type": "string",
              "description": "Client identifier"
            }
          },
          "required": ["title", "practice_area"]
        }
      },
      {
        "name": "search_precedents",
        "description": "Search legal database for similar cases",
        "parameters": {
          "type": "object",
          "properties": {
            "keywords": {
              "type": "array",
              "items": { "type": "string" },
              "description": "Search keywords"
            },
            "practice_area": {
              "type": "string",
              "description": "Filter by practice area"
            },
            "max_results": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "description": "Maximum number of results"
            }
          },
          "required": ["keywords"]
        }
      }
    ],
    "parallel_tool_calls": true
  }'

병렬 도구 호출이 포함된 응답:

{
  "content": "",
  "tool_calls": [
    {
      "id": "call_1",
      "name": "create_case",
      "arguments": {
        "title": "Schmidt vs. Mueller",
        "practice_area": "litigation"
      }
    },
    {
      "id": "call_2",
      "name": "search_precedents",
      "arguments": {
        "keywords": ["Schmidt", "Mueller"],
        "practice_area": "litigation",
        "max_results": 10
      }
    }
  ]
}

모범 사례

1. 명확한 설명 작성: description 필드는 매우 중요합니다. 각 도구를 언제, 왜 사용해야 하는지 구체적으로 설명하세요.

   ❌ "description": "데이터베이스 검색"
   ✅ "description": "키워드 및 업무 분야를 기반으로 유사 사례에 대한 법률 판례 데이터베이스 검색"
   

2. 파라미터 설명 사용: 마인드가 각 파라미터가 무엇을 하는지 이해하도록 돕습니다.

   "case_id": {
     "type": "string",
     "description": "CASE-YYYY-NNNN 형식의 고유 사건 식별자"
   }
   

3. 제한된 값에 대해 enum 활용:

   "status": {
     "type": "string",
     "enum": ["pending", "active", "closed", "archived"]
   }
   

4. 유효성 검사 제약 조건 설정:

   "priority": {
     "type": "integer",
     "minimum": 1,
     "maximum": 5,
     "description": "우선순위 수준 (1=가장 낮음, 5=가장 높음)"
   }
   

5. 엄격 모드 활성화: 마인드가 유효한 인수를 생성하도록 하려면 strict: true(기본값)를 유지하세요.
6. 구조화된 도구 결과 반환: 도구 결과에 JSON을 사용하여 쉽게 파싱할 수 있도록 합니다:

   {
     "role": "tool",
     "tool_call_id": "call_123",
     "content": "{\"success\": true, \"case_id\": \"CASE-2026-001\", \"created_at\": \"2026-03-30T23:00:00Z\"}"
   }
   

7. 오류를 정상적으로 처리: 도구 결과에 오류 세부 정보를 반환합니다:

   {
     "role": "tool",
     "tool_call_id": "call_123",
     "content": "{\"success\": false, \"error\": \"사건이 이미 존재합니다\", \"error_code\": \"DUPLICATE_CASE\"}"
   }
   

제한 사항

• 요청당 최대 128개 도구
• 도구 이름은 고유해야 하며 내부 도구 이름과 충돌할 수 없습니다
• 도구 실행은 클라이언트 측에서 발생합니다 - 도구를 실행하고 보안을 유지하는 것은 사용자의 책임입니다
• 마인드가 응답하려면 도구 결과를 대화 기록에 다시 보내야 합니다

JSON 스키마 지원

parameters 필드는 표준 JSON 스키마 기능을 지원합니다:

타입:

• string, number, integer, boolean, array, object, null

유효성 검사:

• enum , 특정 값으로 제한
• minimum, maximum , 숫자 범위
• minLength, maxLength , 문자열 길이
• minItems, maxItems , 배열 크기
• pattern , 정규식 유효성 검사
• format , 문자열 형식 (예: "date-time", "email", "uri")

구조:

• properties , 객체 속성
• required , 필수 필드
• items , 배열 항목 스키마
• additionalProperties , 추가 속성 허용/비허용

고급 유효성 검사 예시:

{
  "name": "schedule_meeting",
  "description": "Schedule a meeting with a client",
  "parameters": {
    "type": "object",
    "properties": {
      "title": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      },
      "date": {
        "type": "string",
        "format": "date-time",
        "description": "Meeting date and time in ISO 8601 format"
      },
      "attendees": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "email"
        },
        "minItems": 1,
        "maxItems": 20
      },
      "duration_minutes": {
        "type": "integer",
        "minimum": 15,
        "maximum": 480,
        "description": "Meeting duration (15-480 minutes)"
      }
    },
    "required": ["title", "date", "attendees"]
  }
}

작동 방식

1. 컨텍스트 로딩

메시지를 보내면 마인드는 다음을 수행합니다:

• 시스템 프롬프트와 구성을 로드합니다
• 지식 베이스에서 관련 정보를 자동으로 검색합니다
• 대화 기록을 고려합니다

2. 처리

마인드는 다음을 수행합니다:

• 컨텍스트 내에서 메시지를 분석합니다
• 검색된 지식에 기반하여 응답의 근거를 제시하고 인용을 포함합니다
• 필요한 경우 추가 도구(웹 검색, 이미지 생성 등)에 접근합니다
• 자신의 페르소나에 맞는 응답을 구성합니다

3. 응답 생성

마인드는 다음을 수행합니다:

• 전문성을 반영하는 응답을 생성합니다
• 지식 베이스나 웹 출처를 사용할 때 인용을 포함합니다
• 선택적 메타데이터(인용, 이미지 등)와 함께 메시지를 반환합니다

메타데이터

응답에는 추가 메타데이터가 포함될 수 있습니다:

이미지

마인드가 이미지를 생성하거나 표시할 때:

{
  "content": "Here are some logo concepts...",
  "metadata": {
    "images": [
      {
        "id": "img_123",
        "url": "https://...",
        "filename": "Logo Concept 1",
        "description": "Modern minimalist logo with blue gradient",
        "source": "generated"
      }
    ]
  }
}

지식 인용

마인드가 지식 베이스나 웹 검색에서 정보를 검색할 때:

{
  "content": "Based on recent research, solar panel efficiency has improved significantly...",
  "metadata": {
    "ragCitations": [
      {
        "id": "9bf44ab0-9d83-42ec-b941-c0ab7610e949",
        "displaySource": "Spark knowledge",
        "similarity": 0.85
      },
      {
        "id": "external-web-123",
        "displaySource": "https://example.com/solar-research",
        "similarity": 0.92
      }
    ]
  }
}

인용 필드:

• id - 출처의 고유 식별자
• displaySource - 사람이 읽을 수 있는 출처 이름 또는 URL
• similarity - 관련성 점수 (0-1), 출처가 쿼리와 얼마나 잘 일치하는지를 나타냄

마인드는 응답하기 전에 자동으로 지식 베이스를 검색하고, 특정 출처에 근거하여 답변할 때 인용을 포함합니다.

접근 제어

다음과 같은 마인드와 채팅할 수 있습니다:

• 소유한 마인드 - 직접 생성한 마인드
• 접근 권한이 있는 마인드 - 팀원이 공유한 마인드
• 멤버로 속한 마인드 - 소속된 팀 워크스페이스의 마인드
• 공개 마인드 - 공개적으로 접근 가능한 마인드

권한이 없는 마인드에 접근하려고 하면 다음이 반환됩니다:

{
  "statusCode": 403,
  "statusMessage": "Access denied"
}

응답 형식

텍스트 응답

대부분의 응답은 일반 텍스트입니다:

{
  "content": "Based on current trends, I recommend focusing on..."
}

구조화된 응답

일부 마인드는 구조화된 콘텐츠를 반환할 수 있습니다:

{
  "content": "Here's my analysis:\n\n1. Trend: AI Personalization\n   - Impact: High\n   - Timeline: 6-12 months\n\n2. Trend: Short-form Video\n   - Impact: Very High\n   - Timeline: Immediate"
}

메타데이터만 있는 빈 응답

때로는 메타데이터만 반환됩니다 (예: 이미지 생성 시):

{
  "content": "",
  "metadata": {
    "images": [...]
  }
}

모범 사례

구체적으로 질문하기

❌ "Tell me about marketing"
✅ "What are the most cost-effective digital marketing channels for a B2B SaaS startup with a $5K monthly budget?"

컨텍스트 제공하기

✅ "We're launching a sustainable fashion brand targeting Gen Z. What social media strategy would you recommend?"

후속 질문 사용하기

대화 기억 기능을 활용하세요:

User: "What are the top trends?"
Assistant: "The top trends are..."
User: "Which of these would work best for a small budget?"
Assistant: "For a small budget, I'd focus on..."

지식 참조하기

지식을 업로드했다면 참조하세요:

✅ "Based on our brand guidelines, what tone should we use for this campaign?"

오류 응답

400 Bad Request

spark ID가 누락되었거나 유효하지 않음:

{
  "statusCode": 400,
  "statusMessage": "Spark ID is required"
}

지원되지 않는 제공자:

{
  "statusCode": 400,
  "statusMessage": "Unsupported provider: 'invalid'. Supported providers: openai, anthropic, google."
}

제공자 없이 모호한 모델 이름 사용:

{
  "statusCode": 400,
  "statusMessage": "Cannot auto-detect provider for model 'my-model'. Please specify a 'provider' parameter (openai, anthropic, or google)."
}

401 Unauthorized

유효하지 않은 API 키.

403 Forbidden

spark에 대한 접근 거부:

{
  "statusCode": 403,
  "statusMessage": "Access denied"
}

404 Not Found

spark가 존재하지 않음:

{
  "statusCode": 404,
  "statusMessage": "Spark not found"
}

사용 참고 사항

• v1 API는 인증된 계정별로 설정 가능한 제한(기본값 분당 300개 요청)을 적용합니다
• RateLimit-Limit와 RateLimit-Remaining을 읽고 429 이후에는 Retry-After를 따르세요
• 생성 요청은 리소스를 많이 사용하므로 병렬 completion 수를 제한하세요

다음 단계

• 지연 시간 및 성능 이해하기
• 오류 및 속도 제한에 대해 알아보기
• 첫 마인드 생성하기
• 응답 향상을 위해 지식 업로드하기
• API 개요 읽기