bailian-cli 0.1.2 → 1.0.0

package/skill/BAILIAN_API_DOC_REFER.md

@@ -1,970 +0,0 @@
----
-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', '写代码调用', '开发应用'."
----
-
-# 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.
-
-## Base URL
-
-| Region | Base URL |
-|--------|----------|
-| cn (default) | `https://dashscope.aliyuncs.com` |
-| us | `https://dashscope-us.aliyuncs.com` |
-| intl | `https://dashscope-intl.aliyuncs.com` |
-
-## Authentication
-
-### Method 1: API Key (Bearer Token)
-
-```
-Authorization: Bearer sk-xxxxxxxxxxxxxxxx
-```
-
-#### Obtaining API Key (Priority Order)
-
-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**
-```bash
-# Check if Bailian 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
-
-#### Quick Integration Snippet
-
-```bash
-# Auto-detect: env var → config file → prompt user
-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"
-  exit 1
-fi
-
-# Use in requests
-curl -H "Authorization: Bearer $API_KEY" ...
-```
-
-### Method 2: AK/SK Signing (Alibaba Cloud V3 ROA)
-
-Required for Knowledge Retrieve API. Uses `Authorization` header with HMAC-SHA256 signature:
-
-```
-Authorization: ACS3-HMAC-SHA256 Credential={AccessKeyId},SignedHeaders=host;x-acs-action;x-acs-content-sha256;x-acs-date;x-acs-signature-nonce;x-acs-version,Signature={signature}
-```
-
-## Important: Server-Side Calls Required
-
-> **DashScope API does NOT support direct calls from browser-side (frontend) JavaScript.** The API does not provide CORS headers, so `fetch()` or `XMLHttpRequest` from a web page will be blocked by the browser's same-origin policy.
->
-> You MUST build a **server-side** backend (Node.js, Python, Java, Go, etc.) to call DashScope API, then expose your own endpoints for the frontend to consume.
-
-```
-┌──────────┐     ┌──────────────┐     ┌───────────────┐
-│ Frontend │ ──► │ Your Backend │ ──► │ DashScope API │
-│ (Browser)│ ◄── │ (Server)     │ ◄── │               │
-└──────────┘     └──────────────┘     └───────────────┘
-```
-
-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 |
-
-### x-dashscope-source-config (Required)
-
-All requests MUST include this header for source tracking:
-
-```
-x-dashscope-source-config: [{"channel":"bailian-cli","tags":{"t1":"","t2":"public","t3":"skill-doc"}}]
-```
-
-Formatted value:
-
-```json
-[{
-  "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 |
-| `tags.t3` | Integration source: `skill-doc` indicates API doc driven |
-
-## Error Response Format
-
-```json
-{
-  "code": "ErrorCode",
-  "message": "Human-readable error message",
-  "request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
-}
-```
-
-Common error codes: `InvalidApiKey`, `AccessDenied`, `Throttling`, `InvalidParameter`, `ModelNotFound`.
-
----
-
-## 1. Chat Completions (OpenAI Compatible)
-
-**Endpoint**: `POST {baseUrl}/compatible-mode/v1/chat/completions`
-
-Fully compatible with OpenAI Chat Completions API format.
-
-### Request Body
-
-```json
-{
-  "model": "qwen3.6-plus",
-  "messages": [
-    { "role": "system", "content": "You are a helpful assistant." },
-    { "role": "user", "content": "Hello" }
-  ],
-  "max_tokens": 2048,
-  "temperature": 0.7,
-  "top_p": 0.9,
-  "stream": false,
-  "tools": [],
-  "enable_thinking": false,
-  "thinking_budget": 4096
-}
-```
-
-### Multimodal Messages (Vision / Audio / Video)
-
-```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" } }
-    ]
-  }]
-}
-```
-
-Content types: `text`, `image_url`, `audio_url`, `input_audio` (base64), `video` (frame URLs array).
-
-### Omni Multimodal (Text + Audio Output)
-
-```json
-{
-  "model": "qwen3.5-omni-plus",
-  "messages": [{ "role": "user", "content": "你好" }],
-  "modalities": ["text", "audio"],
-  "audio": { "voice": "Cherry", "format": "wav" },
-  "stream": true,
-  "stream_options": { "include_usage": true }
-}
-```
-
-Voices: `Cherry`, `Serena`, `Ethan`, `Chelsie`, `Tina`.
-
-### Response (Non-streaming)
-
-```json
-{
-  "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"
-  }],
-  "usage": { "prompt_tokens": 10, "completion_tokens": 20, "total_tokens": 30 }
-}
-```
-
-### Streaming (SSE)
-
-```
-data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}
-
-data: [DONE]
-```
-
-Audio chunks in streaming: `choices[0].delta.audio.data` (base64 PCM).
-
-### curl Example
-
-```bash
-curl -X POST "https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions" \
-  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-  -H "Content-Type: application/json" \
-  -H 'x-dashscope-source-config: [{"channel":"bailian-cli","tags":{"t1":"","t2":"public","t3":"skill-doc"}}]' \
-  -d '{
-    "model": "qwen3.6-plus",
-    "messages": [{"role": "user", "content": "Hello"}],
-    "stream": false
-  }'
-```
-
-### Available Models
-
-- Text: `qwen3.6-plus`, `qwen-plus`, `qwen-turbo`, `qwen-max`, `qwq-plus`
-- Vision: `qwen-vl-max`, `qwen-vl-plus`
-- Omni: `qwen3.5-omni-plus`
-
----
-
-## 2. Image Generation (Sync)
-
-**Endpoint**: `POST {baseUrl}/api/v1/services/aigc/multimodal-generation/generation`
-
-Synchronous generation via `qwen-image-2.0` series.
-
-### Request Body
-
-```json
-{
-  "model": "qwen-image-2.0",
-  "input": {
-    "messages": [{
-      "role": "user",
-      "content": [{ "text": "A cat in space" }]
-    }]
-  },
-  "parameters": {
-    "size": "1024*1024",
-    "n": 1,
-    "seed": 42,
-    "negative_prompt": "blurry, low quality",
-    "prompt_extend": true,
-    "watermark": false
-  }
-}
-```
-
-Size options: `1024*1024`, `720*1280`, `1280*720`, or ratios `1:1`, `3:4`, `4:3`, `9:16`, `16:9`.
-
-### Image Edit (Multi-image Input)
-
-```json
-{
-  "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" }
-      ]
-    }]
-  },
-  "parameters": { "size": "1024*1024", "n": 1 }
-}
-```
-
-### Response
-
-```json
-{
-  "output": {
-    "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 },
-  "request_id": "xxx"
-}
-```
-
-### curl Example
-
-```bash
-curl -X POST "https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation" \
-  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-  -H "Content-Type: application/json" \
-  -H "X-DashScope-OssResourceResolve: enable" \
-  -H 'x-dashscope-source-config: [{"channel":"bailian-cli","tags":{"t1":"","t2":"public","t3":"skill-doc"}}]' \
-  -d '{
-    "model": "qwen-image-2.0",
-    "input": { "messages": [{ "role": "user", "content": [{ "text": "A sunset over mountains" }] }] },
-    "parameters": { "size": "1024*1024", "n": 1 }
-  }'
-```
-
----
-
-## 3. Video Generation (Async)
-
-**Endpoint**: `POST {baseUrl}/api/v1/services/aigc/video-generation/video-synthesis`
-
-Async operation — returns `task_id`, requires polling.
-
-### Request Headers
-
-```
-Authorization: Bearer sk-xxx
-Content-Type: application/json
-X-DashScope-Async: enable
-```
-
-### Request Body (Text-to-Video)
-
-```json
-{
-  "model": "happyhorse-1.0-t2v",
-  "input": {
-    "prompt": "Sunset on the beach, cinematic",
-    "negative_prompt": "blurry, low quality"
-  },
-  "parameters": {
-    "resolution": "720P",
-    "duration": 5,
-    "prompt_extend": true,
-    "seed": 42
-  }
-}
-```
-
-### Request Body (Image-to-Video)
-
-```json
-{
-  "model": "happyhorse-1.0-i2v",
-  "input": {
-    "prompt": "The girl smiles and blinks",
-    "img_url": "https://example.com/girl.png"
-  },
-  "parameters": { "resolution": "720P", "duration": 5 }
-}
-```
-
-### Video Edit Request
-
-```json
-{
-  "model": "happyhorse-1.0-video-edit",
-  "input": {
-    "prompt": "Convert to clay style",
-    "media": [
-      { "type": "video", "url": "https://example.com/input.mp4" },
-      { "type": "reference_image", "url": "https://example.com/ref.png" }
-    ]
-  },
-  "parameters": {
-    "resolution": "1080P",
-    "duration": 5,
-    "audio_setting": "auto",
-    "prompt_extend": true
-  }
-}
-```
-
-### Video Reference Request (Reference-to-Video)
-
-Multi-subject reference-to-video generation with optional voice cloning. Use `图N` / `视频N` markers in prompt to reference specific media inputs.
-
-```json
-{
-  "model": "happyhorse-1.0-r2v",
-  "input": {
-    "prompt": "视频1抱着图2，在图3的椅子上弹吉他",
-    "media": [
-      {
-        "type": "reference_image",
-        "url": "https://example.com/person.jpg",
-        "reference_voice": "https://example.com/voice.mp3"
-      },
-      {
-        "type": "reference_video",
-        "url": "https://example.com/scene.mp4",
-        "reference_voice": "https://example.com/voice2.mp3"
-      },
-      {
-        "type": "reference_image",
-        "url": "https://example.com/guitar.png"
-      },
-      {
-        "type": "reference_image",
-        "url": "https://example.com/bg.png"
-      }
-    ]
-  },
-  "parameters": {
-    "resolution": "720P",
-    "ratio": "16:9",
-    "duration": 10,
-    "prompt_extend": false,
-    "watermark": true
-  }
-}
-```
-
-**Media types**:
-- `reference_image` — reference person/object/background image
-- `reference_video` — reference video clip
-- `reference_voice` (optional per media) — voice audio for the subject
-
-### Async Response
-
-```json
-{
-  "output": { "task_id": "abc-123-def", "task_status": "PENDING" },
-  "request_id": "xxx"
-}
-```
-
-### Available Models
-
-- Text-to-Video: `happyhorse-1.0-t2v`
-- Image-to-Video: `happyhorse-1.0-i2v`
-- Video Edit: `happyhorse-1.0-video-edit`
-- Reference-to-Video: `happyhorse-1.0-r2v` (recommended), `wan2.6-r2v`, `wan2.6-r2v-flash`
-
----
-
-## 4. Async Task Polling
-
-**Endpoint**: `GET {baseUrl}/api/v1/tasks/{task_id}`
-
-Poll until `task_status` becomes `SUCCEEDED` or `FAILED`. Recommended interval: 5-15 seconds.
-
-### Response
-
-```json
-{
-  "output": {
-    "task_id": "abc-123-def",
-    "task_status": "SUCCEEDED",
-    "video_url": "https://dashscope-result.oss.aliyuncs.com/xxx.mp4",
-    "task_metrics": { "TOTAL": 1, "SUCCEEDED": 1, "FAILED": 0 },
-    "submit_time": "2024-01-01T00:00:00Z",
-    "end_time": "2024-01-01T00:01:00Z"
-  },
-  "usage": {},
-  "request_id": "xxx"
-}
-```
-
-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`
-
-### curl Example
-
-```bash
-curl "https://dashscope.aliyuncs.com/api/v1/tasks/abc-123-def" \
-  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-  -H 'x-dashscope-source-config: [{"channel":"bailian-cli","tags":{"t1":"","t2":"public","t3":"skill-doc"}}]'
-```
-
----
-
-## 5. Speech Synthesis (TTS)
-
-**Endpoint**: `POST {baseUrl}/api/v1/services/aigc/multimodal-generation/generation`
-
-### Request Body
-
-```json
-{
-  "model": "qwen3-tts-flash",
-  "input": {
-    "text": "你好，我是千问",
-    "voice": "Cherry",
-    "language_type": "Chinese",
-    "instructions": "语速较慢，温柔的语调",
-    "optimize_instructions": true
-  }
-}
-```
-
-Voices: `Cherry`, `Serena`, `Ethan`, `Chelsie`.
-
-### Response (Non-streaming)
-
-```json
-{
-  "output": {
-    "audio": { "url": "https://dashscope-result.oss.aliyuncs.com/xxx.wav", "expires_at": "2024-01-02T00:00:00Z" },
-    "finish_reason": "stop"
-  },
-  "usage": {},
-  "request_id": "xxx"
-}
-```
-
-### Streaming Mode
-
-Add header `X-DashScope-SSE: enable`. Each SSE chunk contains base64 audio data:
-
-```json
-{
-  "output": {
-    "audio": { "data": "base64_pcm_data..." },
-    "finish_reason": null
-  }
-}
-```
-
-### curl Example
-
-```bash
-curl -X POST "https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation" \
-  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-  -H "Content-Type: application/json" \
-  -H 'x-dashscope-source-config: [{"channel":"bailian-cli","tags":{"t1":"","t2":"public","t3":"skill-doc"}}]' \
-  -d '{
-    "model": "qwen3-tts-flash",
-    "input": { "text": "Hello world", "voice": "Cherry" }
-  }'
-```
-
-### Available Models
-
-- `qwen3-tts-flash` — Fast TTS
-- `qwen3-tts-instruct-flash` — Supports instruction-based style control
-
----
-
-## 6. Speech Recognition (ASR)
-
-**Endpoint**: `POST {baseUrl}/api/v1/services/audio/asr/transcription`
-
-Always uses async mode. Add header `X-DashScope-Async: enable`.
-
-### Request Body
-
-```json
-{
-  "model": "fun-asr",
-  "input": { "file_urls": ["https://example.com/audio.wav"] },
-  "parameters": {
-    "channel_id": [0],
-    "language_hints": ["zh"],
-    "diarization_enabled": false,
-    "speaker_count": 2,
-    "vocabulary_id": "vocab-abc123"
-  }
-}
-```
-
-Supports up to 100 URLs per request (`file_urls` array).
-
-### Response (Task Submission)
-
-```json
-{
-  "output": { "task_id": "xxx", "task_status": "PENDING" },
-  "request_id": "xxx"
-}
-```
-
-### Response (Task Poll — SUCCEEDED)
-
-```json
-{
-  "output": {
-    "task_id": "xxx",
-    "task_status": "SUCCEEDED",
-    "results": [
-      {
-        "file_url": "https://example.com/audio.wav",
-        "transcription_url": "https://...",
-        "subtask_status": "SUCCEEDED"
-      }
-    ],
-    "task_metrics": { "TOTAL": 1, "SUCCEEDED": 1, "FAILED": 0 }
-  },
-  "request_id": "xxx"
-}
-```
-
-### curl Example
-
-```bash
-curl -X POST "https://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcription" \
-  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-  -H "Content-Type: application/json" \
-  -H "X-DashScope-Async: enable" \
-  -H 'x-dashscope-source-config: [{"channel":"bailian-cli","tags":{"t1":"","t2":"public","t3":"skill-doc"}}]' \
-  -d '{
-    "model": "fun-asr",
-    "input": { "file_urls": ["https://example.com/audio.wav"] },
-    "parameters": { "language_hints": ["zh"] }
-  }'
-```
-
----
-
-## 7. Application Call (Agent / Workflow)
-
-**Endpoint**: `POST {baseUrl}/api/v1/apps/{app_id}/completion`
-
-### Request Body
-
-```json
-{
-  "input": {
-    "prompt": "你好",
-    "session_id": "session_xxx",
-    "image_list": ["https://example.com/photo.png"],
-    "file_ids": ["file_xxx"],
-    "biz_params": { "key": "value" }
-  },
-  "parameters": {
-    "has_thoughts": true,
-    "incremental_output": true,
-    "rag_options": {
-      "pipeline_ids": ["pipe_1", "pipe_2"]
-    },
-    "memory_id": "mem_xxx"
-  }
-}
-```
-
-### Response
-
-```json
-{
-  "output": {
-    "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"
-    }]
-  },
-  "usage": { "models": [{ "model_id": "qwen-plus", "input_tokens": 100, "output_tokens": 50 }] },
-  "request_id": "xxx"
-}
-```
-
-### Streaming
-
-Use SSE. Each chunk has the same structure with incremental `output.text`.
-
-### curl Example
-
-```bash
-curl -X POST "https://dashscope.aliyuncs.com/api/v1/apps/YOUR_APP_ID/completion" \
-  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-  -H "Content-Type: application/json" \
-  -H 'x-dashscope-source-config: [{"channel":"bailian-cli","tags":{"t1":"","t2":"public","t3":"skill-doc"}}]' \
-  -d '{
-    "input": { "prompt": "Hello" },
-    "parameters": { "incremental_output": true }
-  }'
-```
-
----
-
-## 8. Memory API
-
-### 8.1 Add Memory
-
-**Endpoint**: `POST {baseUrl}/api/v2/apps/memory/add`
-
-```json
-{
-  "user_id": "user_001",
-  "messages": [
-    { "role": "user", "content": "我喜欢Python编程" },
-    { "role": "assistant", "content": "好的，已记录" }
-  ],
-  "custom_content": "用户喜欢Python编程",
-  "profile_schema": "schema_xxx",
-  "memory_library_id": "lib_xxx"
-}
-```
-
-Response: `{ "request_id": "xxx", "memory_ids": ["mem_001"] }`
-
-### 8.2 Search Memory
-
-**Endpoint**: `POST {baseUrl}/api/v2/apps/memory/memory_nodes/search`
-
-```json
-{
-  "user_id": "user_001",
-  "query": "编程偏好",
-  "top_k": 10,
-  "memory_library_id": "lib_xxx"
-}
-```
-
-Response: `{ "request_id": "xxx", "memory_nodes": [{ "memory_node_id": "xxx", "content": "...", "created_at": "..." }] }`
-
-### 8.3 List Memory Nodes
-
-**Endpoint**: `GET {baseUrl}/api/v2/apps/memory/memory_nodes?user_id=user_001&page_size=10&page_num=1`
-
-### 8.4 Update Memory Node
-
-**Endpoint**: `PUT {baseUrl}/api/v2/apps/memory/memory_nodes/{node_id}`
-
-```json
-{ "user_id": "user_001", "custom_content": "Updated content" }
-```
-
-### 8.5 Delete Memory Node
-
-**Endpoint**: `DELETE {baseUrl}/api/v2/apps/memory/memory_nodes/{node_id}?user_id=user_001`
-
-### 8.6 Profile Schema — Create
-
-**Endpoint**: `POST {baseUrl}/api/v2/apps/memory/profile_schemas`
-
-```json
-{
-  "name": "user_basic",
-  "description": "Basic user profile",
-  "attributes": [
-    { "name": "age", "description": "年龄" },
-    { "name": "hobby", "description": "爱好" }
-  ]
-}
-```
-
-### 8.7 Profile — Get User Profile
-
-**Endpoint**: `GET {baseUrl}/api/v2/apps/memory/profile_schemas/{schema_id}/profiles?user_id=user_001`
-
----
-
-## 9. Knowledge Retrieve (AK/SK Required)
-
-**Endpoint**: `POST https://bailian.cn-beijing.aliyuncs.com` (Bailian Cloud API, POP style)
-
-Requires AK/SK V3 ROA signing, NOT Bearer token.
-
-### Required Headers
-
-```
-x-acs-action: Retrieve
-x-acs-version: 2023-12-29
-Content-Type: application/json
-Authorization: ACS3-HMAC-SHA256 Credential=...
-x-acs-date: 2024-01-01T00:00:00Z
-x-acs-signature-nonce: <uuid>
-x-acs-content-sha256: <sha256 of body>
-```
-
-### Request Body
-
-```json
-{
-  "IndexId": "idx_xxx",
-  "Query": "如何使用百炼",
-  "DenseSimilarityTopK": 100,
-  "SparseSimilarityTopK": 100,
-  "RerankTopN": 5,
-  "Rerank": true,
-  "TopK": 10
-}
-```
-
-Query parameter: `?WorkspaceId=ws_xxx`
-
-### Response
-
-```json
-{
-  "Success": true,
-  "RequestId": "xxx",
-  "Data": {
-    "Nodes": [{
-      "Text": "Relevant knowledge text...",
-      "Score": 0.95,
-      "Metadata": { "doc_name": "guide.pdf", "page": 3 }
-    }]
-  }
-}
-```
-
----
-
-## 10. MCP WebSearch
-
-**Endpoint**: `POST {baseUrl}/api/v1/mcps/WebSearch/mcp`
-
-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": {} } }
-```
-
-### Step 2: Call Tool
-
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 2,
-  "method": "tools/call",
-  "params": {
-    "name": "web-search_search-news",
-    "arguments": { "query": "阿里云百炼最新功能", "count": 10 }
-  }
-}
-```
-
-### Response
-
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 2,
-  "result": {
-    "content": [{
-      "type": "text",
-      "text": "{ \"results\": [{ \"title\": \"...\", \"url\": \"...\", \"snippet\": \"...\" }] }"
-    }]
-  }
-}
-```
-
-Note: Each request must include the `Mcp-Session-Id` header returned from the initialize response.
-
-### curl Example
-
-```bash
-# Initialize
-curl -X POST "https://dashscope.aliyuncs.com/api/v1/mcps/WebSearch/mcp" \
-  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-  -H "Content-Type: application/json" \
-  -H 'x-dashscope-source-config: [{"channel":"bailian-cli","tags":{"t1":"","t2":"public","t3":"skill-doc"}}]' \
-  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{}}}'
-
-# Search (use Mcp-Session-Id from init response)
-curl -X POST "https://dashscope.aliyuncs.com/api/v1/mcps/WebSearch/mcp" \
-  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-  -H "Content-Type: application/json" \
-  -H "Mcp-Session-Id: SESSION_ID" \
-  -H 'x-dashscope-source-config: [{"channel":"bailian-cli","tags":{"t1":"","t2":"public","t3":"skill-doc"}}]' \
-  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"web-search_search-news","arguments":{"query":"latest AI news","count":5}}}'
-```
-
----
-
-## 11. File Upload (Two-step OSS)
-
-Upload local files to DashScope temporary storage. Returns `oss://` URL valid for 48 hours.
-
-### Step 1: Get Upload Policy
-
-```bash
-GET https://dashscope.aliyuncs.com/api/v1/uploads?action=getPolicy&model={model}
-Authorization: Bearer sk-xxx
-x-dashscope-source-config: [{"channel":"bailian-cli","tags":{"t1":"","t2":"public","t3":"skill-doc"}}]
-```
-
-Response:
-
-```json
-{
-  "data": {
-    "upload_host": "https://xxx.oss-cn-beijing.aliyuncs.com",
-    "upload_dir": "tmp/xxx",
-    "oss_access_key_id": "STS.xxx",
-    "signature": "xxx",
-    "policy": "base64...",
-    "x_oss_object_acl": "private",
-    "x_oss_forbid_overwrite": "true"
-  }
-}
-```
-
-### Step 2: Upload to OSS (multipart/form-data)
-
-```bash
-curl -X POST "{upload_host}" \
-  -F "OSSAccessKeyId={oss_access_key_id}" \
-  -F "Signature={signature}" \
-  -F "policy={policy}" \
-  -F "x-oss-object-acl={x_oss_object_acl}" \
-  -F "x-oss-forbid-overwrite={x_oss_forbid_overwrite}" \
-  -F "key={upload_dir}/{filename}" \
-  -F "success_action_status=200" \
-  -F "file=@/path/to/local/file.png"
-```
-
-Result: `oss://{upload_dir}/{filename}`
-
-**Important**: When using `oss://` URLs in subsequent API calls, you MUST include the header:
-```
-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 |