A comprehensive Volcengine API skill supporting image generation, video generation, and vision understanding.
English | 简体中文
# 1. Clone repository
git clone https://github.com/Lychee-AI-Team/Volcengine-Skill.git
cd Volcengine-Skill
# 2. Run installation script
./install.sh
# 3. Configure API Key
export ARK_API_KEY="your-api-key"
# Optional: custom relay/proxy base URL
# export VOLCENGINE_BASE_URL="https://your-relay.example.com/api/v3"
# 4. Run example
python3 examples/quickstart.py# 1. Clone repository
git clone https://github.com/Lychee-AI-Team/Volcengine-Skill.git
cd Volcengine-Skill
# 2. Configure environment
echo "ARK_API_KEY=your-api-key" > .env
# 3. Start service
docker compose up --buildIn OpenClaw chat, send the SKILL.md URL and ask OpenClaw to install it directly.
Please install this skill from SKILL.md:
https://raw.githubusercontent.com/Lychee-AI-Team/Volcengine-Skill/main/volcengine-api/SKILL.md
After installation, run a smoke check command in your local workspace:
python scripts/smoke_e2e.py --help| Method | Time | Use Case | Command |
|---|---|---|---|
| Script | 2-3 min | Local development, quick start | ./install.sh |
| Docker | 3-5 min | Containerized environment, teams | docker compose up |
| OpenClaw Chat | 1-2 min | Agent-driven setup, no manual shell steps | Send SKILL.md URL in OpenClaw |
| Manual | 5-10 min | Custom environment | See INSTALLATION.md |
📖 For detailed installation instructions, see INSTALLATION.md
- Text-to-Image
- Image Editing
- Image-to-Image
- Multiple sizes and styles
- Text-to-Video
- Image-to-Video
- Camera motion control
- First/last frame control
- Image content analysis
- Object detection and localization
- View generation progress
- Download results
- Manage history
For detailed installation instructions, see INSTALLATION.md.
# Clone repository
git clone https://github.com/Lychee-AI-Team/Volcengine-Skill.git
cd Volcengine-Skill
# Run installation script
./install.sh# Install dependencies
python3 -m pip install -r volcengine-api/requirements.txt
# Add toolkit package to PYTHONPATH (for interactive snippets)
export PYTHONPATH="$(pwd)/volcengine-api:${PYTHONPATH}"If you use OpenClaw, you can install by conversation instead of manual shell setup.
Install this Volcengine skill from:
https://raw.githubusercontent.com/Lychee-AI-Team/Volcengine-Skill/main/volcengine-api/SKILL.md
Then validate command availability:
python scripts/smoke_e2e.py --helpexport ARK_API_KEY="your-api-key-here"
# Optional relay/proxy endpoint
# export VOLCENGINE_BASE_URL="https://your-relay.example.com/api/v3"Create ~/.volcengine/config.yaml:
api_key: "your-api-key-here"
base_url: "https://ark.cn-beijing.volces.com/api/v3"
timeout: 30
max_retries: 3
output_dir: "./output"./scripts/configure.shBefore running the Python snippets below, ensure toolkit is importable:
export PYTHONPATH="$(pwd)/volcengine-api:${PYTHONPATH}"from toolkit.api_client import VolcengineAPIClient
from toolkit.config import ConfigManager
# Configure
config = ConfigManager()
config.set("api_key", "your-api-key")
# Create client
with VolcengineAPIClient(config) as client:
# Generate image
result = client.post("/images/generations", json={
"model": "doubao-seedream-4-0-250828",
"prompt": "Sunset beach with palm trees and waves",
"size": "1024x1024",
"response_format": "url"
})
print(f"Image URL: {result['data'][0]['url']}")# Generate video (async task)
result = client.post("/contents/generations/tasks", json={
"model": "doubao-seedance-1-5-pro-251215",
"content": [
{
"type": "text",
"text": "Camera slowly pulls out, revealing mountain scenery --duration 5"
}
]
})
# Note: Video generation is async. Use task ID to query status:
# task_result = client.get(f"/contents/generations/tasks/{result['id']}")
print(f"Task ID: {result['id']}")from toolkit.api_client import VolcengineAPIClient
from toolkit.config import ConfigManager
from toolkit.task_manager import TaskManager
from toolkit.models.base import TaskType, TaskStatus
from toolkit.utils.file_utils import FileUtils
# Initialize
config = ConfigManager()
client = VolcengineAPIClient(config)
task_manager = TaskManager(client)
# Create task
task = task_manager.create_task(
task_type=TaskType.IMAGE_GENERATION,
params={"prompt": "Beautiful sunset"}
)
# Query status
status = task_manager.get_task(task.id)
print(f"Status: {status.status}")
# Download result
if status.status == TaskStatus.SUCCEEDED:
FileUtils.download_file(status.result.url, "./output/image.png")from toolkit.validator import Validator
# Validate parameters
result = Validator.validate_image_generation_params(
prompt="City night view",
width=1920,
height=1080
)
if not result.is_valid:
print(f"Error: {result.errors}")
else:
# Execute generation
...More examples at examples.md
Volcengine-Skill/
├── install.sh # One-click installer
├── Dockerfile # Docker image definition
├── docker-compose.yml # Docker Compose config
├── .env.example # Environment template
├── scripts/
│ ├── configure.sh # Interactive config wizard
│ ├── verify_install.sh # Installation verification
│ └── help.sh # Help reference
├── examples/
│ └── quickstart.py # Quick start example
├── docs/
│ ├── QUickstart.md # Quick start guide
│ ├── INSTALLATION.md # Installation docs
│ ├── examples.md # Usage examples
│ └── troubleshooting.md # Troubleshooting
└── volcengine-api/
├── toolkit/ # Core functionality
│ ├── models/ # Data models
│ ├── utils/ # Utility functions
│ ├── api_client.py # API client
│ ├── config.py # Configuration management
│ ├── error_handler.py# Error handling
│ ├── task_manager.py # Task management
│ └── validator.py # Parameter validation
├── tests/ # Test suite
├── SKILL.md # Skill usage guide
└── requirements.txt # Dependencies
# Run all tests
pytest volcengine-api/tests/ -v
# Run specific test
pytest volcengine-api/tests/test_api_client.py -v
# Test coverage
pytest volcengine-api/tests/ --cov=toolkit --cov-report=htmlpython scripts/smoke_e2e.pyOptional parameters:
python scripts/smoke_e2e.py \
--image-prompt "Cyberpunk city at night" \
--video-prompt "Camera rises as flying cars streak by" \
--poll-interval 5 \
--max-polls 24config = ConfigManager()
config.get("api_key") # Get config
config.set("timeout", 60) # Set config
config.get_api_key() # Get API key
config.get_output_dir() # Get output directoryclient = VolcengineAPIClient(config)
client.get(endpoint) # GET request
client.post(endpoint, json={}) # POST request
client.put(endpoint, json={}) # PUT request
client.delete(endpoint) # DELETE requestmanager = TaskManager(client)
manager.create_task(type, params) # Create task
manager.get_task(task_id) # Get task
manager.list_tasks(status=..., task_type=...) # List tasks
manager.update_task_status(id, status) # Update status
manager.delete_task(task_id) # Delete taskValidator.validate_required(value, field, result)
Validator.validate_type(value, type, field, result)
Validator.validate_range(value, min, max, field, result)
Validator.validate_image_generation_params(prompt, width, height)
Validator.validate_video_generation_params(prompt, duration)All errors are converted to user-friendly messages:
from toolkit.error_handler import (
VolcengineError,
AuthenticationError,
RateLimitError,
InvalidInputError
)
try:
result = client.post("/images/generations", json=params)
except AuthenticationError as e:
print(f"Authentication failed: {e.message}")
print(f"Solution: {e.solution}")
except RateLimitError as e:
print(f"Rate limit: please wait {e.retry_after} seconds")
except InvalidInputError as e:
print(f"Parameter error: {e.message}")-
Don't hardcode API keys
# ❌ Wrong api_key = "your-key-here" # ✅ Correct api_key = os.getenv("ARK_API_KEY")
-
Use environment variables
export ARK_API_KEY="your-key"
-
Set config file permissions
chmod 600 ~/.volcengine/config.yaml
MIT License - See LICENSE file
Contributions welcome! See CONTRIBUTING.md for details.
Built with ❤️ for Volcengine API