bailian-cli 0.1.2 → 1.0.0-beta.0

package/skill/BAILIAN_API_DOC_REFER.md

@@ -1,21 +1,21 @@
 ---
 name: bailian-api-doc
-description: "DashScope API Documentation Reference — MUST READ when writing ANY code that needs AI/LLM capabilities: text generation, image generation, video generation, speech synthesis, speech recognition, vision understanding, web search, RAG knowledge retrieval, memory, or app orchestration. This is the canonical API reference for integrating Alibaba Cloud Bailian (DashScope) AI services into applications, scripts, backends, or tools. Contains complete API endpoints, request/response schemas, curl examples, authentication (auto-detect local API Key), streaming/async patterns. WHEN TO USE: user is writing code / building an app / creating a service / developing a tool / implementing a feature that involves calling any AI model (LLM, VLM, TTS, ASR, image gen, video gen, etc.). Trigger keywords: 'write code', 'build app', 'integrate API', 'call model', 'HTTP request', 'curl example', 'backend service', 'generate text/image/video/audio programmatically', '接入大模型', '调用API', '写代码调用', '开发应用'."
+description: "DashScope API Documentation Reference — MUST READ when writing ANY code that needs AI/LLM capabilities: text generation, image generation, video generation, speech synthesis, speech recognition, vision understanding, web search, RAG knowledge retrieval, memory, or app orchestration. This is the canonical API reference for integrating Aliyun Model Studio (DashScope) AI services into applications, scripts, backends, or tools. Contains complete API endpoints, request/response schemas, curl examples, authentication (auto-detect local API Key), streaming/async patterns. WHEN TO USE: user is writing code / building an app / creating a service / developing a tool / implementing a feature that involves calling any AI model (LLM, VLM, TTS, ASR, image gen, video gen, etc.). Trigger keywords: 'write code', 'build app', 'integrate API', 'call model', 'HTTP request', 'curl example', 'backend service', 'generate text/image/video/audio programmatically', '接入大模型', '调用API', '写代码调用', '开发应用'."
 ---
 
 # DashScope API Reference — Integration Guide
 
 > **When to use this document**: Whenever you are writing code (in any language) that needs AI capabilities — text generation, image creation, video production, speech synthesis/recognition, vision understanding, web search, RAG, or memory — refer to this document for the correct API endpoints, request formats, and authentication.
 >
-> This is the single source of truth for integrating Alibaba Cloud Bailian (DashScope) AI services into your applications, scripts, backends, and tools.
+> This is the single source of truth for integrating Aliyun Model Studio (DashScope) AI services into your applications, scripts, backends, and tools.
 
 ## Base URL
 
-| Region | Base URL |
-|--------|----------|
-| cn (default) | `https://dashscope.aliyuncs.com` |
-| us | `https://dashscope-us.aliyuncs.com` |
-| intl | `https://dashscope-intl.aliyuncs.com` |
+| Region       | Base URL                              |
+| ------------ | ------------------------------------- |
+| cn (default) | `https://dashscope.aliyuncs.com`      |
+| us           | `https://dashscope-us.aliyuncs.com`   |
+| intl         | `https://dashscope-intl.aliyuncs.com` |
 
 ## Authentication
 
@@ -30,25 +30,29 @@ Authorization: Bearer sk-xxxxxxxxxxxxxxxx
 Before requesting a new key, check if one already exists locally:
 
 **1. Environment Variable (Highest Priority)**
+
 ```bash
 echo $DASHSCOPE_API_KEY
 ```
+
 If set, use it directly.
 
-**2. Bailian CLI Config File**
+**2. Aliyun Model Studio CLI Config File**
+
 ```bash
-# Check if Bailian CLI has saved credentials
+# Check if Aliyun Model Studio CLI has saved credentials
 cat ~/.bailian/config.json | grep api_key
 
 # Or use CLI command
 bl auth status
 ```
+
 If `api_key` exists in `~/.bailian/config.json`, use it directly.
 
 **3. Apply for a New Key**
 
 Only if neither of the above is available, get a new API Key at:
-https://bailian.console.aliyun.com/cn-beijing/?source_channel=aliway&tab=app#/api-key
+https://bailian.console.aliyun.com/cn-beijing/?tab=app#/api-key
 
 #### Quick Integration Snippet
 
@@ -57,7 +61,7 @@ https://bailian.console.aliyun.com/cn-beijing/?source_channel=aliway&tab=app#/ap
 API_KEY="${DASHSCOPE_API_KEY:-$(cat ~/.bailian/config.json 2>/dev/null | grep -o '"api_key":\s*"[^"]*"' | cut -d'"' -f4)}"
 
 if [ -z "$API_KEY" ]; then
-  echo "No API Key found. Get one at: https://bailian.console.aliyun.com/cn-beijing/?source_channel=aliway&tab=app#/api-key"
+  echo "No API Key found. Get one at: https://bailian.console.aliyun.com/cn-beijing/?tab=app#/api-key"
   exit 1
 fi
 
@@ -87,19 +91,20 @@ Authorization: ACS3-HMAC-SHA256 Credential={AccessKeyId},SignedHeaders=host;x-ac
 ```
 
 Typical architecture:
+
 - **Frontend**: Calls your own backend API (e.g., `POST /api/chat`)
 - **Backend**: Forwards request to DashScope API with API Key, returns response to frontend
 - **API Key**: Stored on server only — NEVER expose API Key in frontend code
 
 ## Common Headers
 
-| Header | Value | Description |
-|--------|-------|-------------|
-| `Content-Type` | `application/json` | Required for all JSON requests |
-| `Authorization` | `Bearer sk-xxx` | API Key authentication |
-| `x-dashscope-source-config` | JSON array (see below) | Source tracking / channel identification |
-| `X-DashScope-Async` | `enable` | Enable async mode (returns task_id) |
-| `X-DashScope-OssResourceResolve` | `enable` | Required when using `oss://` URLs |
+| Header                           | Value                  | Description                              |
+| -------------------------------- | ---------------------- | ---------------------------------------- |
+| `Content-Type`                   | `application/json`     | Required for all JSON requests           |
+| `Authorization`                  | `Bearer sk-xxx`        | API Key authentication                   |
+| `x-dashscope-source-config`      | JSON array (see below) | Source tracking / channel identification |
+| `X-DashScope-Async`              | `enable`               | Enable async mode (returns task_id)      |
+| `X-DashScope-OssResourceResolve` | `enable`               | Required when using `oss://` URLs        |
 
 ### x-dashscope-source-config (Required)
 
@@ -112,21 +117,23 @@ x-dashscope-source-config: [{"channel":"bailian-cli","tags":{"t1":"","t2":"publi
 Formatted value:
 
 ```json
-[{
-  "channel": "bailian-cli",
-  "tags": {
-    "t1": "",
-    "t2": "public",
-    "t3": "skill-doc"
+[
+  {
+    "channel": "bailian-cli",
+    "tags": {
+      "t1": "",
+      "t2": "public",
+      "t3": "skill-doc"
+    }
   }
-}]
+]
 ```
 
-| Field | Description |
-|-------|-------------|
-| `channel` | Source channel identifier, fixed as `bailian-cli` |
-| `tags.t1` | Reserved tag |
-| `tags.t2` | Access scope: `public` for external integration |
+| Field     | Description                                              |
+| --------- | -------------------------------------------------------- |
+| `channel` | Source channel identifier, fixed as `bailian-cli`        |
+| `tags.t1` | Reserved tag                                             |
+| `tags.t2` | Access scope: `public` for external integration          |
 | `tags.t3` | Integration source: `skill-doc` indicates API doc driven |
 
 ## Error Response Format
@@ -173,13 +180,15 @@ Fully compatible with OpenAI Chat Completions API format.
 ```json
 {
   "model": "qwen-vl-max",
-  "messages": [{
-    "role": "user",
-    "content": [
-      { "type": "text", "text": "Describe this image" },
-      { "type": "image_url", "image_url": { "url": "https://example.com/photo.jpg" } }
-    ]
-  }]
+  "messages": [
+    {
+      "role": "user",
+      "content": [
+        { "type": "text", "text": "Describe this image" },
+        { "type": "image_url", "image_url": { "url": "https://example.com/photo.jpg" } }
+      ]
+    }
+  ]
 }
 ```
 
@@ -207,16 +216,18 @@ Voices: `Cherry`, `Serena`, `Ethan`, `Chelsie`, `Tina`.
   "id": "chatcmpl-xxx",
   "object": "chat.completion",
   "model": "qwen3.6-plus",
-  "choices": [{
-    "index": 0,
-    "message": {
-      "role": "assistant",
-      "content": "Hello! How can I help you?",
-      "reasoning_content": null,
-      "tool_calls": null
-    },
-    "finish_reason": "stop"
-  }],
+  "choices": [
+    {
+      "index": 0,
+      "message": {
+        "role": "assistant",
+        "content": "Hello! How can I help you?",
+        "reasoning_content": null,
+        "tool_calls": null
+      },
+      "finish_reason": "stop"
+    }
+  ],
   "usage": { "prompt_tokens": 10, "completion_tokens": 20, "total_tokens": 30 }
 }
 ```
@@ -265,10 +276,12 @@ Synchronous generation via `qwen-image-2.0` series.
 {
   "model": "qwen-image-2.0",
   "input": {
-    "messages": [{
-      "role": "user",
-      "content": [{ "text": "A cat in space" }]
-    }]
+    "messages": [
+      {
+        "role": "user",
+        "content": [{ "text": "A cat in space" }]
+      }
+    ]
   },
   "parameters": {
     "size": "1024*1024",
@@ -289,14 +302,16 @@ Size options: `1024*1024`, `720*1280`, `1280*720`, or ratios `1:1`, `3:4`, `4:3`
 {
   "model": "qwen-image-2.0",
   "input": {
-    "messages": [{
-      "role": "user",
-      "content": [
-        { "image": "https://example.com/photo.png" },
-        { "image": "https://example.com/bg.png" },
-        { "text": "Merge these two images" }
-      ]
-    }]
+    "messages": [
+      {
+        "role": "user",
+        "content": [
+          { "image": "https://example.com/photo.png" },
+          { "image": "https://example.com/bg.png" },
+          { "text": "Merge these two images" }
+        ]
+      }
+    ]
   },
   "parameters": { "size": "1024*1024", "n": 1 }
 }
@@ -307,13 +322,17 @@ Size options: `1024*1024`, `720*1280`, `1280*720`, or ratios `1:1`, `3:4`, `4:3`
 ```json
 {
   "output": {
-    "choices": [{
-      "finish_reason": "stop",
-      "message": {
-        "role": "assistant",
-        "content": [{ "image": "https://dashscope-result.oss.aliyuncs.com/xxx.png", "type": "image" }]
+    "choices": [
+      {
+        "finish_reason": "stop",
+        "message": {
+          "role": "assistant",
+          "content": [
+            { "image": "https://dashscope-result.oss.aliyuncs.com/xxx.png", "type": "image" }
+          ]
+        }
       }
-    }],
+    ],
     "finished": true
   },
   "usage": { "image_count": 1 },
@@ -445,6 +464,7 @@ Multi-subject reference-to-video generation with optional voice cloning. Use `
 ```
 
 **Media types**:
+
 - `reference_image` — reference person/object/background image
 - `reference_video` — reference video clip
 - `reference_voice` (optional per media) — voice audio for the subject
@@ -493,6 +513,7 @@ Poll until `task_status` becomes `SUCCEEDED` or `FAILED`. Recommended interval:
 Task statuses: `PENDING` → `RUNNING` → `SUCCEEDED` | `FAILED`.
 
 Result fields vary by task type:
+
 - Video: `output.video_url`
 - Image (async): `output.choices[].message.content[].image`
 - ASR: `output.results[].transcription_url`
@@ -533,7 +554,10 @@ Voices: `Cherry`, `Serena`, `Ethan`, `Chelsie`.
 ```json
 {
   "output": {
-    "audio": { "url": "https://dashscope-result.oss.aliyuncs.com/xxx.wav", "expires_at": "2024-01-02T00:00:00Z" },
+    "audio": {
+      "url": "https://dashscope-result.oss.aliyuncs.com/xxx.wav",
+      "expires_at": "2024-01-02T00:00:00Z"
+    },
     "finish_reason": "stop"
   },
   "usage": {},
@@ -678,20 +702,24 @@ curl -X POST "https://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcrip
     "text": "Response text",
     "finish_reason": "stop",
     "session_id": "session_xxx",
-    "thoughts": [{
-      "thought": "I need to search...",
-      "action_type": "api",
-      "action_name": "search",
-      "action_input": "{}",
-      "response": "",
-      "observation": "Search results..."
-    }],
-    "doc_references": [{
-      "index_id": "idx_xxx",
-      "title": "Doc Title",
-      "doc_id": "doc_xxx",
-      "text": "Relevant text snippet"
-    }]
+    "thoughts": [
+      {
+        "thought": "I need to search...",
+        "action_type": "api",
+        "action_name": "search",
+        "action_input": "{}",
+        "response": "",
+        "observation": "Search results..."
+      }
+    ],
+    "doc_references": [
+      {
+        "index_id": "idx_xxx",
+        "title": "Doc Title",
+        "doc_id": "doc_xxx",
+        "text": "Relevant text snippet"
+      }
+    ]
   },
   "usage": { "models": [{ "model_id": "qwen-plus", "input_tokens": 100, "output_tokens": 50 }] },
   "request_id": "xxx"
@@ -792,7 +820,7 @@ Response: `{ "request_id": "xxx", "memory_nodes": [{ "memory_node_id": "xxx", "c
 
 ## 9. Knowledge Retrieve (AK/SK Required)
 
-**Endpoint**: `POST https://bailian.cn-beijing.aliyuncs.com` (Bailian Cloud API, POP style)
+**Endpoint**: `POST https://bailian.cn-beijing.aliyuncs.com` (Aliyun Model Studio Cloud API, POP style)
 
 Requires AK/SK V3 ROA signing, NOT Bearer token.
 
@@ -813,7 +841,7 @@ x-acs-content-sha256: <sha256 of body>
 ```json
 {
   "IndexId": "idx_xxx",
-  "Query": "如何使用百炼",
+  "Query": "如何使用阿里云百炼",
   "DenseSimilarityTopK": 100,
   "SparseSimilarityTopK": 100,
   "RerankTopN": 5,
@@ -831,11 +859,13 @@ Query parameter: `?WorkspaceId=ws_xxx`
   "Success": true,
   "RequestId": "xxx",
   "Data": {
-    "Nodes": [{
-      "Text": "Relevant knowledge text...",
-      "Score": 0.95,
-      "Metadata": { "doc_name": "guide.pdf", "page": 3 }
-    }]
+    "Nodes": [
+      {
+        "Text": "Relevant knowledge text...",
+        "Score": 0.95,
+        "Metadata": { "doc_name": "guide.pdf", "page": 3 }
+      }
+    ]
   }
 }
 ```
@@ -851,7 +881,12 @@ Uses JSON-RPC 2.0 over Streamable HTTP (MCP protocol).
 ### Step 1: Initialize
 
 ```json
-{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2025-03-26", "capabilities": {} } }
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "initialize",
+  "params": { "protocolVersion": "2025-03-26", "capabilities": {} }
+}
 ```
 
 ### Step 2: Call Tool
@@ -875,10 +910,12 @@ Uses JSON-RPC 2.0 over Streamable HTTP (MCP protocol).
   "jsonrpc": "2.0",
   "id": 2,
   "result": {
-    "content": [{
-      "type": "text",
-      "text": "{ \"results\": [{ \"title\": \"...\", \"url\": \"...\", \"snippet\": \"...\" }] }"
-    }]
+    "content": [
+      {
+        "type": "text",
+        "text": "{ \"results\": [{ \"title\": \"...\", \"url\": \"...\", \"snippet\": \"...\" }] }"
+      }
+    ]
   }
 }
 ```
@@ -951,6 +988,7 @@ curl -X POST "{upload_host}" \
 Result: `oss://{upload_dir}/{filename}`
 
 **Important**: When using `oss://` URLs in subsequent API calls, you MUST include the header:
+
 ```
 X-DashScope-OssResourceResolve: enable
 ```
@@ -959,12 +997,12 @@ X-DashScope-OssResourceResolve: enable
 
 ## Integration Patterns Summary
 
-| Pattern | APIs | Header |
-|---------|------|--------|
-| **Sync Request** | Chat, Image Gen/Edit, TTS, App Call, Memory | Standard |
-| **Async Task** | Video Gen/Edit, ASR (long), Image (legacy) | `X-DashScope-Async: enable` |
-| **Streaming (SSE)** | Chat, TTS, App Call | `stream: true` in body |
-| **Polling** | All async tasks | `GET /api/v1/tasks/{id}` |
-| **File Upload** | Two-step OSS | `X-DashScope-OssResourceResolve: enable` |
-| **MCP Protocol** | WebSearch | JSON-RPC 2.0 + `Mcp-Session-Id` |
-| **AK/SK Signing** | Knowledge Retrieve | ACS3-HMAC-SHA256 |
+| Pattern             | APIs                                        | Header                                   |
+| ------------------- | ------------------------------------------- | ---------------------------------------- |
+| **Sync Request**    | Chat, Image Gen/Edit, TTS, App Call, Memory | Standard                                 |
+| **Async Task**      | Video Gen/Edit, ASR (long), Image (legacy)  | `X-DashScope-Async: enable`              |
+| **Streaming (SSE)** | Chat, TTS, App Call                         | `stream: true` in body                   |
+| **Polling**         | All async tasks                             | `GET /api/v1/tasks/{id}`                 |
+| **File Upload**     | Two-step OSS                                | `X-DashScope-OssResourceResolve: enable` |
+| **MCP Protocol**    | WebSearch                                   | JSON-RPC 2.0 + `Mcp-Session-Id`          |
+| **AK/SK Signing**   | Knowledge Retrieve                          | ACS3-HMAC-SHA256                         |