AI Chat v2 API 연동 안내

AI Chat v2 API(/aichat2/conversations)는 차세대 대화 인터페이스로, AI Chat API의 전면 업그레이드 버전입니다. v1의 간결하고 관리형인 다중 턴 대화를 기반으로 다음을 확장했습니다:

멀티모달 사용자 입력: 구조화된 message 필드를 통해 텍스트 + 이미지 + 파일 블록을 직접 전송하며, 먼저 references를 사용해 간접적으로 첨부할 필요가 없습니다.
Agent화된 도구 호출: 인터넷 검색, 웹페이지 크롤링, 파일 읽기 등의 도구 세트가 내장되어 있으며, 사용자가 승인한 MCP 서버(Google Drive, Notion, Slack, GitHub 등)를 연결할 수 있습니다. 모델은 한 번의 요청에서 여러 차례 자율적으로 도구를 호출하여 복잡한 작업을 완료할 수 있습니다.
구조화된 스트리밍 이벤트: accept: text/event-stream 또는 application/x-ndjson를 통해 토큰별 text_delta, tool_use, tool_result, thinking, citation, card, artifact 등의 이벤트를 받을 수 있어, 프런트엔드에서 해당 유형에 따라 각각 렌더링하기 편리합니다.
중단 / 재개 가능: 모델은 사용자에게 추가 정보가 필요할 때 ask_user_question 이벤트를 전송하고 일시 중지합니다. 다음 호출에서 tool_results를 통해 답변을 다시 채우면 계속 진행할 수 있습니다.
새로운 CRUD 작업: 동일한 endpoint에서 action 필드를 통해 retrieve / retrieve_batch / update / delete를 수행하며, 별도의 대화 관리 API가 필요하지 않습니다.
지속적으로 업데이트되는 모델 목록: 기본적으로 GPT-5.4, Claude Opus 4.8, Claude Sonnet 4.6, Gemini 3.1 Pro, GLM 5.1, DeepSeek V4, Kimi K3 등의 최신 모델을 제공합니다.

동시에 요청 본문 수준에서 v1과 완전히 하위 호환됩니다: model + question(+ 선택 사항인 stateful / id / references / preset)만 전달하면 v1과 동등한 {answer, id} JSON 응답을 받을 수 있습니다. 따라서 /aichat/conversations에서 마이그레이션할 때 클라이언트를 다시 작성할 필요 없이 경로만 /aichat2/conversations로 변경하면 됩니다.

현재 /aichat/conversations를 사용하고 있다면, 기존 인터페이스는 계속 서비스되며 원하는 속도에 맞춰 마이그레이션할 수 있습니다.

신청 절차

AI Chat v2 API를 사용하려면 먼저 Ace Data Cloud 콘솔에서 API Token을 발급받아 예비로 보관하세요.

아직 로그인 또는 회원가입하지 않았다면, 로그인 페이지로 자동 이동하여 회원가입과 로그인을 안내하며, 완료 후 현재 페이지로 자동 반환됩니다. 하나의 API Token으로 플랫폼의 모든 서비스를 호출할 수 있으며, 서비스마다 별도로 신청할 필요가 없습니다. 최초 신청 시 무료 크레딧이 제공되어 무료로 체험할 수 있으며, 크레딧이 부족할 경우 콘솔에서 공용 잔액을 충전할 수 있습니다.

📘 전체 문서: AI Chat v2 API →

기본 사용

가장 간단한 사용법은 v1과 완전히 동일합니다: model + question을 전달하고 {answer, id}를 받습니다. CURL 예시:

curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "model": "gpt-5.4",
    "question": "用一句话介绍下 AceDataCloud。"
  }'

반환 결과:

{
  "answer": "AceDataCloud 是一个聚合主流 AI 模型与多模态服务的统一 API 平台，开发者通过一个密钥即可调用 GPT、Claude、Gemini、Midjourney、Suno、Veo 等多家服务。",
  "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44"
}

Python 예시:

import requests

url = "https://api.acedata.cloud/aichat2/conversations"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json",
}

payload = {
    "model": "gpt-5.4",
    "question": "用一句话介绍下 AceDataCloud。",
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

사용 가능한 model 값은 오른쪽 Try 패널의 드롭다운에서 직접 확인할 수 있으며, 일반적인 카테고리는 다음과 같습니다:

OpenAI: gpt-5.4-mini, gpt-5.4-nano, gpt-5.2-pro, gpt-5.1-all, gpt-5-all, gpt-4.1, gpt-4o, gpt-4o-image, o3, o4-mini 등
Anthropic: claude-opus-4-8, claude-opus-4-7, claude-opus-4-6, claude-opus-4-5-20251101, claude-sonnet-4-6, claude-sonnet-4-5-20250929, claude-haiku-4-5-20251001 등
Google: gemini-3.1-pro-preview, gemini-3.1-pro-preview, gemini-3.1-flash-image, gemini-3.1-pro-preview, gemini-2.5-flash-lite 등
xAI: grok-4 등
DeepSeek: deepseek-v4-pro, deepseek-v4.1-flash, deepseek-v4-flash, deepseek-v3.2-exp, deepseek-r1-0528 등
Moonshot: kimi-k3.1-pro, kimi-k3, kimi-k2.6, kimi-k2.5 등
Zhipu: glm-5.3, glm-5.2, glm-5.1, glm-5, glm-5-turbo, glm-4.7, glm-4.5v 등

구체적인 요금 규칙은 서비스 페이지의 Pricing 카드에서 확인하세요.

다중 턴 대화

v1과 마찬가지로 stateful: true를 전달하여 대화 저장을 활성화하면 API가 id를 반환합니다. 이후 요청에서 id를 다시 전달하면 messages 기록을 직접 유지하지 않아도 대화를 계속할 수 있습니다. 첫 번째 요청:

curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "model": "gpt-5.4",
    "stateful": true,
    "question": "记住一个数字：42。"
  }'

반환:

{
  "answer": "好的，我已经记住了 42。需要我用它做什么吗？",
  "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44"
}

두 번째 요청에서는 동일한 id를 함께 전달합니다:

curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "model": "gpt-5.4",
    "stateful": true,
    "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44",
    "question": "我刚才让你记住的数字是多少？"
  }'

{
  "answer": "你让我记住的数字是 42。",
  "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44"
}

stateful의 기본값은 true이며, 생략하는 것은 명시적으로 true를 전달하는 것과 동일합니다. 서버가 이번 대화를 저장하지 않기를 원한다면, 명시적으로 stateful: false로 설정할 수 있습니다.

스트리밍 응답

v2는 두 가지 스트리밍 형식을 지원하며, accept 헤더에 따라 선택합니다:

시나리오	`accept`	데이터 형태
Web 프런트엔드 / EventSource	`text/event-stream`	`data: {json}\n\n`, 마지막 줄은 `data: [DONE]\n\n`
서버 / CLI / Node 스트리밍 파싱	`application/x-ndjson`	한 줄당 하나의 JSON 객체
스트리밍이 필요하지 않음	`application/json`（기본값）	한 번에 `{answer, id}` 반환

NDJSON 예시

import json
import requests

url = "https://api.acedata.cloud/aichat2/conversations"

headers = {
    "accept": "application/x-ndjson",
    "authorization": "Bearer {token}",
    "content-type": "application/json",
}

payload = {
    "model": "gpt-5.4",
    "stateful": True,
    "question": "用三句话介绍杭州。",
}

with requests.post(url, json=payload, headers=headers, stream=True) as resp:
    answer = ""
    for line in resp.iter_lines():
        if not line:
            continue
        event = json.loads(line)
        if event.get("type") == "text_delta":
            # 与 v1 兼容：增量片段同时通过 delta_answer 字段提供
            answer += event["content"]
            print(event["delta_answer"], end="", flush=True)
        elif event.get("type") == "done":
            print()
            print("usage =", event.get("usage"))

NDJSON의 각 줄은 모두 구조화된 이벤트이며, 가장 일반적인 것은 text_delta입니다:

{"type":"text_delta","content":"杭","delta_answer":"杭","id":"f2f4b3e8-..."}
{"type":"text_delta","content":"州","delta_answer":"州","id":"f2f4b3e8-..."}
{"type":"text_delta","content":"是","delta_answer":"是","id":"f2f4b3e8-..."}
...
{"type":"done","conversation_id":"f2f4b3e8-...","usage":{"prompt_tokens":21,"completion_tokens":58,"total_tokens":79},"terminal_reason":"natural_stop"}

SSE 예시

브라우저 측에서 EventSource를 사용하면 사용자 지정 요청 본문을 지원하지 않으므로, fetch + 수동 \n\n 분할 파싱 사용을 권장합니다:

const resp = await fetch("https://api.acedata.cloud/aichat2/conversations", {
  method: "POST",
  headers: {
    accept: "text/event-stream",
    authorization: "Bearer {token}",
    "content-type": "application/json",
  },
  body: JSON.stringify({
    model: "gpt-5.4",
    stateful: true,
    question: "用三句话介绍杭州。",
  }),
});

const reader = resp.body.getReader();
const decoder = new TextDecoder();
let buffer = "";
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  buffer += decoder.decode(value, { stream: true });
  const blocks = buffer.split("\n\n");
  buffer = blocks.pop() ?? "";
  for (const block of blocks) {
    const dataLine = block.split("\n").find((l) => l.startsWith("data: "));
    if (!dataLine) continue;
    const payload = dataLine.slice(6);
    if (payload === "[DONE]") return;
    const event = JSON.parse(payload);
    if (event.type === "text_delta") process.stdout.write(event.content);
  }
}

스트리밍 이벤트 유형

`type`	의미
`text_delta`	어시스턴트 답변의 증분 텍스트 조각입니다. `content`는 새로 추가된 내용입니다. v1 호환을 위해 동일한 이벤트에 `delta_answer`(=`content`)와 `id`도 포함됩니다.
`thinking`	모델의 사고 과정입니다(선택한 모델이 reasoning을 노출할 때만 나타납니다).
`tool_use`	모델이 도구 호출을 결정하며, 이벤트에는 `tool_id`, `tool_name`, `input`이 포함됩니다.
`tool_result`	도구 실행 결과로, 이전 `tool_use`와 `tool_id`를 통해 쌍을 이루며 `is_error`는 실패 여부를 나타냅니다.
`card`	도구가 생성한 구조화된 카드(예: 이미지, 링크 미리보기)로, 직접 렌더링하기에 적합합니다.
`citation`	해당 텍스트 조각 인용의 출처 URL을 보충하는 데 사용됩니다.
`ask_user_question`	모델이 사용자에게 추가 정보를 요청할 때 발생하며, 대화는 `awaiting_user_input` 상태로 진입합니다. 자세한 내용은 아래 일시 중지된 대화 재개를 참조하세요.
`artifact`	모델이 생성한 독립 산출물(예: 코드 블록, 문서)로, 저장하거나 다운로드할 수 있습니다.
`system_message`	시스템 알림 정보(사용자 및 어시스턴트 내용 아님)로, UI 알림에만 사용됩니다.
`compact`	내부 컨텍스트가 압축된 이벤트로, 특별한 처리가 필요하지 않습니다.
`error`	이번 라운드에서 오류가 발생했으며, `message`가 오류 내용을 설명합니다.
`done`	스트리밍 응답이 종료되며, `usage`(`prompt_tokens` / `completion_tokens` / `total_tokens` 포함)와 `terminal_reason`을 포함합니다.

최종 답변만 관심 있는 클라이언트의 경우, 모든 text_delta의 content를 연결하면 application/json 모드의 answer와 동일합니다.

멀티모달 입력

사용자 입력에 이미지 또는 파일이 포함되어 있다면, question 대신 message(배열)를 전달합니다. 각 배열 요소는 하나의 콘텐츠 블록입니다:

{
  "model": "gpt-5.4",
  "stateful": true,
  "message": [
    { "type": "text", "text": "这张图片里有几只猫？" },
    { "type": "image_url", "image_url": { "url": "https://cdn.acedata.cloud/cats.jpg" } }
  ]
}

지원되는 블록 유형:

text — 일반 텍스트이며, text 필드가 필수입니다.
image_url — 이미지이며, image_url.url이 필수입니다.
file_url — 파일(PDF, CSV, TXT 등)이며, file_url.url이 필수입니다.

v1 `references`와의 관계

이전 클라이언트와의 호환성을 위해, v2는 여전히 references: ["https://...", ...] 필드를 인식합니다:

URL 접미사가 jpg / jpeg / png / gif / bmp / webp / svg / heic / heif이면 자동으로 image_url 블록으로 변환됩니다；
기타 확장명은 file_url 블록으로 변환됩니다；
동시에 question도 제공된 경우, 이를 앞에 배치한 text 블록으로 사용합니다.

따라서 v1에서 마이그레이션만 하고 요청 본문을 변경하고 싶지 않다면, 경로를 /aichat2/conversations로 바꾸기만 하면 되며, 기존 references 사용법은 그대로 작동합니다. 더 세밀한 제어가 필요하다면(예: 여러 이미지를 텍스트 사이에 배치하거나 순서가 매우 중요한 경우) 직접 message 배열을 사용하세요.

도구 호출 및 MCP

v2의 핵심 강화점은 모델이 도구를 자율적으로 호출하여 여러 단계의 작업을 완료할 수 있다는 것이며, 이 기능은 기본으로 활성화되어 있어 클라이언트가 요청에서 추가 설정을 할 필요가 없습니다. 일반적인 시나리오:

사용자가 「최근 상하이에서 새로 열린 전시가 무엇인지 찾아줘」라고 질문 → 모델이 내장 web search 호출 → 결과를 정리하여 답변.
사용자가 「이 PDF를 읽고 요약을 작성해줘」라고 질문 → 모델이 file_read 호출 → 요약 작성.
사용자가 Connections에서 Google Drive / GitHub / Notion 등을 이미 인증함 → 모델이 해당 MCP 도구를 호출하여 데이터를 읽고 쓸 수 있음.

NDJSON / SSE 스트림에서 도구 호출은 tool_use와 tool_result 두 종류의 이벤트로 표시됩니다. 예:

{"type":"tool_use","tool_id":"toolu_01ABCDEF","tool_name":"web_search","input":{"query":"上海 2026 春季展览"},"id":"f2f4b3e8-..."}
{"type":"tool_result","tool_id":"toolu_01ABCDEF","output":"...","is_error":false,"id":"f2f4b3e8-..."}
{"type":"text_delta","content":"目前","delta_answer":"目前","id":"f2f4b3e8-..."}
{"type":"text_delta","content":"上海","delta_answer":"上海","id":"f2f4b3e8-..."}
...

프런트엔드에서 도구 호출 세부 정보를 표시하고 싶지 않다면, tool_use / tool_result / card / citation 이 몇 종류의 이벤트를 무시하면 됩니다. 모델의 최종 출력은 여전히 text_delta를 통해 스트리밍됩니다. max_turns는 이번 요청에서 모델이 도구를 자체 호출할 수 있는 최대 횟수를 제한할 수 있으며, 범위는 1–500이고 생략 시 기본값은 500입니다. 이를 작게 설정하면(예: max_turns: 1) 단일 답변을 강제하고 어떤 도구 호출도 허용하지 않을 수 있습니다.

비동기 실행 및 무인 승인

호출이 경고 Webhook, CI/CD, 모니터링 시스템 또는 기타 백그라운드 작업에서 발생하는 경우, async: true를 설정하여 인터페이스가 즉시 작업 ID를 반환하고 백그라운드에서 계속 실행되도록 할 수 있습니다:

{
  "model": "gpt-5.5",
  "async": true,
  "question": "我的服务报警了，用个人微信通知微信群「AceDataCloud团队」……"
}

반환 예시:

{
  "task_id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44",
  "conversation_id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44",
  "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44",
  "status": "queued"
}

이후 action: retrieve + id를 사용하여 대화 결과를 조회할 수 있습니다；또한 callback_url을 제공할 수도 있으며, 작업 완료 후 플랫폼이 { status, answer, usage, error }를 콜백 주소로 POST합니다. callback_url은 반드시 http / https를 사용해야 하며, localhost 또는 사설 IP 리터럴 주소를 직접 입력할 수 없습니다. 백그라운드 작업에서는 일반적으로 아무도 확인을 클릭할 수 없습니다. 특정 Skill 또는 MCP Server가 무인 모드에서 전송, 게시, 쓰기 등의 작업을 실행하도록 하려면 요청 본문에 사전 승인 목록을 명시적으로 전달하세요:

{
  "model": "gpt-5.5",
  "async": true,
  "allowed_skills": ["acedatacloud/personal-wechat"],
  "allowed_mcp_servers": [],
  "question": "我的服务报警了，用个人微信通知微信群「AceDataCloud团队」……"
}

allowed_skills의 값은 연결된 Skill의 slug입니다；allowed_mcp_servers의 값은 연결된 MCP Server의 slug입니다. 사전 승인 목록에 포함되지 않은 Skill / MCP Server는 무인 모드에서 여전히 미리보기, dry-run 또는 쓰기 작업 실행 거부만 가능합니다. 더 세밀한 제어가 필요하다면 동등한 unattended_policy 객체를 사용할 수도 있습니다:

{
  "unattended_policy": {
    "allowed_skills": ["acedatacloud/personal-wechat"],
    "allowed_mcp_servers": [],
    "expires_at": 1790000000
  }
}

사전 승인은 바로 이 두 목록 자체입니다: 목록이 비어 있으면 어떠한 기능도 승인하지 않는 것이며, 별도의 스위치 필드는 필요하지 않습니다. 주의: 사전 승인은 단지 「이번 요청에서 이러한 기능이 무인 모드로 인적 확인을 건너뛸 수 있도록 허용한다」는 것을 의미합니다. 구체적인 Skill은 여전히 --unattended-confirm 또는 해당 보안 메커니즘을 지원해야 합니다；그렇지 않으면 계속 dry-run만 수행하며 쓰기 작업을 직접 실행하지 않습니다.

일시 중지된 대화 재개

일부 도구는 모델이 「사용자에게 되묻게」 하며, 이때 모델은 ask_user_question 이벤트를 내보내고 대화는 awaiting_user_input 상태로 동결됩니다:

{
  "type": "ask_user_question",
  "tool_id": "toolu_01XYZW",
  "tool_name": "ask_user_question",
  "question": "你希望生成的报告是中文还是英文？",
  "options": ["中文", "英文"],
  "id": "f2f4b3e8-..."
}

프런트엔드에서 이 이벤트를 카드로 렌더링하여 사용자가 답변을 선택하게 한 다음, 동일한 id로 다음 요청을 시작하고 답변을 tool_results를 통해 다시 채웁니다:

curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \
  -H 'accept: text/event-stream' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "model": "gpt-5.4",
    "stateful": true,
    "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44",
    "tool_results": [
      {
        "tool_use_id": "toolu_01XYZW",
        "output": "中文"
      }
    ]
  }'

요청 본문의 tool_use_id는 반드시 일시 중지 시의 tool_id와 완전히 일치해야 합니다；일치하지 않으면 400이 반환됩니다. 요청에 tool_results가 동시에 존재하면 question / message / references는 모두 무시됩니다. 사용자가 이 문제를 포기하기로 결정한 경우, 새로운 question / message를 직접 전달하면 됩니다. 플랫폼은 일시 중지된 도구 호출을 자동으로 「사용자가 건너뜀」으로 표시합니다.

대화 관리（CRUD）

v2는 동일한 endpoint에서 action 필드를 통해 경량 대화 관리를 제공하며, 별도의 API를 열 필요가 없습니다.

`action: retrieve` —— 하나의 대화 가져오기

curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "action": "retrieve",
    "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44"
  }'

완전한 대화 문서(messages 기록, model, title, tools_used 등을 포함)를 반환합니다.

`action: retrieve_batch` —— 대화 요약 나열

{
  "action": "retrieve_batch",
  "model_group": "chatgpt",
  "limit": 20,
  "offset": 0
}

{ items: [...], total }을 반환합니다. 요약에는 messages가 포함되지 않으므로, 사이드바 목록에 적합합니다. 사용자가 특정 대화를 열면 action: retrieve를 사용하여 해당 대화의 전체 메시지를 별도로 가져옵니다. 선택적 필터 매개변수: user_id, application_id, model_group, model.

`action: update` —— 제목 변경 또는 기록 다시 작성

{
  "action": "update",
  "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44",
  "title": "항저우 여행 계획"
}

messages도 전달할 수 있지만, 서버에서 엄격한 schema 검증을 수행합니다(접힌 ToolUseContent 형태여야 함). 조건에 맞지 않으면 400이 반환됩니다. 일반적으로는 title 변경에만 사용하는 것을 권장합니다.

`action: delete` —— 하나의 대화 삭제

{
  "action": "delete",
  "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44"
}

{ id, success: true }를 반환합니다. 삭제 후에는 복구할 수 없으므로 확인한 뒤 호출하세요.

v1에서 원활하게 마이그레이션하기

이미 /aichat/conversations를 사용 중이라면 v2로 마이그레이션할 때 거의 코드를 수정할 필요가 없습니다.

URL을 https://api.acedata.cloud/aichat/conversations에서 https://api.acedata.cloud/aichat2/conversations로 변경합니다.
이전에 v1 모델명(예: gpt-3.5, gpt-4-browsing 등)을 전달했다면, v2로 전환할 때 최신 모델(예: gpt-5.4, claude-opus-4-8, gemini-3.1-pro-preview 등)로 업그레이드하는 것을 권장합니다.
NDJSON 스트림의 필드는 하위 호환성을 유지합니다. 각 text_delta 이벤트에는 여전히 delta_answer와 id가 포함되므로, 기존에 줄 단위로 delta_answer를 파싱하던 클라이언트는 수정할 필요가 없습니다.

마이그레이션 후에는 필요에 따라 v2의 새로운 기능(멀티모달 message, SSE, 도구 호출, action CRUD)을 활성화하고, 일정에 맞춰 진행하면 됩니다.

오류 처리

오류 응답은 다음 형식으로 통일됩니다.

{
  "error": {
    "code": "chat_error",
    "message": "model service returned an error"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

일반적인 오류:

400 bad_request: 필수 필드 누락, tool_use_id 불일치, 잘못된 messages schema 등.
401 invalid_token: authorization 헤더가 올바르지 않음.
404 not_found: action: retrieve / update / delete 수행 시 id에 해당하는 대화가 존재하지 않음.
429 too_many_requests: 속도 제한이 트리거됨.
500 chat_error: 업스트림 LLM 오류 또는 이번 라운드에서 completion_tokens=0(미사용으로 처리되며 요금이 부과되지 않음).

스트리밍 응답에서는 오류가 {"type":"error","message":"..."} 이벤트로 전송되며, 그 직후 스트림이 종료됩니다.

결론

AI Chat v2 API는 v1과의 하위 호환성을 유지하면서 대화를 「단일 턴 / 다중 턴 질의응답」에서 「Agent화된 관측 가능한 대화」로 업그레이드합니다. 멀티모달 입력, 도구 호출, 일시 중지 / 재개, 스트리밍 구조화 이벤트, 내장 CRUD를 제공합니다. 신규 연동에는 v2를 바로 사용하는 것을 권장하며, 기존 v1 통합은 단계적으로 원활하게 마이그레이션할 수 있습니다. 궁금한 사항이 있으면 언제든지 기술 지원팀에 문의해 주세요.

시작하기

AI 채팅

AI 이미지

AI 비디오

AI 오디오

웹 & 데이터

CAPTCHA

신원

Coding

추가 가이드

AI Chat v2 API 연동 안내

신청 절차

기본 사용

다중 턴 대화

스트리밍 응답

NDJSON 예시

SSE 예시

스트리밍 이벤트 유형

멀티모달 입력

v1 `references`와의 관계

도구 호출 및 MCP

비동기 실행 및 무인 승인

일시 중지된 대화 재개

대화 관리（CRUD）

`action: retrieve` —— 하나의 대화 가져오기

`action: retrieve_batch` —— 대화 요약 나열

`action: update` —— 제목 변경 또는 기록 다시 작성

`action: delete` —— 하나의 대화 삭제

v1에서 원활하게 마이그레이션하기

오류 처리

결론

​신청 절차

​기본 사용

​다중 턴 대화

​스트리밍 응답

​NDJSON 예시

​SSE 예시

​스트리밍 이벤트 유형

​멀티모달 입력

​v1 references와의 관계

​도구 호출 및 MCP

​비동기 실행 및 무인 승인

​일시 중지된 대화 재개

​대화 관리（CRUD）

​action: retrieve —— 하나의 대화 가져오기

​action: retrieve_batch —— 대화 요약 나열

​action: update —— 제목 변경 또는 기록 다시 작성

​action: delete —— 하나의 대화 삭제

​v1에서 원활하게 마이그레이션하기

​오류 처리

​결론

신청 절차

기본 사용

다중 턴 대화

스트리밍 응답

NDJSON 예시

SSE 예시

스트리밍 이벤트 유형

멀티모달 입력

v1 `references`와의 관계

도구 호출 및 MCP

비동기 실행 및 무인 승인

일시 중지된 대화 재개

대화 관리（CRUD）

`action: retrieve` —— 하나의 대화 가져오기

`action: retrieve_batch` —— 대화 요약 나열

`action: update` —— 제목 변경 또는 기록 다시 작성

`action: delete` —— 하나의 대화 삭제

v1에서 원활하게 마이그레이션하기

오류 처리

결론