> ## Documentation Index > Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt > Use this file to discover all available pages before exploring further. # AI Chat v2 API Integrationsbeskrivning > AI Dialogue API guide - Ace Data Cloud AI Chat v2 API (`/aichat2/conversations`) är nästa generations dialoggränssnitt och en omfattande uppgradering av [AI Chat API](https://platform.acedata.cloud/documents/aichat-conversations). Det bygger på v1:s enkelhet och hantering av flerdialoger och har utvidgats med: * **Multimodal användarinmatning**: Genom det strukturerade `message`-fältet kan text + bild + filblock skickas direkt utan att först behöva bifogas indirekt med `references`. * **Agent-baserade verktygsanrop**: Inbyggda verktyg för nätverksökning, webbsökning, filavläsning med mera, och kan kopplas till användarauktoriserade MCP-servrar (Google Drive, Notion, Slack, GitHub etc.), modellen kan i en enda begäran självständigt anropa verktyg för att slutföra komplexa uppgifter. * **Strukturerade strömmande händelser**: Genom `accept: text/event-stream` eller `application/x-ndjson` kan man få token-för-token `text_delta`, `tool_use`, `tool_result`, `thinking`, `citation`, `card`, `artifact` och andra händelser, vilket underlättar rendering i frontend baserat på motsvarande typ. * **Avbrytbar / Återställbar**: Modellen kommer att skicka en `ask_user_question`-händelse och pausa när den behöver mer information från användaren, nästa anrop kan fortsätta genom att fylla i svaret med `tool_results`. * **Nya CRUD-åtgärder**: Genom `action`-fältet kan man utföra `retrieve` / `retrieve_batch` / `update` / `delete` på samma endpoint, utan behov av extra sessionshanterings-API. * **Kontinuerligt uppdaterad modellista**: Standardanslutning till GPT-5.4, Claude Opus 4.8, Claude Sonnet 4.6, Gemini 3.1 Pro, GLM 5.1, DeepSeek V4, Kimi K3 och andra moderna modeller. Samtidigt är det på begäransnivå **fullt bakåtkompatibelt med v1**: Genom att bara skicka `model` + `question` (+ valfritt `stateful` / `id` / `references` / `preset`) får man ett `{answer, id}` JSON-svar som är ekvivalent med v1, så att migrera från `/aichat/conversations` kräver ingen omskrivning av klienten, man behöver bara byta sökväg till `/aichat2/conversations`. > Om du för närvarande använder `/aichat/conversations`, kommer den gamla gränssnittet fortfarande att vara tillgängligt, så att du kan migrera i din egen takt. ## Ansökningsprocess För att använda AI Chat v2 API, börja med att gå till [Ace Data Cloud-konsolen](https://platform.acedata.cloud/console/applications) för att få din API-token, som du kan spara för framtida bruk. ![](https://cdn.acedata.cloud/5hmkdg.jpg) Om du inte har loggat in eller registrerat dig, kommer du automatiskt att omdirigeras till inloggningssidan där du kan registrera dig och logga in, och efter att ha slutfört detta kommer du automatiskt att återvända till den aktuella sidan. **En API-token räcker för att anropa alla plattformens tjänster, du behöver inte ansöka separat för varje tjänst.** Första ansökan ger en gratis kvot, så att du kan prova gratis; när kvoten är slut kan du ladda på allmän balans i [konsolen](https://platform.acedata.cloud/console/coin). > 📘 Fullständig dokumentation: [AI Chat v2 API →](https://platform.acedata.cloud/documents/aichat2-conversations) ## Grundläggande användning Den enklaste användningen är helt identisk med v1: skicka `model` + `question` för att få `{answer, id}`. CURL-exempel: ```shell theme={null} 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": "Beskriv AceDataCloud med en mening." }' ``` Returresultat: ```json theme={null} { "answer": "AceDataCloud är en enhetlig API-plattform som samlar populära AI-modeller och multimodala tjänster, där utvecklare kan anropa tjänster som GPT, Claude, Gemini, Midjourney, Suno, Veo med en nyckel.", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44" } ``` Python-exempel: ```python theme={null} 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": "Beskriv AceDataCloud med en mening.", } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` Tillgängliga `model`-värden kan ses direkt i rullgardinsmenyn i Try-panelen till höger, vanliga kategorier inkluderar: * 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` etc. * 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` etc. * Google: `gemini-3.1-pro`, `gemini-3.1-pro-preview`, `gemini-3.1-flash-image-preview`, `gemini-3-pro-preview`, `gemini-2.5-flash-lite` etc. * xAI: `grok-4` etc. * DeepSeek: `deepseek-v4-flash`, `deepseek-v3.2-exp`, `deepseek-r1-0528` etc. * Moonshot: `kimi-k3`, `kimi-k2.6`, `kimi-k2.5` etc. * Zhipu: `glm-5.1`, `glm-5`, `glm-5-turbo`, `glm-4.7`, `glm-4.5v` etc. Specifika avgiftsregler kan ses på tjänstesidan under Pricing-kortet. ## Fleromgångsdialog Som med v1, skicka `stateful: true` för att aktivera sessionslagring, API:t kommer att returnera ett `id`; för efterföljande begärningar, ta med `id` för att fortsätta dialogen utan att själv behöva hantera meddelandehistorik. Första begäran: ```shell theme={null} 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": "Kom ihåg ett nummer: 42." }' ``` Retur: ```json theme={null} { "answer": "Okej, jag har kommit ihåg 42. Vad vill du att jag ska göra med det?", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44" } ``` Andra begäran, med samma `id`: ```shell theme={null} 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": "Vad var numret jag bad dig att komma ihåg nyss?" }' ``` ```json theme={null} { "answer": "Numret du bad mig att komma ihåg är 42.", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44" } ``` > `stateful` är som standard `true`, att utelämna det är likvärdigt med att uttryckligen ange `true`. Om du inte vill att servern ska spara denna konversation kan du uttryckligen ställa in `stateful: false`. ## Strömmande svar v2 stöder två typer av strömmande format, välj enligt `accept`-huvudet: | Scenario | `accept` | Dataformat | | ------------------------------------- | ----------------------------- | -------------------------------------------------- | | Web frontend / EventSource | `text/event-stream` | `data: {json}\n\n`, sista raden `data: [DONE]\n\n` | | Server / CLI / Node strömmande analys | `application/x-ndjson` | En JSON-objekt per rad | | Ingen strömning | `application/json` (standard) | Engångsretur `{answer, id}` | ### NDJSON Exempel ```python theme={null} 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": "Beskriv Hangzhou med tre meningar.", } 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": # Kompatibel med v1: inkrementella segment tillhandahålls också via delta_answer-fältet answer += event["content"] print(event["delta_answer"], end="", flush=True) elif event.get("type") == "done": print() print("usage =", event.get("usage")) ``` NDJSON varje rad är strukturerade händelser, den vanligaste är `text_delta`: ```json theme={null} {"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 Exempel Webbläsarens `EventSource` stöder inte anpassade begärningskroppar, det rekommenderas att använda `fetch` + manuellt dela upp med `\n\n`: ```javascript theme={null} 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: "Beskriv Hangzhou med tre meningar.", }), }); 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); } } ``` ### Strömmande händelsetyper | `type` | Betydelse | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `text_delta` | Inkrementella textstycken av assistentens svar. `content` är det nya innehållet; för att vara kompatibel med v1, bär samma händelse också `delta_answer` (lika med `content`) och `id`. | | `thinking` | Modellens tänkande process (finns endast när den valda modellen exponerar reasoning). | | `tool_use` | Modellen bestämmer sig för att anropa ett verktyg, händelsen bär `tool_id`, `tool_name`, `input`. | | `tool_result` | Resultatet av verktyget, kopplat till föregående `tool_use` via `tool_id`, `is_error` indikerar om det misslyckades. | | `card` | Strukturerade kort som produceras av verktyget (som bilder, länkförhandsvisningar), lämpliga för direkt rendering. | | `citation` | Används för att komplettera källan URL för motsvarande textstycke. | | `ask_user_question` | Modellen skickar ut när den behöver mer information från användaren, konversationen går in i `awaiting_user_input`-status, se nedan [återuppta pausad konversation](#återuppta-pausad-konversation). | | `artifact` | Självständiga produkter som genereras av modellen (som kodblock, dokument), kan sparas eller laddas ner. | | `system_message` | Systemmeddelanden (inte användar- och assistentinnehåll), används endast för UI-meddelanden. | | `compact` | Händelser där intern kontext har komprimerats, ingen speciell hantering krävs. | | `error` | Fel inträffade under denna runda, `message` beskriver felinnehållet. | | `done` | Strömmande svar avslutat, bär `usage` (inklusive `prompt_tokens` / `completion_tokens` / `total_tokens`) och `terminal_reason`. | För klienter som bara är intresserade av det slutgiltiga svaret, att sammanfoga alla `text_delta`-innehåll ger samma resultat som `answer` i `application/json`-läget. ## Multimodal inmatning Om användarens inmatning innehåller bilder eller filer, skicka `message` (array) istället för `question`. Varje element i arrayen är en innehållsblock: ```json theme={null} { "model": "gpt-5.4", "stateful": true, "message": [ { "type": "text", "text": "Hur många katter finns det i denna bild?" }, { "type": "image_url", "image_url": { "url": "https://cdn.acedata.cloud/cats.jpg" } } ] } ``` Stödda blocktyper: * `text` — Vanlig text, obligatoriskt `text`-fält. * `image_url` — Bild, obligatoriskt `image_url.url`. * `file_url` — Fil (PDF, CSV, TXT etc.), obligatoriskt `file_url.url`. ### Förhållandet till v1 `references` För att vara kompatibel med gamla klienter, känner v2 fortfarande igen `references: ["https://...", ...]`-fältet: * URL-suffixen är `jpg / jpeg / png / gif / bmp / webp / svg / heic / heif`, automatiskt omvandlad till `image_url` block; * Andra filändelser omvandlas till `file_url` block; * Om `question` också tillhandahålls, placera den som ett `text` block före. Så om du bara vill migrera från v1 utan att ändra begäran, byt bara sökväg till `/aichat2/conversations`, den ursprungliga användningen av `references` fungerar som vanligt. För mer finjusterad kontroll (till exempel att placera flera bilder mellan text eller där ordningen är viktig) använd direkt `message` array. ## Verktygsanrop och MCP v2:s kärnförbättring är att modellen kan självständigt anropa verktyg för att slutföra flerstegsuppgifter, **detta är som standard aktiverat**, utan att klienten behöver göra några extra konfigurationer i begäran. Vanliga scenarier: * Användaren frågar "Hjälp mig att söka efter nya utställningar i Shanghai" → modellen anropar inbyggd webbsökning → organiserar resultaten till ett svar. * Användaren frågar "Läs den här PDF:en och skriv en sammanfattning" → modellen anropar file\_read → skriver sammanfattning. * Användaren har redan auktoriserat Google Drive / GitHub / Notion etc. i [Connections](https://platform.acedata.cloud/connections) → modellen kan anropa motsvarande MCP-verktyg för att läsa och skriva data. I NDJSON / SSE-strömmen presenteras verktygsanrop genom `tool_use` och `tool_result` två typer av händelser, till exempel: ```json theme={null} {"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-..."} ... ``` Om du inte vill visa detaljer om verktygsanropet i fronten, ignorera `tool_use` / `tool_result` / `card` / `citation` dessa typer av händelser, modellen kommer fortfarande att leverera slutgiltigt utdata genom `text_delta`. `max_turns` kan begränsa hur många gånger modellen kan anropa verktyg i denna begäran, standardgränsen bestäms av plattformen. Att sätta den lågt (till exempel `max_turns: 1`) kan tvinga till ett enda svar, utan att tillåta några verktygsanrop. ## Asynkron exekvering och obevakad auktorisering Om ditt anrop kommer från en varnings Webhook, CI/CD, övervakningssystem eller andra bakgrundsuppgifter, kan du ställa in `async: true` för att låta gränssnittet omedelbart returnera uppgifts-ID, medan bakgrunden fortsätter att köra: ```json theme={null} { "model": "gpt-5.5", "async": true, "question": "我的服务报警了，用个人微信通知微信群「AceDataCloud团队」……" } ``` Exempel på svar: ```json theme={null} { "task_id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44", "conversation_id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44", "status": "queued" } ``` Därefter kan du använda `action: retrieve` + `id` för att fråga efter sessionens resultat; du kan också tillhandahålla `callback_url`, så kommer plattformen att POST:a `{ status, answer, usage, error }` till din återkopplingsadress när uppgiften är klar. `callback_url` måste använda `http` / `https`, och får inte direkt ange `localhost` eller privata IP-litterära adresser. Bakgrundsuppgifter har vanligtvis ingen som kan klicka för att bekräfta. Om du vill att vissa färdigheter eller MCP-servrar ska utföra sändning, publicering, skrivning etc. i obevakad läge, vänligen ange en förhandsauktoriseringslista i begäran: ```json theme={null} { "model": "gpt-5.5", "async": true, "allowed_skills": ["acedatacloud/personal-wechat"], "allowed_mcp_servers": [], "question": "我的服务报警了，用个人微信通知微信群「AceDataCloud团队」……" } ``` Värdena i `allowed_skills` är sluggar för anslutna färdigheter; värdena i `allowed_mcp_servers` är sluggar för anslutna MCP-servrar. Färdigheter / MCP-servrar som inte listas i förhandsauktoriseringen kan fortfarande bara förhandsgranskas, köras i torrkörning eller vägras att utföra skrivoperationer i obevakad läge. Om du behöver mer detaljerad kontroll kan du också använda det ekvivalenta `unattended_policy` objektet: ```json theme={null} { "unattended_policy": { "allowed_skills": ["acedatacloud/personal-wechat"], "allowed_mcp_servers": [], "expires_at": 1790000000 } } ``` Förhandsauktorisering är just dessa två listor: en tom lista innebär att inga förmågor auktoriseras, utan behov av extra växlingsfält. Observera: Förhandsauktorisering representerar endast "denna begäran tillåter dessa förmågor att hoppa över manuell bekräftelse i obevakad läge". Specifika färdigheter måste fortfarande stödja `--unattended-confirm` eller motsvarande säkerhetsmekanism; annars kommer det att fortsätta i torrkörning och inte direkt utföra skrivoperationer. ## Återställning av pausad konversation Vissa verktyg kan få modellen att "ställa en fråga till användaren", modellen kommer då att skicka en `ask_user_question` händelse, konversationen fryses i `awaiting_user_input` status: ```json theme={null} { "type": "ask_user_question", "tool_id": "toolu_01XYZW", "tool_name": "ask_user_question", "question": "你希望生成的报告是中文还是英文？", "options": ["中文", "英文"], "id": "f2f4b3e8-..." } ``` I fronten rendera denna händelse som ett kort så att användaren kan välja svar, och skicka en ny begäran med samma `id`, fyll i svaret genom `tool_results`: ```shell theme={null} 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": "中文" } ] }' ``` I begäran måste `tool_use_id` **vara** helt identisk med den pausade `tool_id`; annars returneras 400. När begäran innehåller `tool_results`, kommer `question` / `message` / `references` att ignoreras. Om användaren beslutar att ge upp denna fråga, skicka bara en ny `question` / `message` så kommer plattformen automatiskt att markera det pausade verktygsanropet som "användaren hoppade över". ## Sessionshantering (CRUD) v2 erbjuder lättvikts sessionshantering genom `action` fältet på samma endpoint, utan behov av att öppna en annan API. ### `action: retrieve` —— Hämta en session ```shell theme={null} 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" }' ``` Returnera det fullständiga samtalsdokumentet (inklusive `messages` historia, `model`, `title`, `tools_used` etc.). ### `action: retrieve_batch` —— Lista samtalsöversikter ```json theme={null} { "action": "retrieve_batch", "model_group": "chatgpt", "limit": 20, "offset": 0 } ``` Returnera `{ items: [...], total }`. **Översikten innehåller inte `messages`**, lämplig för sidofältlista; om användaren klickar på en viss konversation, använd sedan `action: retrieve` för att hämta dess fullständiga meddelanden. Valfria filtreringsparametrar: `user_id`, `application_id`, `model_group`, `model`. ### `action: update` —— Ändra titel eller skriva om historik ```json theme={null} { "action": "update", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44", "title": "Hangzhou reseplan" } ``` `messages` kan också skickas, men servern kommer att göra strikt schema validering (måste vara i den hopfällda `ToolUseContent` formen), om det inte uppfyller kraven kommer det att returnera 400. Generellt rekommenderas det att endast användas för att ändra `title`. ### `action: delete` —— Ta bort en konversation ```json theme={null} { "action": "delete", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44" } ``` Returnera `{ id, success: true }`. Efter borttagning kan det inte återställas, vänligen bekräfta innan du anropar. ## Smidig migrering från v1 Om du redan använder [`/aichat/conversations`](https://platform.acedata.cloud/documents/aichat-conversations), kräver migreringen till v2 nästan inga kodändringar: 1. Ändra URL från `https://api.acedata.cloud/aichat/conversations` till `https://api.acedata.cloud/aichat2/conversations`. 2. Om du tidigare skickade v1-modellnamn (som `gpt-3.5`, `gpt-4-browsing` etc.), rekommenderas det att uppgradera till moderna modeller (som `gpt-5.4`, `claude-opus-4-8`, `gemini-3.1-pro` etc.) vid övergång till v2. 3. NDJSON-strömmens fält förblir bakåtkompatibla: varje `text_delta`-händelse innehåller fortfarande `delta_answer` och `id`, så klienter som tidigare analyserade `delta_answer` rad för rad behöver inte ändras. Efter migreringen kan du aktivera v2:s nya funktioner (multimodal `message`, SSE, verktygsanrop, `action` CRUD) i din egen takt. ## Felhantering Felresponsen är enhetlig: ```json theme={null} { "error": { "code": "chat_error", "message": "upstream LLM returned an error" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` Vanliga fel: * `400 bad_request`: Saknar obligatoriska fält, `tool_use_id` matchar inte, `messages` schema är ogiltigt etc. * `401 invalid_token`: `authorization`-huvudet är felaktigt. * `404 not_found`: `action: retrieve / update / delete` när `id` motsvarande konversation inte finns. * `429 too_many_requests`: Utlöst hastighetsbegränsning. * `500 chat_error`: Upstream LLM rapporterade ett fel eller denna omgång `completion_tokens=0` (behandlas som icke-använd, kommer inte att debiteras). I strömmande svar skickas fel som `{"type":"error","message":"..."}` händelse, och strömmen avslutas omedelbart efter. ## Slutsats AI Chat v2 API är bakåtkompatibelt med v1 samtidigt som det uppgraderar konversationer från "enkla/multipla frågor och svar" till "Agent-baserade observerbara konversationer": multimodala indata, verktygsanrop, pausbar/återupptagbar, strömmande strukturerade händelser, inbyggd CRUD. Det rekommenderas att nya integrationer direkt använder v2; befintliga v1-integrationer kan migreras i faser. Om du har några frågor, tveka inte att kontakta vårt tekniska supportteam.