@acedatacloud/skills 2026.406.0

package/skills/acedatacloud-api/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: acedatacloud-api
+description: Guide for using AceDataCloud APIs. Use when authenticating, making API calls, managing credentials, understanding billing, or integrating AceDataCloud services into applications. Covers setup, authentication, request patterns, error handling, and SDK integration.
+license: Apache-2.0
+metadata:
+  author: acedatacloud
+  version: "1.0"
+compatibility: Requires an AceDataCloud account at platform.acedata.cloud.
+---
+
+# AceDataCloud API Usage Guide
+
+Complete guide for using AceDataCloud's AI-powered data services API.
+
+## Getting Started
+
+### 1. Create an Account
+
+Register at [platform.acedata.cloud](https://platform.acedata.cloud).
+
+### 2. Subscribe to a Service
+
+Browse available services and click **Get** to subscribe. Most services include free quota.
+
+### 3. Create API Credentials
+
+Go to your service's **Credentials** page and create an API Token.
+
+> **Full details:** See [authentication](../_shared/authentication.md) for token types and usage.
+
+## SDK Integration (OpenAI-Compatible)
+
+For chat completion services, use the standard OpenAI SDK:
+
+```python
+from openai import OpenAI
+
+client = OpenAI(
+    api_key="YOUR_API_TOKEN",
+    base_url="https://api.acedata.cloud/v1"
+)
+
+response = client.chat.completions.create(
+    model="claude-sonnet-4-20250514",
+    messages=[{"role": "user", "content": "Hello!"}]
+)
+```
+
+```javascript
+import OpenAI from "openai";
+
+const client = new OpenAI({
+  apiKey: "YOUR_API_TOKEN",
+  baseURL: "https://api.acedata.cloud/v1"
+});
+
+const response = await client.chat.completions.create({
+  model: "gpt-4.1",
+  messages: [{ role: "user", content: "Hello!" }]
+});
+```
+
+## Request Patterns
+
+### Synchronous APIs
+
+Some APIs return results immediately (e.g., face transform, search):
+
+```bash
+curl -X POST https://api.acedata.cloud/face/analyze \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"image_url": "https://example.com/photo.jpg"}'
+```
+
+### Async Task APIs
+
+Most generation APIs (images, video, music) are asynchronous.
+
+> **Full details:** See [async task polling](../_shared/async-tasks.md) for the submit-and-poll pattern.
+
+## Error Handling
+
+| HTTP Code | Meaning | Action |
+|-----------|---------|--------|
+| 400 | Bad request | Check request parameters |
+| 401 | Unauthorized | Check API token |
+| 403 | Forbidden | Content filtered or insufficient permissions |
+| 429 | Rate limited | Wait and retry with backoff |
+| 500 | Server error | Retry or contact support |
+
+Error response format:
+
+```json
+{
+  "error": {
+    "code": "token_mismatched",
+    "message": "Invalid or expired token"
+  }
+}
+```
+
+## Billing
+
+- Each API call deducts from your **subscription balance** (remaining_amount)
+- Cost varies by service, model, and usage (tokens, requests, data size)
+- Check balance at [platform.acedata.cloud](https://platform.acedata.cloud)
+- Most services offer free trial quota
+
+## Service Categories
+
+| Category | Services | Base Path |
+|----------|----------|-----------|
+| **AI Chat** | GPT, Claude, Gemini, DeepSeek, Grok | `/v1/chat/completions` |
+| **Image Gen** | Midjourney, Flux, Seedream, NanoBanana | `/midjourney/*`, `/flux/*`, etc. |
+| **Video Gen** | Luma, Sora, Veo, Kling, Hailuo, Seedance, Wan | `/luma/*`, `/sora/*`, etc. |
+| **Music Gen** | Suno, Producer, Fish Audio | `/suno/*`, `/producer/*`, `/fish/*` |
+| **Search** | Google Search (web/images/news/maps) | `/serp/*` |
+| **Face** | Analyze, beautify, swap, cartoon, age | `/face/*` |
+| **Utility** | Short URL, QR Art, Headshots | `/short-url`, `/qrart/*`, `/headshots/*` |
+
+## Gotchas
+
+- Tokens are **service-scoped** by default — create a global token if you need cross-service access
+- Async APIs return a `task_id` — always use `callback_url` to get the task_id immediately, then poll for results
+- Avoid `wait: true` — it blocks for the full generation duration and will time out for video/music tasks
+- Rate limits vary by service tier — upgrade your plan if hitting limits
+- All timestamps are in UTC
+
+> **MCP:** See [MCP servers](../_shared/mcp-servers.md) for tool-use integration with AI agents.

package/skills/ai-chat/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: ai-chat
+description: Access 50+ LLM models through a unified OpenAI-compatible API via AceDataCloud. Use when you need chat completions from GPT, Claude, Gemini, DeepSeek, Grok, or other models through a single endpoint. Supports streaming, function calling, and vision.
+license: Apache-2.0
+metadata:
+  author: acedatacloud
+  version: "1.0"
+compatibility: Requires ACEDATACLOUD_API_TOKEN environment variable. Works as a drop-in replacement for the OpenAI SDK.
+---
+
+# AI Chat — Unified LLM Gateway
+
+Access 50+ language models through a single OpenAI-compatible endpoint via AceDataCloud.
+
+> **Setup:** See [authentication](../_shared/authentication.md) for token setup.
+
+## Quick Start
+
+```bash
+curl -X POST https://api.acedata.cloud/v1/chat/completions \
+  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"model": "claude-sonnet-4-20250514", "messages": [{"role": "user", "content": "Hello!"}]}'
+```
+
+## OpenAI SDK Drop-in
+
+```python
+from openai import OpenAI
+
+client = OpenAI(
+    api_key="your-token-here",
+    base_url="https://api.acedata.cloud/v1"
+)
+
+response = client.chat.completions.create(
+    model="gpt-4.1",
+    messages=[{"role": "user", "content": "Explain quantum computing"}]
+)
+print(response.choices[0].message.content)
+```
+
+## Available Models
+
+### OpenAI GPT
+
+| Model | Type | Best For |
+|-------|------|----------|
+| `gpt-4.1` | Latest | General-purpose, high quality |
+| `gpt-4.1-mini` | Small | Fast, cost-effective |
+| `gpt-4.1-nano` | Tiny | Ultra-fast, lowest cost |
+| `gpt-4o` | Multimodal | Vision + text |
+| `gpt-4o-mini` | Small multimodal | Fast vision tasks |
+| `o1` | Reasoning | Complex reasoning tasks |
+| `o1-mini` | Small reasoning | Quick reasoning |
+| `o1-pro` | Pro reasoning | Advanced reasoning |
+| `gpt-5` | Latest gen | Next-gen intelligence |
+| `gpt-5-mini` | Mini gen 5 | Fast next-gen |
+
+### Anthropic Claude
+
+| Model | Type | Best For |
+|-------|------|----------|
+| `claude-opus-4-6` | Latest Opus | Highest capability |
+| `claude-sonnet-4-6` | Latest Sonnet | Balanced quality/speed |
+| `claude-opus-4-5-20251101` | Opus 4.5 | Premium tasks |
+| `claude-sonnet-4-5-20250929` | Sonnet 4.5 | High-quality balance |
+| `claude-sonnet-4-20250514` | Sonnet 4 | Reliable general-purpose |
+| `claude-haiku-4-5-20251001` | Haiku 4.5 | Fast, efficient |
+| `claude-3-5-sonnet-20241022` | Legacy 3.5 | Proven track record |
+| `claude-3-opus-20240229` | Legacy Opus | Maximum quality (legacy) |
+
+### Google Gemini
+
+| Model | Best For |
+|-------|----------|
+| `gemini-1.5-pro` | Long context, complex tasks |
+| `gemini-1.5-flash` | Fast, efficient |
+
+### DeepSeek
+
+| Model | Best For |
+|-------|----------|
+| `deepseek-r1` | Deep reasoning |
+| `deepseek-r1-0528` | Latest reasoning |
+| `deepseek-v3` | General-purpose |
+| `deepseek-v3-250324` | Latest general |
+
+### xAI Grok
+
+| Model | Best For |
+|-------|----------|
+| `grok-4` | Latest, highest capability |
+| `grok-3` | General-purpose |
+| `grok-3-fast` | Speed-optimized |
+| `grok-3-mini` | Compact, efficient |
+
+## Features
+
+### Streaming
+
+```json
+POST /v1/chat/completions
+{
+  "model": "claude-sonnet-4-20250514",
+  "messages": [{"role": "user", "content": "Write a story"}],
+  "stream": true
+}
+```
+
+### Function Calling
+
+```json
+POST /v1/chat/completions
+{
+  "model": "gpt-4.1",
+  "messages": [{"role": "user", "content": "What's the weather in Tokyo?"}],
+  "tools": [
+    {
+      "type": "function",
+      "function": {
+        "name": "get_weather",
+        "parameters": {"type": "object", "properties": {"location": {"type": "string"}}}
+      }
+    }
+  ]
+}
+```
+
+### Vision
+
+```json
+POST /v1/chat/completions
+{
+  "model": "gpt-4o",
+  "messages": [
+    {
+      "role": "user",
+      "content": [
+        {"type": "text", "text": "What's in this image?"},
+        {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}
+      ]
+    }
+  ]
+}
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `model` | string | Model name (see tables above) |
+| `messages` | array | Array of `{role, content}` objects |
+| `temperature` | 0–2 | Randomness (default: 1) |
+| `top_p` | 0–1 | Nucleus sampling |
+| `max_tokens` | integer | Maximum output tokens |
+| `stream` | boolean | Enable SSE streaming |
+| `tools` | array | Function calling definitions |
+| `tool_choice` | string/object | Tool selection strategy |
+
+## Response
+
+```json
+{
+  "id": "chatcmpl-xxx",
+  "object": "chat.completion",
+  "model": "claude-sonnet-4-20250514",
+  "choices": [
+    {
+      "index": 0,
+      "message": {"role": "assistant", "content": "Hello!"},
+      "finish_reason": "stop"
+    }
+  ],
+  "usage": {
+    "prompt_tokens": 10,
+    "completion_tokens": 5,
+    "total_tokens": 15
+  }
+}
+```
+
+## Gotchas
+
+- **100% OpenAI-compatible** — use the standard OpenAI SDK with `base_url="https://api.acedata.cloud/v1"`
+- Billing is token-based with per-model pricing (more expensive models cost more per token)
+- Vision is supported on multimodal models (`gpt-4o`, `gpt-4o-mini`, `grok-2-vision-*`)
+- Function calling works on most modern models (GPT-4+, Claude 3+)
+- Streaming returns `chat.completion.chunk` objects via SSE
+- `finish_reason` values: `"stop"` (complete), `"length"` (max tokens), `"tool_calls"` (function call), `"content_filter"` (filtered)
+
+## Stateful Conversations Endpoint
+
+For stateful, session-based chat (no need to send the full history each time), use the `/aichat/conversations` endpoint:
+
+```bash
+curl -X POST https://api.acedata.cloud/aichat/conversations \
+  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"model": "gpt-4.1", "question": "What is quantum computing?", "stateful": true}'
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `model` | string | Model name (see Available Models above) |
+| `question` | string | The prompt or question to answer |
+| `id` | string | Conversation ID — pass the same ID to continue a session |
+| `preset` | string | Preset/system prompt for the conversation |
+| `stateful` | boolean | Enable stateful conversation (maintains history server-side) |
+| `references` | array | Additional context documents to include |

package/skills/face-transform/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: face-transform
+description: Analyze and transform faces via AceDataCloud API. Use when detecting face keypoints, beautifying portraits, aging/de-aging faces, swapping genders, replacing faces between photos, creating cartoon avatars, or detecting liveness. Provides 7 specialized face APIs.
+license: Apache-2.0
+metadata:
+  author: acedatacloud
+  version: "1.0"
+compatibility: Requires ACEDATACLOUD_API_TOKEN environment variable.
+---
+
+# Face Transform
+
+Analyze and transform faces through AceDataCloud's Face API suite.
+
+> **Setup:** See [authentication](../_shared/authentication.md) for token setup.
+
+## Quick Start
+
+```bash
+curl -X POST https://api.acedata.cloud/face/analyze \
+  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"image_url": "https://example.com/portrait.jpg"}'
+```
+
+## Available APIs
+
+| Endpoint | Purpose | Description |
+|----------|---------|-------------|
+| `POST /face/analyze` | Face Detection | Detect face keypoints (90+ points per face) |
+| `POST /face/beautify` | Beautification | Apply beauty/decoration effects |
+| `POST /face/change-age` | Age Transform | Make a face look older or younger |
+| `POST /face/change-gender` | Gender Swap | Transform facial gender characteristics |
+| `POST /face/swap` | Face Swap | Replace one person's face with another |
+| `POST /face/cartoon` | Cartoon Style | Convert portrait to animated/cartoon style |
+| `POST /face/detect-live` | Liveness Check | Detect if a face image is from a live person |
+
+## Workflows
+
+### 1. Face Analysis
+
+Detect faces and extract 90+ keypoints per face.
+
+```json
+POST /face/analyze
+{
+  "image_url": "https://example.com/photo.jpg"
+}
+```
+
+Response includes detailed keypoints: `nose`, `mouth`, `left_eye`, `right_eye`, `left_eyebrow`, `right_eyebrow`, `contour` — each as arrays of `{x, y}` coordinates.
+
+### 2. Face Beautification
+
+```json
+POST /face/beautify
+{
+  "image_url": "https://example.com/portrait.jpg"
+}
+```
+
+### 3. Age Transformation
+
+```json
+POST /face/change-age
+{
+  "image_url": "https://example.com/portrait.jpg"
+}
+```
+
+### 4. Gender Swap
+
+```json
+POST /face/change-gender
+{
+  "image_url": "https://example.com/portrait.jpg"
+}
+```
+
+### 5. Face Swap
+
+Replace the face in the target image with the face from the source.
+
+```json
+POST /face/swap
+{
+  "source_image_url": "https://example.com/source-face.jpg",
+  "target_image_url": "https://example.com/target-person.jpg"
+}
+```
+
+### 6. Cartoon Style
+
+```json
+POST /face/cartoon
+{
+  "image_url": "https://example.com/portrait.jpg"
+}
+```
+
+### 7. Liveness Detection
+
+```json
+POST /face/detect-live
+{
+  "image_url": "https://example.com/face-photo.jpg"
+}
+```
+
+## Parameters
+
+### Common
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `image_url` | Yes (most endpoints) | Source face image URL |
+
+### `/face/swap`
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `source_image_url` | Yes | URL of the face to use (replaces the face) |
+| `target_image_url` | Yes | URL of the image to put the face onto |
+| `callback_url` | No | Webhook URL for async delivery |
+| `timeout` | No | Max wait time in seconds (default: 120) |
+
+### `/face/beautify`
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `image_url` | Yes | Image URL |
+| `smoothing` | No | Skin smoothing 0–100 (default: 10) |
+| `whitening` | No | Whitening 0–100 (default: 30) |
+| `face_lifting` | No | Face slimming 0–100 (default: 70) |
+| `eye_enlarging` | No | Eye enlarging 0–100 (default: 70) |
+
+### `/face/analyze`
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `image_url` | Yes | Image URL |
+| `mode` | No | `0` = all faces (default), `1` = largest face only |
+| `face_model_version` | No | Algorithm version (recommended: `3.0`) |
+| `need_rotate_detection` | No | `0` = disabled (default), `1` = enabled |
+
+## Gotchas
+
+- All face APIs return results synchronously. `/face/swap` additionally supports an optional `callback_url` parameter for async delivery (pass it to receive the result via webhook instead of waiting inline)
+- Face analyze returns 90+ keypoints per detected face, supporting multiple faces in one image
+- Face swap uses `source_image_url` (the face to apply) and `target_image_url` (the body to apply it to)
+- All APIs are currently in **Alpha** stage — interfaces may evolve
+- Images should contain clearly visible, front-facing faces for best results
+- Liveness detection helps distinguish live photos from printed/screen photos

package/skills/fish-audio/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: fish-audio
+description: Generate AI audio and synthesize voices with Fish Audio via AceDataCloud API. Use when creating text-to-speech audio, synthesizing voices, or generating audio content. Supports multiple voice models and TTS capabilities.
+license: Apache-2.0
+metadata:
+  author: acedatacloud
+  version: "1.0"
+compatibility: Requires ACEDATACLOUD_API_TOKEN environment variable.
+---
+
+# Fish Audio — Voice & Audio Synthesis
+
+Generate AI audio and synthesize voices through AceDataCloud's Fish Audio API.
+
+> **Setup:** See [authentication](../_shared/authentication.md) for token setup.
+
+## Quick Start
+
+```bash
+curl -X POST https://api.acedata.cloud/fish/audios \
+  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"prompt": "Hello, this is a demonstration of AI voice synthesis."}'
+```
+
+> **Async:** See [async task polling](../_shared/async-tasks.md). Poll via `POST /fish/tasks` with `{"task_id": "..."}`.
+
+## Endpoints
+
+| Endpoint | Purpose |
+|----------|---------|
+| `POST /fish/audios` | Generate audio from text or parameters |
+| `POST /fish/voices` | Voice synthesis and cloning |
+| `POST /fish/tasks` | Poll task status |
+
+## Workflows
+
+### 1. Text-to-Speech
+
+```json
+POST /fish/audios
+{
+  "prompt": "The quick brown fox jumps over the lazy dog.",
+  "voice_id": "default"
+}
+```
+
+### 2. Voice Cloning — Register a Voice
+
+Upload a reference audio to create a cloneable voice.
+
+```json
+POST /fish/voices
+{
+  "voice_url": "https://example.com/reference-voice.mp3",
+  "title": "My Custom Voice",
+  "description": "Clear, neutral-toned speaker for TTS",
+  "image_url": "https://example.com/avatar.jpg"
+}
+```
+
+### 3. Text-to-Speech with Cloned Voice
+
+```json
+POST /fish/audios
+{
+  "prompt": "Welcome to our platform.",
+  "voice_id": "<voice_id from POST /fish/voices>"
+}
+```
+
+## Parameters
+
+### `/fish/audios`
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `prompt` | string | Text to synthesize into speech |
+| `voice_id` | string | Voice model or cloned voice ID to use |
+| `model` | string | TTS model (e.g., `"speech-1.5"`, `"speech-1.5-hd"`) |
+| `action` | string | Operation type (e.g., `"generate"`) |
+| `callback_url` | string | Webhook URL for async delivery |
+
+### `/fish/voices`
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `voice_url` | string | Reference audio URL for voice cloning |
+| `title` | string | Display title for the cloned voice |
+| `description` | string | Description of the voice |
+| `image_url` | string | Cover image URL for the voice |
+| `callback_url` | string | Webhook URL for async delivery |
+
+## Gotchas
+
+- Pricing is based on **byte count** of the generated audio
+- Voice cloning requires a clear reference audio sample
+- Text-to-speech supports multiple languages automatically
+- Use the `/fish/voices` endpoint to register a reference audio and receive a `voice_id` for TTS

package/skills/flux-image/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: flux-image
+description: Generate and edit images with Flux (Black Forest Labs) via AceDataCloud API. Use when creating images from text prompts, editing existing images with text instructions, or when high-quality image generation is needed. Supports multiple Flux models including dev, pro, ultra, and kontext for editing.
+license: Apache-2.0
+metadata:
+  author: acedatacloud
+  version: "1.0"
+compatibility: Requires ACEDATACLOUD_API_TOKEN environment variable. Optionally pair with mcp-flux for tool-use.
+---
+
+# Flux Image Generation
+
+Generate and edit images through AceDataCloud's Flux API.
+
+> **Setup:** See [authentication](../_shared/authentication.md) for token setup.
+
+## Quick Start
+
+```bash
+curl -X POST https://api.acedata.cloud/flux/images \
+  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"prompt": "a cat wearing a space helmet, photorealistic", "model": "flux-dev", "callback_url": "https://api.acedata.cloud/health"}'
+```
+
+> **Async:** See [async task polling](../_shared/async-tasks.md). Poll via `POST /flux/tasks` with `{"task_id": "..."}`.
+
+## Models
+
+| Model | Quality | Speed | Sizes | Best For |
+|-------|---------|-------|-------|----------|
+| `flux-dev` | Good | Fast | 256–1440px | Quick generation (default) |
+| `flux-pro` | High | Medium | 256–1440px | Production work |
+| `flux-pro-1.1` | Higher | Medium | 256–1440px | Better prompt following |
+| `flux-pro-1.1-ultra` | Highest | Slow | Aspect ratios | Maximum quality |
+| `flux-kontext-pro` | High | Medium | Aspect ratios | Image editing |
+| `flux-kontext-max` | Highest | Slow | Aspect ratios | Complex editing |
+
+## Generate Images
+
+```json
+POST /flux/images
+{
+  "prompt": "a minimalist logo of a mountain",
+  "action": "generate",
+  "model": "flux-pro-1.1",
+  "size": "1024x1024",
+  "count": 1
+}
+```
+
+### Size Options
+
+**For dev/pro/pro-1.1** (pixel dimensions):
+- `"1024x1024"`, `"1344x768"`, `"768x1344"`, `"1024x576"`, `"576x1024"`
+
+**For ultra/kontext** (aspect ratios):
+- `"1:1"`, `"16:9"`, `"9:16"`, `"4:3"`, `"3:4"`, `"3:2"`, `"2:3"`, `"21:9"`, `"9:21"`
+
+## Edit Images
+
+Use kontext models for text-guided image editing:
+
+```json
+POST /flux/images
+{
+  "prompt": "change the background to a beach sunset",
+  "action": "edit",
+  "image_url": "https://example.com/photo.jpg",
+  "model": "flux-kontext-pro"
+}
+```
+
+## Gotchas
+
+- Use pixel dimensions (e.g., `"1024x1024"`) with dev/pro models, aspect ratios (e.g., `"16:9"`) with ultra/kontext models
+- Editing requires kontext models (`flux-kontext-pro` or `flux-kontext-max`) — other models only support generation
+- `count` parameter generates multiple images in one request (increases cost proportionally)
+- Ultra model produces highest quality but is slowest — use dev for iteration, ultra for final output
+- All generation is async — always set `"callback_url"` to get a `task_id` immediately, then poll `/flux/tasks`
+
+> **MCP:** `pip install mcp-flux` | Hosted: `https://flux.mcp.acedata.cloud/mcp` | See [all MCP servers](../_shared/mcp-servers.md)