ai-chat

Files (1)

• SKILL.md

SKILL.md (first lines)

# AI Chat — Unified LLM Gateway

AceDataCloud exposes the following documented chat surfaces:

| Endpoint | Use For |
|----------|---------|
| `POST /aichat2/conversations` | Recommended stateful / multimodal / agentic conversations |
| `POST /aichat/conversations` | Legacy conversation endpoint |
| `POST /openai/chat/completions` (public alias `/v1/chat/completions`) | OpenAI-compatible stateless chat completions |
| `POST /openai/responses` (public alias `/v1/responses`) | OpenAI-compatible responses API |
| `POST /kimi/chat/completions` (public alias `/v1/chat/completions`) | Kimi Chat Completions with model-specific reasoning controls |
| `POST /v1/chat/completions` (alias `/claude/chat/completions`) | Claude Chat Completions, including Opus 5.5 |
| `POST /gemini/chat/completions` (public alias `/v1/chat/completions`) | Gemini Chat Completions, including Gemini 4 Argon |
| `POST /v1/messages` (alias `/claude/messages`) | Native Claude Messages, including thinking and tool calls |
| `POST /v1/messages/count_tokens` (alias `/claude/messages/count_tokens`) | Count native Claude input tokens without generating output |
| `POST /v1beta/models/{model}:generateContent` | Native Gemini content generation, including audio input |
| `POST /v1beta/models/{model}:streamGenerateContent?alt=sse` | Native Gemini SSE streaming |

## First-time setup

1. Install the official Skill with `clawhub install @acedatacloud/ai-chat`. Check that the ClawHub publisher is **@acedatacloud**.
2. Sign in at [AceDataCloud → Applications](https://platform.acedata.cloud/console/applications), open **General application**, and check AI Chat access, balance, and current pricing. Copy its API key, or select **Manage Keys → Create** for a separate key. Copy the key value without `Bearer `; a `platform-...` management token is not a service API key.
3. If you enable **Allowed APIs** restrictions, include `/aichat2/conversations` for the first example; other chat routes need their own access. Advanced workflows below may call additional routes.
4. On the OpenClaw Gateway host, put `ACEDATACLOUD_API_TOKEN=your_api_key_here` in `~/.openclaw/.env`, then restart the Gateway and start a new session. For a direct terminal test, run `export ACEDATACLOUD_API_TOKEN="your_api_key_here"` in that shell. Never put the key in a prompt or commit an `.env` file.
5. Run the **Quick Start** below. If this workflow returns a task ID, query that same task until it finishes; do not submit the same billable request again just to check progress.

[Illustrated key setup, first run, and troubleshooting](https://github.com/AceDataCloud/Skills#first-run-with-clawhub-and-openclaw) · [Token details](https://github.com/AceDataCloud/Skills/blob/main/skills/_shared/authentication.md)

## Quick Start

### Recommended: stateful conversations

```bash
curl -X POST https://api.acedata.cloud/aichat2/conversations \
  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4.1","question":"Summarize the latest release notes.","stateful":true}'
```

### OpenAI-compatible SDK

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ACEDATACLOUD_API_TOKEN"],
    base_url="https://api.acedata.cloud/openai"
)

response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Explain quantum computing"}]
)
print(response.choices[0].message.content)
```

### Dify: OpenAI-API-compatible provider

Set **Base URL** to `https://api.acedata.cloud/v1`, **API Key** to your AceDataCloud service token, **model** to `gpt-5.5` (or another supported chat model), and **model type** to LLM. Select **conversation type** Chat and **API type** Chat Completions. Dify appends `/chat/completions` itself; do not use `/openai/v1` or include the full endpoint in Base URL. Test the connection before selecting the model in a Workflow / Chatflow LLM node.

## Currently Documented Model Families

The OpenAPI specs expose a broad, fast-moving model catalog. Representative current
models include:

| Family | Current examples |
|--------|------------------|
| OpenAI / reasoning | `gpt-6-astra`, `gpt-6.1-sol`, `gpt-6-sol`, `gpt-6-luna`, `gpt-5.6-luna`, `gpt-5.6-terra`, `gpt-5.6-sol-fast`, `gpt-5.6-sol`, `gpt-5.5`, `gpt-5.5-pro`, `gpt-5.4`, `gpt-5.4-pro`, `gpt-5.2`, `gpt-5.1`, `gpt-5`, `gpt-5-mini`, `gpt-5-nano`, `gpt-4.1`, `gpt-4.1-mini`, `gpt-4.1-nano`, `gpt-4o`, `gpt-4o-mini`, `o1`, `o3`, `o4-mini` |
| OpenAI free-tier chat-completions | `gpt-5.5:free`, `gpt-5:free`, `gpt-4.1:free`, `gpt-4o:free`, `gpt-4o-mini:free`, `gpt-oss:free` |
| Claude | `claude-opus-5-5`, `claude-sonnet-5-5`, `claude-fable-5-1`, `claude-fable-5`, `claude-opus-5`, `claude-sonnet-5`, `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-sonnet-4-20250514`, `claude-haiku-4-5-20251001`, `claude-3-7-sonnet-20250219` |
| Gemini | `gemini-4-argon`, `gemini-3.8-flash`, `gemini-3.6-flash`, `gemini-3.5-flash`, `gemini-3.1-pro`, `gemini-3.1-pro-preview`, `gemini-3.1-flash-lite-preview`, `gemini-3-pro-preview`, `gemini-2.5-flash-lite`, `gemini-2.0-flash-lite` |
| Grok | `grok-4.7`, `grok-4.5`, `grok-4`, `grok-4-0709`, `grok-3`, `grok-3-fast` |
| DeepSeek | `deepseek-v4.1-flash`, `deepseek-v4-pro`, `deepseek-v4-flash`, `deepseek-r1`, `deepseek-r1-0528`, `deepseek-v3`, `deepseek-v3-250324`, `deepseek-v3.2-exp` |
| Kimi | `kimi-k3.1-pro`, `kimi-k3`, `kimi-k2.6`, `kimi-k2.5`, `kimi-k2-thinking-turbo`, `kimi-k2-thinking` |
| GLM | `glm-5.2`, `glm-5.1`, `glm-5`, `glm-5-turbo`, `glm-4.7`, `glm-4.6`, `glm-4.5`, `glm-4.5v`, `glm-3-turbo` |

When the user asks for a recommended model, read the current public `GET https://platform.acedata.cloud/api/v1/models/` response and prefer suitable entries with `recommended=true`. This is an editorial preference, not an access grant or a new API capability; `recommended=false` does not retire a model. Check the selected model's supported route and current pricing before calling it, and do not silently replace a model the user explicitly selected.

Catalog discovery follows the requesting visitor's IP, not the display language or a `?country=` override. Mainland-China views hide marked Claude, OpenAI, Gemini and Grok chat catalog entries. Check media visibility separately: OpenAI image generation/editing and companion guides are also hidden in mainland China. Read the service's `image_unavailable_regions` and API/document `unavailable_regions`; do not hide unrelated media or the entire mixed service based on chat-only or image-only restrictions. Raw catalog responses may retain marked rows, so presence alone is not visibility. Honor the current public visibility when recommending models; do not use a cached global list to advertise region-hidden chat or images. A missing catalog entry is not evidence of retirement or revoked API access: this presentation filtering does not change API routing or billing. Report the discovery limitation, check actual account access and pricing, and do not silently replace a user-selected model.

To select `gpt-5.6-sol-fast`, send that exact public model ID on Chat Completions, Responses, Messages, or either conversation endpoint above. It is listed in the public model/pricing catalog with vision capability, but has no public model introduction. Check account eligibility and current pricing before requesting it; catalog visibility does not guarantee access. Its pricing rules use a higher tier when total input exceeds 272,000 (not at exactly 272,000). For Chat Completions and Responses, input totals already include reported cache tokens; for Messages, add the separately reported cache-read and cache-creation tokens to uncached input before checking this threshold. Do not silently substitute `gpt-5.6-sol` after an access or parameter error; protocol-specific features remain model-dependent.

`gpt-6.1-sol` supports `low`, `medium`, `high`, `xhigh`, and `max` reasoning effort; do not send `none` or `minimal`. During its first week, access requires verified ACE T1+ holdings or an access grant. Check the platform access response for the opening time.

`claude-opus-5-5` is available on Claude Chat Completions (`POST /v1/chat/completions`) and native Messages (`POST /v1/messages`). Messages remains the recommended route for complete thinking blocks and native tool semantics. Ordinary and streaming Chat Completions are supported, but Chat replies do not return native thinking blocks. For Chat Completions, use `n=1`, omit non-default `temperature` and `top_p`, and use `tool_choice: "auto"` rather than forcing a tool. `claude-sonnet-5-5` remains a Messages model. Check the current public model list and account access before using another route; cross-protocol pricing rules do not establish identical feature support.

`/aichat2/conversations` also accepts `model_group` values
`chatgpt`, `claude`, `gemini`, `grok`, `kimi`, `glm`, and `deepseek`.

> **Image-generating models are not chat models.** Names ending in `-image`
> (e.g. `gemini-*-image`, `gpt-4o-image`) are image-generation models; they
> do not work on the OpenAI-compatible chat, Claude Messages, or conversation
> routes. Generate images through the dedicated endpoints instead — Gemini via
> `POST /v1beta/models/{model}:generateContent`, or `/nano-banana/images`.

## Token billing across compatible protocols

1. Before submitting, check the selected route's current public model list, account access, key restrictions and current model pricing. A settlement rule is not a publication or access grant. Keep the requested public model ID; do not silently substitute another model or route after an error.
2. For accepted compatible-model requests, billing follows the model's actual input, output and cache usage. Switching between Chat Completions, Responses and Messages does not turn token billing into a fixed per-request fee or guarantee the same price across protocols.
3. Read the actual response `usage` using that protocol's fields:

   | Protocol | Input/cache accounting |
   |----------|------------------------|
   | Chat Completions | `usage.prompt_tokens` includes reported cache tokens. Treat `usage.prompt_tokens_details.cached_tokens` as a subset, not extra input; the reported cache portion uses its corresponding cache price. |
   | Responses | `usage.input_tokens` includes reported cache tokens. Treat reported cache tokens in `usage.input_tokens_details` as a subset, not extra input; the cache portion uses its corresponding cache price. |
   | Messages | `usage.input_tokens` excludes the separately reported `usage.cache_read_input_tokens` and `usage.cache_creation_input_tokens`. Account for these dimensions separately at their corresponding prices. If `usage.cache_creation` reports 5-minute/1-hour details, these partition creation usage; do not add them again to the creation total. |

4. Check the console's current model prices and the returned `usage.cost` for the actual charge. Report only returned usage/cost fields; missing cache or cost data is not evidence of a cache hit or a free request. Do not invent a charge from a reference USD price.

## OpenAI-Compatible Chat

```json
POST /openai/chat/completions
{
  "model": "gpt-4.1",
  "messages": [{"role": "user", "content": "Write a haiku about observability."}],
  "stream": true,
  "tools": [

From AceDataCloud/Skills, Apache-2.0.

More from AceDataCloud/Skills