> ## 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 Integração > AI Dialogue API guide - Ace Data Cloud AI Chat v2 API (`/aichat2/conversations`) é a nova geração da interface de diálogo, uma versão totalmente aprimorada da [AI Chat API](https://platform.acedata.cloud/documents/aichat-conversations). Ela expande sobre a simplicidade e a hospedagem de diálogos múltiplos da v1: * **Entrada de usuário multimodal**: através do campo estruturado `message`, é possível enviar texto + imagem + bloco de arquivo diretamente, sem a necessidade de anexar indiretamente com `references`. * **Chamadas de ferramentas como Agente**: inclui um conjunto de ferramentas para busca na web, captura de páginas, leitura de arquivos, etc., e pode montar servidores MCP autorizados pelo usuário (Google Drive, Notion, Slack, GitHub, etc.), permitindo que o modelo chame ferramentas de forma autônoma em uma única solicitação para completar tarefas complexas. * **Eventos estruturados em fluxo**: através de `accept: text/event-stream` ou `application/x-ndjson`, é possível obter eventos como `text_delta`, `tool_use`, `tool_result`, `thinking`, `citation`, `card`, `artifact`, etc., facilitando a renderização no front-end por tipo correspondente. * **Interrupção / Recuperação**: o modelo emitirá um evento `ask_user_question` e pausará quando precisar de informações adicionais do usuário; na próxima chamada, basta preencher a resposta com `tool_results` para continuar. * **Novas ações CRUD**: no mesmo endpoint, é possível realizar `retrieve` / `retrieve_batch` / `update` / `delete` através do campo `action`, sem a necessidade de uma API de gerenciamento de sessão adicional. * **Lista de modelos em constante atualização**: por padrão, conecta-se a modelos contemporâneos como GPT-5.4, Claude Opus 4.8, Claude Sonnet 4.6, Gemini 3.1 Pro, GLM 5.1, DeepSeek V4, Kimi K3, entre outros. Além disso, no nível do corpo da solicitação, é **totalmente compatível com a v1**: basta enviar `model` + `question` (+ opcionalmente `stateful` / `id` / `references` / `preset`) para obter uma resposta JSON `{answer, id}` equivalente à v1, portanto, a migração de `/aichat/conversations` não requer reescrita do cliente, apenas troque o caminho para `/aichat2/conversations`. > Se você está atualmente usando `/aichat/conversations`, a interface antiga ainda estará disponível, permitindo que você migre no seu próprio ritmo. ## Processo de Solicitação Para usar a AI Chat v2 API, primeiro acesse o [Painel de Controle da Ace Data Cloud](https://platform.acedata.cloud/console/applications) para obter seu Token de API, que deve ser guardado. ![](https://cdn.acedata.cloud/5hmkdg.jpg) Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login, onde poderá se registrar e fazer login; após isso, você será retornado à página atual. **Um Token de API é suficiente para acessar todos os serviços da plataforma, não sendo necessário solicitar um para cada serviço.** A primeira solicitação oferece um crédito gratuito para que você possa experimentar; quando o crédito acabar, você pode recarregar o saldo geral no [painel de controle](https://platform.acedata.cloud/console/coin). > 📘 Documentação completa: [AI Chat v2 API →](https://platform.acedata.cloud/documents/aichat2-conversations) ## Uso Básico A forma mais simples de uso é idêntica à v1: envie `model` + `question` e receba `{answer, id}`. Exemplo de CURL: ```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": "Descreva a AceDataCloud em uma frase." }' ``` Resultado retornado: ```json theme={null} { "answer": "AceDataCloud é uma plataforma de API unificada que agrega modelos de IA populares e serviços multimodais, permitindo que desenvolvedores acessem serviços como GPT, Claude, Gemini, Midjourney, Suno, Veo, entre outros, com uma única chave.", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44" } ``` Exemplo em Python: ```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": "Descreva a AceDataCloud em uma frase.", } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` Os valores disponíveis para `model` podem ser vistos diretamente no painel de teste à direita, com categorias comuns incluindo: * 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. As regras de cobrança específicas podem ser consultadas no cartão de Preços na página de serviços. ## Diálogo Múltiplo Assim como na v1, envie `stateful: true` para ativar a preservação da sessão, e a API retornará um `id`; nas solicitações subsequentes, basta incluir o `id` para continuar a conversa, sem a necessidade de manter o histórico de mensagens. Primeira solicitação: ```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": "Lembre-se de um número: 42." }' ``` Retorno: ```json theme={null} { "answer": "Ok, eu já lembrei do 42. O que você gostaria que eu fizesse com ele?", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44" } ``` Segunda solicitação, incluindo o mesmo `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": "Qual é o número que pedi para você lembrar?" }' ``` ```json theme={null} { "answer": "O número que você me pediu para lembrar é 42.", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44" } ``` > `stateful` é `true` por padrão, omitir e passar `true` explicitamente é equivalente. Se você não deseja que o servidor salve esta rodada de conversa, pode definir explicitamente `stateful: false`. ## Resposta em fluxo v2 suporta dois formatos de fluxo, escolhidos de acordo com o cabeçalho `accept`: | Cenário | `accept` | Forma dos dados | | -------------------------------------- | --------------------------- | ----------------------------------------------------- | | Front-end Web / EventSource | `text/event-stream` | `data: {json}\n\n`, a última linha `data: [DONE]\n\n` | | Servidor / CLI / Análise de fluxo Node | `application/x-ndjson` | Um objeto JSON por linha | | Sem necessidade de fluxo | `application/json` (padrão) | Retorno único `{answer, id}` | ### Exemplo NDJSON ```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": "Descreva Hangzhou em três frases.", } 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": # Compatível com v1: fragmentos incrementais também fornecidos pelo campo delta_answer answer += event["content"] print(event["delta_answer"], end="", flush=True) elif event.get("type") == "done": print() print("uso =", event.get("usage")) ``` Cada linha do NDJSON é um evento estruturado, o mais comum é `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"} ``` ### Exemplo SSE No lado do navegador, o `EventSource` não suporta corpo de requisição personalizado, recomenda-se usar `fetch` + divisão manual por `\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: "Descreva Hangzhou em três frases.", }), }); 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); } } ``` ### Tipos de eventos em fluxo | `type` | Significado | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `text_delta` | Fragmentos de texto incrementais da resposta do assistente. `content` é o conteúdo novo; para compatibilidade com v1, o mesmo evento também carrega `delta_answer` (igual a `content`) e `id`. | | `thinking` | O processo de pensamento do modelo (apenas aparece quando o modelo selecionado expõe raciocínio). | | `tool_use` | O modelo decide chamar uma ferramenta, o evento carrega `tool_id`, `tool_name`, `input`. | | `tool_result` | Resultado da execução da ferramenta, emparelhado com a última `tool_use` através de `tool_id`, `is_error` indica se falhou. | | `card` | Cartão estruturado gerado pela ferramenta (como imagem, pré-visualização de link), adequado para renderização direta. | | `citation` | Usado para complementar a fonte URL de um trecho de texto correspondente. | | `ask_user_question` | O modelo emite quando precisa que o usuário forneça informações adicionais, a conversa entra no estado `awaiting_user_input`, veja abaixo [retomar conversa pausada](#retomar-conversa-pausada). | | `artifact` | Produtos independentes gerados pelo modelo (como blocos de código, documentos), que podem ser salvos ou baixados. | | `system_message` | Mensagens de sistema (não conteúdo do usuário e assistente), usadas apenas para dicas de UI. | | `compact` | Evento em que o contexto interno foi compactado, sem necessidade de tratamento especial. | | `error` | Erro ocorreu nesta rodada, `message` descreve o conteúdo do erro. | | `done` | Fim da resposta em fluxo, carrega `usage` (incluindo `prompt_tokens` / `completion_tokens` / `total_tokens`) e `terminal_reason`. | Para clientes que se preocupam apenas com a resposta final, concatenar todos os `content` de `text_delta` é equivalente ao `answer` no modo `application/json`. ## Entrada multimodal Se a entrada do usuário contiver imagens ou arquivos, passe `message` (array) em vez de `question`. Cada elemento do array é um bloco de conteúdo: ```json theme={null} { "model": "gpt-5.4", "stateful": true, "message": [ { "type": "text", "text": "Quantos gatos há nesta imagem?" }, { "type": "image_url", "image_url": { "url": "https://cdn.acedata.cloud/cats.jpg" } } ] } ``` Tipos de bloco suportados: * `text` — Texto comum, campo `text` é obrigatório. * `image_url` — Imagem, campo `image_url.url` é obrigatório. * `file_url` — Arquivo (PDF, CSV, TXT, etc.), campo `file_url.url` é obrigatório. ### Relação com `references` da v1 Para compatibilidade com clientes antigos, a v2 ainda reconhece o campo `references: ["https://...", ...]`: * O sufixo da URL é `jpg / jpeg / png / gif / bmp / webp / svg / heic / heif`, automaticamente se transforma em um bloco `image_url`; * Outros tipos de extensão se transformam em um bloco `file_url`; * Se também for fornecida uma `question`, ela deve ser colocada como um bloco `text` na frente. Portanto, se você deseja migrar apenas do v1 e não quer alterar o corpo da solicitação, basta trocar o caminho para `/aichat2/conversations`, o uso original de `references` continuará funcionando. Para um controle mais refinado (por exemplo, colocar várias imagens entre textos, ou se a ordem for muito importante), use diretamente o array `message`. ## Chamada de ferramentas e MCP O ponto central da v2 é que o modelo pode chamar ferramentas de forma autônoma para completar tarefas em várias etapas, **isso está ativado por padrão**, não sendo necessário que o cliente faça nenhuma configuração adicional na solicitação. Cenários comuns: * O usuário pergunta "Ajude-me a procurar quais novas exposições estão acontecendo em Xangai" → o modelo chama a pesquisa web embutida → organiza os resultados em uma resposta. * O usuário pergunta "Leia este PDF e escreva um resumo" → o modelo chama `file_read` → escreve o resumo. * O usuário já autorizou Google Drive / GitHub / Notion, etc., em [Connections](https://platform.acedata.cloud/connections) → o modelo pode chamar as ferramentas MCP correspondentes para ler e escrever seus dados. No fluxo NDJSON / SSE, a chamada de ferramentas é apresentada através de eventos do tipo `tool_use` e `tool_result`, por exemplo: ```json theme={null} {"type":"tool_use","tool_id":"toolu_01ABCDEF","tool_name":"web_search","input":{"query":"Xangai 2026 Exposições de Primavera"},"id":"f2f4b3e8-..."} {"type":"tool_result","tool_id":"toolu_01ABCDEF","output":"...","is_error":false,"id":"f2f4b3e8-..."} {"type":"text_delta","content":"Atualmente","delta_answer":"Atualmente","id":"f2f4b3e8-..."} {"type":"text_delta","content":"Xangai","delta_answer":"Xangai","id":"f2f4b3e8-..."} ... ``` Se você não quiser exibir os detalhes da chamada de ferramentas na interface, ignore os eventos `tool_use` / `tool_result` / `card` / `citation`, a saída final do modelo ainda será apresentada através de `text_delta`. `max_turns` pode limitar quantas vezes o modelo pode chamar ferramentas em uma única solicitação, o limite padrão é determinado pela plataforma. Defini-lo baixo (por exemplo, `max_turns: 1`) pode forçar uma única resposta, não permitindo nenhuma chamada de ferramenta. ## Execução assíncrona e autorização sem supervisão Se sua chamada vem de um Webhook de alerta, CI/CD, sistema de monitoramento ou outras tarefas em segundo plano, você pode definir `async: true` para que a interface retorne imediatamente o ID da tarefa, enquanto o backend continua a execução: ```json theme={null} { "model": "gpt-5.5", "async": true, "question": "Meu serviço disparou um alerta, use o WeChat pessoal para notificar o grupo 'Equipe AceDataCloud'..." } ``` Exemplo de retorno: ```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" } ``` Depois, você pode usar `action: retrieve` + `id` para consultar o resultado da conversa; também pode fornecer `callback_url`, e após a conclusão da tarefa, a plataforma enviará `{ status, answer, usage, error }` via POST para o seu endereço de callback. `callback_url` deve usar `http` / `https`, e não pode ser preenchido diretamente com `localhost` ou endereços IP privados. Tarefas em segundo plano geralmente não têm ninguém para clicar em confirmar. Se você deseja que algumas Skills ou MCP Server executem ações de envio, publicação, escrita, etc., em modo sem supervisão, forneça explicitamente a lista de pré-autorização no corpo da solicitação: ```json theme={null} { "model": "gpt-5.5", "async": true, "allowed_skills": ["acedatacloud/personal-wechat"], "allowed_mcp_servers": [], "question": "Meu serviço disparou um alerta, use o WeChat pessoal para notificar o grupo 'Equipe AceDataCloud'..." } ``` Os valores em `allowed_skills` são os slugs das Skills conectadas; os valores em `allowed_mcp_servers` são os slugs dos MCP Servers conectados. Skills / MCP Servers não listados na pré-autorização ainda poderão apenas visualizar, fazer dry-run ou recusar a execução de operações de escrita em modo sem supervisão. Se precisar de um controle mais detalhado, você também pode usar o objeto equivalente `unattended_policy`: ```json theme={null} { "unattended_policy": { "mode": "allow_selected", "allowed_skills": ["acedatacloud/personal-wechat"], "allowed_mcp_servers": [], "expires_at": 1790000000 } } ``` Nota: A pré-autorização apenas representa "esta solicitação permite que essas capacidades sejam executadas em modo sem supervisão sem confirmação humana". Skills específicas ainda devem suportar `--unattended-confirm` ou mecanismos de segurança correspondentes; caso contrário, continuarão a fazer dry-run e não executarão operações de escrita diretamente. ## Retomar conversas pausadas Algumas ferramentas farão com que o modelo "pergunte ao usuário", e nesse momento o modelo emitirá um evento `ask_user_question`, congelando a conversa no estado `awaiting_user_input`: ```json theme={null} { "type": "ask_user_question", "tool_id": "toolu_01XYZW", "tool_name": "ask_user_question", "question": "Você prefere que o relatório gerado seja em chinês ou inglês?", "options": ["Chinês", "Inglês"], "id": "f2f4b3e8-..." } ``` Na interface, esse evento deve ser renderizado como um cartão para que o usuário escolha uma resposta, e então, usando o mesmo `id`, inicie a próxima solicitação, preenchendo a resposta através de `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": "Chinês" } ] }' ``` O `tool_use_id` no corpo da solicitação **deve** ser exatamente o mesmo que o `tool_id` no momento da pausa; se não for, retornará 400. Quando `tool_results` estiver presente na solicitação, `question` / `message` / `references` serão ignorados. Se o usuário decidir desistir dessa pergunta, basta enviar uma nova `question` / `message`, e a plataforma marcará automaticamente a chamada da ferramenta pausada como "pulada pelo usuário". ## Gerenciamento de sessões (CRUD) A v2 oferece gerenciamento leve de sessões no mesmo endpoint através do campo `action`, sem necessidade de abrir uma API separada. ### `action: retrieve` — Recuperar uma sessão ```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" }' ``` Retorna o documento completo da conversa (incluindo o histórico de `messages`, `model`, `title`, `tools_used`, etc.). ### `action: retrieve_batch` —— Listar resumos de conversas ```json theme={null} { "action": "retrieve_batch", "model_group": "chatgpt", "limit": 20, "offset": 0 } ``` Retorna `{ items: [...], total }`. **O resumo não inclui `messages`**, adequado para uma lista de barra lateral; se o usuário abrir uma conversa, use `action: retrieve` para buscar suas mensagens completas separadamente. Parâmetros de filtragem opcionais: `user_id`, `application_id`, `model_group`, `model`. ### `action: update` —— Alterar título ou reescrever histórico ```json theme={null} { "action": "update", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44", "title": "Plano de viagem para Hangzhou" } ``` `messages` também pode ser enviado, mas o servidor fará uma verificação rigorosa do schema (deve estar na forma de `ToolUseContent` colapsada), não conformidades retornarão 400. Geralmente, recomenda-se usar apenas para alterar o `title`. ### `action: delete` —— Deletar uma conversa ```json theme={null} { "action": "delete", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44" } ``` Retorna `{ id, success: true }`. Após a exclusão, não pode ser recuperado, por favor, confirme antes de chamar. ## Migração suave do v1 Se você já está usando [`/aichat/conversations`](https://platform.acedata.cloud/documents/aichat-conversations), a migração para o v2 quase não requer alteração de código: 1. Altere a URL de `https://api.acedata.cloud/aichat/conversations` para `https://api.acedata.cloud/aichat2/conversations`. 2. Se você estava usando nomes de modelos v1 (como `gpt-3.5`, `gpt-4-browsing`, etc.), ao mudar para v2, recomenda-se atualizar para modelos contemporâneos (como `gpt-5.4`, `claude-opus-4-8`, `gemini-3.1-pro`, etc.). 3. Os campos do fluxo NDJSON permanecem compatíveis: cada evento `text_delta` ainda traz `delta_answer` e `id`, portanto, os clientes que originalmente analisavam `delta_answer` linha por linha não precisam ser alterados. Após a migração, você pode ativar as novas capacidades do v2 conforme necessário (entrada multimodal `message`, SSE, chamadas de ferramentas, CRUD de `action`), avançando no seu próprio ritmo. ## Tratamento de erros As respostas de erro são unificadas como: ```json theme={null} { "error": { "code": "chat_error", "message": "upstream LLM returned an error" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` Erros comuns: * `400 bad_request`: campos obrigatórios ausentes, `tool_use_id` não correspondente, schema de `messages` inválido, etc. * `401 invalid_token`: cabeçalho `authorization` incorreto. * `404 not_found`: ao usar `action: retrieve / update / delete`, a conversa correspondente ao `id` não existe. * `429 too_many_requests`: limite de taxa acionado. * `500 chat_error`: erro do LLM upstream ou `completion_tokens=0` nesta rodada (tratado como não consumido, não haverá cobrança). Em respostas em fluxo, os erros são enviados como `{"type":"error","message":"..."}` e, em seguida, o fluxo será encerrado. ## Conclusão A API AI Chat v2, ao manter a compatibilidade com o v1, atualiza as conversas de "perguntas e respostas de uma única rodada/múltiplas rodadas" para "conversas observáveis em formato de agente": entrada multimodal, chamadas de ferramentas, pausáveis/recuperáveis, eventos estruturados em fluxo, CRUD embutido. Recomenda-se que novas integrações usem diretamente o v2; integrações existentes do v1 podem ser migradas suavemente em fases. Se houver qualquer dúvida, entre em contato com nossa equipe de suporte técnico.