qwencloud-text

What this skill does

> **Agent setup**: If your agent doesn't auto-load skills (e.g. Claude Code),
> see [agent-compatibility.md](references/agent-compatibility.md) once per session.

# Qwen Text Chat (OpenAI-Compatible)

Generate text, conduct conversations, write code, and invoke tools using Qwen models through the OpenAI-compatible API.
This skill is part of **qwencloud/qwencloud-ai**.

## Skill directory

Use this skill's internal files to execute and learn. Load reference files on demand when the default path fails or you
need details.

| Location                            | Purpose                                                                             |
|-------------------------------------|-------------------------------------------------------------------------------------|
| `scripts/text.py`                   | Default execution — chat/completions request, streaming, output save                |
| `references/execution-guide.md`     | Fallback: curl, Python SDK, function calling, thinking mode                         |
| `references/api-guide.md`           | API supplement and full code examples                                               |
| `references/prompt-guide.md`        | Prompt engineering: CO-STAR framework, CoT, few-shot, task steps                    |
| `references/sources.md`             | Official documentation URLs (manual lookup only)                                    |
| `references/agent-compatibility.md` | Agent self-check: register skills in project config for agents that don't auto-load |

## Security

**NEVER output any API key or credential in plaintext.** Always use variable references (`$DASHSCOPE_API_KEY` in shell,
`os.environ["DASHSCOPE_API_KEY"]` in Python). Any check or detection of credentials must be **non-plaintext**: report
only status (e.g. "set" / "not set", "valid" / "invalid"), never the value. Never display contents of `.env` or config
files that may contain secrets.

**When the API key is not configured, NEVER ask the user to provide it directly.** Instead, help create a `.env` file with a placeholder (`DASHSCOPE_API_KEY=sk-your-key-here`) and instruct the user to replace it with their actual key from the [QwenCloud Console](https://home.qwencloud.com/api-keys). Only write the actual key value if the user explicitly requests it.

## Key Compatibility

Scripts require a **standard QwenCloud API key** (`sk-...`). Coding Plan keys (`sk-sp-...`) cannot be used for direct
API calls — they are designed exclusively for interactive coding tools (Cursor, Claude Code, Qwen Code) and do not work
on QwenCloud API endpoints. The script detects `sk-sp-` keys at startup and prints a warning. If qwencloud-ops-auth is installed,
see its `references/codingplan.md` for details on key types, endpoint mapping, and error codes.

## Model Selection

| Model              | Use Case                                                                |
|--------------------|-------------------------------------------------------------------------|
| `qwen3.6-plus`     | **Recommended default** — latest flagship, balanced performance/cost/speed, 1M context, thinking on by default, multimodal (text+image+video) |
| `qwen3.5-plus`     | Balanced performance, cost, speed, 1M context, thinking on by default   |
| `qwen3.5-flash`    | Fast, low-cost, 1M context                                              |
| `qwen3-max`        | Strongest capability, built-in tools (web search, code interpreter)     |
| `qwen-plus`        | General purpose                                                         |
| `qwen-turbo`       | Cheapest, low latency                                                   |
| `qwen3-coder-next` | **Recommended code model** — best balance of quality, speed, cost; agentic coding |
| `qwen3-coder-plus` | Code generation — highest quality for complex tasks                     |
| `qwen3-coder-flash`| Code generation — fast responses, lower cost                            |
| `qwq-plus`         | Reasoning / chain-of-thought                                            |
| `qwen-mt-plus`     | Machine translation — best quality, 92 languages                        |
| `qwen-mt-flash`    | Machine translation — fast, low cost, 92 languages                      |
| `qwen-mt-lite`     | Machine translation — real-time chat, fastest, 31 languages             |
| `qwen-plus-character-ja` | Role-playing — recommended for Singapore                          |
| `qwen-plus-character`    | Role-playing — character restoration, empathetic dialog             |
| `qwen-flash-character`   | Role-playing — fast, lower cost                                    |

1. **User specified a model** → use directly.
2. **Consult the qwencloud-model-selector skill** when model choice depends on requirement, scenario, or pricing.
3. **No signal, clear task** → `qwen3.6-plus` (default).

> Fallback: if model-selector is unavailable, the defaults in the table above apply.

> **⚠️ Important**: The model list above is a **point-in-time snapshot** and may be outdated. Model availability
> changes frequently. **Always check the [official model list](https://www.qwencloud.com/models)
> for the authoritative, up-to-date catalog before making model decisions.**

> **Model details**: For more information about a specific model, direct the user to its detail page: `https://www.qwencloud.com/models/<model-name>` (replace `<model-name>` with the exact model ID, e.g. `qwen3.6-plus` → https://www.qwencloud.com/models/qwen3.6-plus). NEVER modify or guess the model name in the URL.

> **Dynamic model queries**: If the **qwencloud-model-selector** skill or **QwenCloud CLI** (`qwencloud models info <model>`) is available, use it for real-time model data. CLI requires authentication — see the **qwencloud-usage** skill for login flow.

## Execution

### Prerequisites

- **API Key**: Check that `DASHSCOPE_API_KEY` (or `QWEN_API_KEY`) is set using a **non-plaintext** check only (e.g. in shell:
  `[ -n "$DASHSCOPE_API_KEY" ]`; report only "set" or "not set", never the key value). If not set: run the *
  *qwencloud-ops-auth** skill if available; otherwise guide the user to obtain a key from [QwenCloud Console](https://home.qwencloud.com/api-keys) and set it via `.env` file
  (`echo 'DASHSCOPE_API_KEY=sk-your-key-here' >> .env` in project root or current directory) or environment variable.
  The script searches for `.env` in the current working directory and the project root. Skills may be installed independently — do
  not assume qwencloud-ops-auth is present.
- Python 3.9+ (stdlib only, **no pip install needed** for script execution)

### Environment Check

Before first execution, verify Python is available:

```bash
python3 --version  # must be 3.9+
```

If `python3` is not found, try `python --version` or `py -3 --version`. If Python is unavailable or below 3.9, skip to *
*Path 2 (curl)** in [execution-guide.md](references/execution-guide.md).

### Default: Run Script

**Script path**: Scripts are in the `scripts/` subdirectory **of this skill's directory** (the directory containing this
SKILL.md). **You MUST first locate this skill's installation directory, then ALWAYS use the full absolute path to execute
scripts.** Do NOT assume scripts are in the current working directory. Do NOT use `cd` to switch directories before
execution.

**Execution note:** Run all scripts in the **foreground** — wait for stdout; do not background.

**Discovery:** Run `python3 <this-skill-dir>/scripts/text.py --help` first to see all available arguments.

```bash
python3 <this-skill-dir>/scripts/text.py \
  --request '{"messages":[{"role":"user","content":"Hello!"}],"model":"qwen3.6-plus"}' \
  --output output/qwencloud-text/ --print-response
```

For streaming (recommended for interactive use):

```bash
python3 <this-skill-dir>/scripts/text.py \
  --request '{"messages":[{"role":"user","content":"Write a poem about the sea"}],"model":"qwen3.6-plus"}' \
  --stream --print-response
```

| Argument