241 lines
10 KiB
Markdown
241 lines
10 KiB
Markdown
# sn-image-base
|
|
|
|
The skill for the [SenseNova-Skills](https://github.com/OpenSenseNova/SenseNova-Skills) project, providing low-level APIs for image generation, recognition (VLM), and text optimization (LLM).
|
|
|
|
See [SKILL.md](SKILL.md) for full behavior.
|
|
|
|
This document describes detailed configurations for the skill.
|
|
|
|
For installation and usage, please refer to the project's [README.md](https://github.com/OpenSenseNova/SenseNova-Skills/blob/main/README.md).
|
|
|
|
## Overview
|
|
|
|
The skill provides the following subcommands:
|
|
|
|
- `sn-image-generate`: image generation
|
|
- `sn-image-recognize`: image recognition (VLM)
|
|
- `sn-text-optimize`: text optimization (LLM)
|
|
|
|
The skill supports the following models services:
|
|
|
|
- For image generation:
|
|
- [SenseNova](https://platform.sensenova.cn/)
|
|
- Nano Banana API
|
|
- OpenAI Image Generation API (e.g. GPT-Image-2)
|
|
|
|
- For text and vision chat:
|
|
- [SenseNova](https://platform.sensenova.cn/)
|
|
- Models via Anthropic Messages API (e.g. Claude Sonnet 4.6)
|
|
- Models via OpenAI Chat Completion API (e.g. GPT and Gemini/Qwen etc. in OpenAI Compatible API format)
|
|
|
|
## Configurations
|
|
|
|
### Quick Start
|
|
|
|
We recommend you to try out our [SenseNova Token Plan](https://platform.sensenova.cn/token-plan).
|
|
|
|
Go to <https://platform.sensenova.cn/token-plan/> to register a free account and get your API key for image generation and chat calls.
|
|
|
|
Set the following environment variables in `~/.openclaw/.env` (or `~/.hermes/.env` if you are using Hermes):
|
|
|
|
```ini
|
|
# If all capabilities use the same gateway, these two variables are enough.
|
|
SN_BASE_URL="https://token.sensenova.cn/v1"
|
|
SN_API_KEY="<sensenova-token-plan-api-key>"
|
|
|
|
# Optional model overrides
|
|
SN_IMAGE_GEN_MODEL="sensenova-u1-fast" # or other image generation models available in the SenseNova Token Plan
|
|
SN_CHAT_MODEL="sensenova-6.7-flash-lite"
|
|
```
|
|
|
|
### Detailed Configurations
|
|
|
|
With the [Quick Start](#quick-start), you can already use this skill.
|
|
|
|
If you want to configure the skill more (i.e. use different models, change the base URL, etc.), you can see the following configurations.
|
|
|
|
Multiple sources of configuration are supported, the priority is (high to low):
|
|
|
|
- (Recommended) `~/.openclaw/.env` (for OpenClaw) or `~/.hermes/.env` (for Hermes)
|
|
- current working directory `.env` (not necessarily exists, depends on how the agent runs the skill)
|
|
- process environment variables
|
|
|
|
> For experienced developers, see [configs.py](scripts/sn_image_base/configs.py) for the full list of variables and defaults.
|
|
>
|
|
> Helpful symbols for tracing behavior quickly:
|
|
>
|
|
> - `prepare_env()` for `.env` loading order
|
|
> - `Field.resolve()` for env-var fallback order ("first set value wins")
|
|
> - `Configs` for all defaults and env-name mapping
|
|
|
|
#### Image Generation
|
|
|
|
Environment variables are resolved as: dedicated variable > domain shared variable > global variable.
|
|
|
|
| Capability | API key fallback | Base URL fallback |
|
|
| ---------- | ---------------- | ----------------- |
|
|
| Text model | `SN_TEXT_API_KEY` -> `SN_CHAT_API_KEY` -> `SN_API_KEY` | `SN_TEXT_BASE_URL` -> `SN_CHAT_BASE_URL` -> `SN_BASE_URL` |
|
|
| Vision model | `SN_VISION_API_KEY` -> `SN_CHAT_API_KEY` -> `SN_API_KEY` | `SN_VISION_BASE_URL` -> `SN_CHAT_BASE_URL` -> `SN_BASE_URL` |
|
|
| Image generation | `SN_IMAGE_GEN_API_KEY` -> `SN_API_KEY` | `SN_IMAGE_GEN_BASE_URL` -> `SN_BASE_URL` |
|
|
|
|
Full configuration for image generation:
|
|
|
|
| Config Key | Description | Default |
|
|
| ---------- | ----------- | ------- |
|
|
| `SN_API_KEY` | Global API key used when capability-specific keys are unset | `""` |
|
|
| `SN_BASE_URL` | Global base URL used when capability-specific base URLs are unset | `""` |
|
|
| `SN_IMAGE_GEN_API_KEY` | Optional image-generation-only API key override | `SN_API_KEY` |
|
|
| `SN_IMAGE_GEN_MODEL_TYPE` | The type of image generation model to use | `"sensenova"` |
|
|
| `SN_IMAGE_GEN_MODEL` | The name of the image generation model to use | `"sensenova-u1-fast"` |
|
|
| `SN_IMAGE_GEN_BASE_URL` | The base URL for the image generation API | `SN_BASE_URL`, then `"https://token.sensenova.cn/v1"` |
|
|
|
|
The default values are recommended for the [SenseNova](https://platform.sensenova.cn/).
|
|
|
|
When all capabilities use one gateway, set only `SN_BASE_URL` and `SN_API_KEY`.
|
|
Set `SN_IMAGE_GEN_*` only when image generation needs a different provider.
|
|
|
|
To use non-default image generation models, please:
|
|
|
|
1. Set `SN_IMAGE_GEN_MODEL_TYPE` according to the model type, available values are:
|
|
|
|
```ini
|
|
# (Default) For [SenseNova](https://platform.sensenova.cn/)
|
|
SN_IMAGE_GEN_MODEL_TYPE="sensenova"
|
|
# For Google's Nano Banana model API
|
|
SN_IMAGE_GEN_MODEL_TYPE="nano-banana"
|
|
# For OpenAI's image generation API
|
|
SN_IMAGE_GEN_MODEL_TYPE="openai-image"
|
|
```
|
|
|
|
2. Set `SN_IMAGE_GEN_BASE_URL` to the base URL for the image generation API. For example:
|
|
|
|
```ini
|
|
# (Default) For [SenseNova](https://platform.sensenova.cn/)
|
|
SN_IMAGE_GEN_BASE_URL="https://token.sensenova.cn/v1"
|
|
# For Google's Nano Banana model API
|
|
SN_IMAGE_GEN_BASE_URL="https://generativelanguage.googleapis.com"
|
|
# For OpenAI's image generation API
|
|
SN_IMAGE_GEN_BASE_URL="https://api.openai.com/v1"
|
|
```
|
|
|
|
3. Set `SN_IMAGE_GEN_MODEL` to the model name provided by the model type. For example:
|
|
|
|
```ini
|
|
# (Default) For [SenseNova](https://platform.sensenova.cn/)
|
|
SN_IMAGE_GEN_MODEL="sensenova-u1-fast"
|
|
# For Google's Nano Banana model API
|
|
SN_IMAGE_GEN_MODEL="gemini-3.1-flash-image-preview"
|
|
# For OpenAI's image generation API
|
|
SN_IMAGE_GEN_MODEL="gpt-image-2"
|
|
```
|
|
|
|
4. If image generation uses a different key than the global key, set `SN_IMAGE_GEN_API_KEY`. If `SN_API_KEY` already works for image generation, skip this.
|
|
|
|
```ini
|
|
SN_IMAGE_GEN_API_KEY="sk-your-image-generation-api-key"
|
|
```
|
|
|
|
#### Text and Vision Chat
|
|
|
|
##### Configure the shared chat runtime
|
|
|
|
Text optimization and image recognition now share one chat runtime. Configure the
|
|
protocol, endpoint, API key, and default model once, then override text or vision
|
|
models only when needed:
|
|
|
|
| Config Keys | Description | Default |
|
|
| ----------- | ----------- | ------- |
|
|
| `SN_CHAT_API_KEY` | API key for text and vision chat calls | `SN_API_KEY` |
|
|
| `SN_CHAT_BASE_URL` | Shared base URL for the chat API | `SN_BASE_URL`, then `"https://token.sensenova.cn/v1"` |
|
|
| `SN_CHAT_TYPE` | Shared chat protocol type | `"openai-completions"` |
|
|
| `SN_CHAT_MODEL` | Shared default model for text and vision chat calls | `"sensenova-6.7-flash-lite"` |
|
|
| `SN_TEXT_API_KEY` | Optional text-only provider API key | `SN_CHAT_API_KEY` -> `SN_API_KEY` |
|
|
| `SN_TEXT_BASE_URL` | Optional text-only provider base URL | `SN_CHAT_BASE_URL` -> `SN_BASE_URL` |
|
|
| `SN_TEXT_TYPE` | Optional text-only protocol type | `SN_CHAT_TYPE` |
|
|
| `SN_TEXT_MODEL` | Optional model override for `sn-text-optimize` | `SN_CHAT_MODEL` |
|
|
| `SN_VISION_API_KEY` | Optional vision provider API key | `SN_CHAT_API_KEY` -> `SN_API_KEY` |
|
|
| `SN_VISION_BASE_URL` | Optional vision provider base URL | `SN_CHAT_BASE_URL` -> `SN_BASE_URL` |
|
|
| `SN_VISION_TYPE` | Optional vision protocol type | `SN_CHAT_TYPE` |
|
|
| `SN_VISION_MODEL` | Optional vision-capable model override for `sn-image-recognize` | `SN_CHAT_MODEL` |
|
|
|
|
The default values are recommended for the [SenseNova](https://platform.sensenova.cn/).
|
|
|
|
Configure `SN_TEXT_*` or `SN_VISION_*` only when a command needs a different provider than the shared `SN_CHAT_*` provider.
|
|
|
|
For chat calls, the runner also accepts host-only base URLs such as
|
|
`https://token.sensenova.cn`: if no URL path is present, it appends the API
|
|
version path before the interface endpoint. Prefer the documented versioned
|
|
base URL, for example `https://token.sensenova.cn/v1`, for consistency with the
|
|
built-in defaults.
|
|
|
|
To use non-default shared chat settings, please:
|
|
|
|
1. Set `SN_CHAT_TYPE` according to the chat API protocol. Available values are:
|
|
|
|
```ini
|
|
# (Default) OpenAI-compatible `/chat/completions` interface (most widely supported)
|
|
SN_CHAT_TYPE="openai-completions"
|
|
# Anthropic Messages `/messages` interface
|
|
SN_CHAT_TYPE="anthropic-messages"
|
|
```
|
|
|
|
2. Set `SN_CHAT_BASE_URL` to the shared chat endpoint base URL. For example:
|
|
|
|
```ini
|
|
# (Default) For [SenseNova](https://platform.sensenova.cn/)
|
|
SN_CHAT_BASE_URL="https://token.sensenova.cn/v1"
|
|
# For Anthropic Messages API
|
|
SN_CHAT_BASE_URL="https://api.anthropic.com/v1"
|
|
# For OpenAI's chat completion API
|
|
SN_CHAT_BASE_URL="https://api.openai.com/v1"
|
|
# For Google Gemini API (OpenAI-compatible)
|
|
SN_CHAT_BASE_URL="https://generativelanguage.googleapis.com/v1beta/openai/"
|
|
```
|
|
|
|
3. Set `SN_CHAT_MODEL`, or set `SN_TEXT_MODEL` / `SN_VISION_MODEL` only when a command needs a different model:
|
|
|
|
```ini
|
|
# (Default) SenseNova 6.7 Flash Lite
|
|
SN_CHAT_MODEL="sensenova-6.7-flash-lite"
|
|
# Anthropic Claude Sonnet 4.6
|
|
SN_VISION_MODEL="claude-sonnet-4-6"
|
|
# Google Gemini 3 Flash Preview
|
|
SN_VISION_MODEL="gemini-3-flash-preview"
|
|
# OpenAI GPT 5.5
|
|
SN_TEXT_MODEL="gpt-5.5"
|
|
```
|
|
|
|
4. Set `SN_CHAT_API_KEY` to the API key for the shared chat endpoint, or use global `SN_API_KEY`.
|
|
|
|
```ini
|
|
SN_CHAT_API_KEY="sk-your-api-key"
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Missing API key
|
|
|
|
- Symptom: errors like "required but not set", "missing api key", or request unauthorized.
|
|
- Fix: set global `SN_API_KEY` when all capabilities use one key. Do not also set `SN_IMAGE_GEN_API_KEY` unless image generation needs a different provider or key. Use `SN_CHAT_API_KEY`, `SN_TEXT_API_KEY`, or `SN_VISION_API_KEY` only when chat/text/vision needs a different provider.
|
|
|
|
### Wrong base URL
|
|
|
|
- Symptom: request fails immediately, or URL validation/auth endpoint errors.
|
|
- Fix: verify `SN_BASE_URL` or capability-specific base URLs are full base URLs (with scheme + host), for example `https://token.sensenova.cn/v1`.
|
|
|
|
### Unsupported model name
|
|
|
|
- Symptom: provider returns HTTP 404 / model-not-found / bad request.
|
|
- Fix: ensure `*_MODEL_TYPE` / `*_TYPE` and `*_MODEL` are from the same provider, and that the model is available in your account.
|
|
|
|
### Auth / permission errors
|
|
|
|
- Symptom: HTTP 401/403, "permission denied", "forbidden".
|
|
- Fix: check whether the key matches the selected provider endpoint, confirm account quotas/permissions, and retry with a known-valid model.
|
|
|
|
## Security Notes
|
|
|
|
- **Never** commit `.env` files or API keys to git.
|
|
- If a key is leaked, rotate it immediately and update local env files.
|
|
- Prefer local secret management (`~/.openclaw/.env` or `~/.hermes/.env`) over hardcoding keys in scripts or prompts.
|