Volcengine SDK Code Generator
Generate complete, runnable Volcengine SDK code from natural-language descriptions, and answer SDK configuration questions.
Workflow
When a user describes a Volcengine API operation, follow these steps:
Step 1: Identify Target Service, Operation, and Advanced Configuration Needs
Parse the user's description to determine:
Target service: which Volcengine service (e.g., ECS, VPC, TOS, billing)
Target operation: what operation to perform (e.g., list instances, create a VPC, query billing)
Target language: which programming language (Go, Python, PHP, Java, Node.js). If not specified, ask the user.
Advanced configuration needs: whether the user mentions or the scenario implies any of the following:
- Retry: user mentions "retry", "fault tolerance", or the operation is a write/create type (prone to throttling)
- Timeout: user mentions "timeout", or the operation involves large data volumes (batch queries, file uploads)
- Credentials: user mentions "STS", "AssumeRole", "temporary credentials", "OIDC", or explicitly wants to avoid hardcoding AK/SK
- Proxy/network: user mentions "proxy" or "internal network"
- Debug mode: user mentions "debug" or "logging"
- Connection pooling: user mentions "connection pool", "high concurrency", or "pool"
If the user explicitly requests these, include the corresponding configuration in the generated code. If not explicitly requested but implied by the scenario (e.g., resource creation naturally warrants retry), include suggested configuration as comments.
Step 2: Query Service Metadata via Volcengine API Explorer
Use the following APIs to find the correct service code, version, and action name. This step is critical because guessing often produces incorrect code — the API Explorer is the authoritative source.
2a. Find the ServiceCode
Fetch the service catalog:
GET https://api.volcengine.com/api/common/explorer/services
Response structure:
{
"Result": {
"Categories": [
{
"CategoryName": "...",
"Services": [
{
"ServiceCn": "Cloud Server",
"ServiceCode": "ecs",
"Product": "ECS",
"IsSdkAvailable": true,
"RegionType": "regional"
}
]
}
]
}
}
Match the user's intent to the correct ServiceCode based on ServiceCn, Product, and category name.
2b. Find the API version
GET https://api.volcengine.com/api/common/explorer/versions?ServiceCode={ServiceCode}
Response:
{
"Result": {
"Versions": [
{
"ServiceCode": "billing",
"Version": "2022-01-01",
"IsDefault": 0
}
]
}
}
Use the version with IsDefault == 1. If no default version exists, use the latest available.
2c. Find the Action name
GET https://api.volcengine.com/api/common/explorer/apis?ServiceCode={ServiceCode}&Version={Version}&APIVersion={Version}
Response:
{
"Result": {
"Groups": [
{
"Name": "Instance",
"Apis": [
{
"Action": "DescribeInstances",
"NameCn": "Query instance list",
"Description": "..."
}
]
}
]
}
}
Match user intent using the Action name and NameCn (Chinese name).
2c-alt: Search API (when direct lookup fails)
If the service catalog or API list cannot clearly match the user's description — for example, the user uses vague terms, Chinese names that don't map directly to a ServiceCode, or the API list doesn't seem to contain what the user wants — use the search API as a fallback:
GET https://api.volcengine.com/api/common/search/all?Query={URL-encoded search term}&Channel=api&Limit=10
Search terms can be Chinese or English — use whichever best matches the user's description.
Response structure:
{
"Result": {
"List": [
{
"BizInfo": {
"Action": "ListProjects",
"ServiceCn": "Access Control",
"ServiceCode": "iam",
"Version": "2021-08-01"
},
"Highlight": [
{"Field": "title", "Summary": "Get <em>project</em> <em>list</em>"}
]
}
],
"Total": 200
}
}
Select the best match based on ServiceCn, Action, and highlight text, then continue to step 2d.
The search API is particularly useful when:
- The user describes the operation in natural language but doesn't know which service owns it
- A service has too many APIs to browse manually
- The description spans multiple services (search returns results across all services)
2d. Get full API parameter details
GET https://api.volcengine.com/api/common/explorer/api-swagger?ServiceCode={ServiceCode}&Version={Version}&APIVersion={Version}&ActionName={Action}
Returns the full Swagger/OpenAPI specification, including:
- HTTP method (GET/POST)
- All request parameters with types, required flags, and descriptions
- Response structure
- Constraints and validation rules
x-demo field: contains requestDemo and responseDemo with official examples
Read this specification carefully — it is essential for generating accurate code.
2e. Extract parameter example values (from x-demo requestDemo)
The info.x-demo array in the Swagger response contains requestDemo — official request examples. Extract realistic parameter values from these to populate generated code.
Extraction process:
- Locate
info.x-demo[0].requestDemo and parse the request body JSON
- Use requestDemo values as example values in generated code — they are more accurate and realistic than invented values
- For masked values (e.g.,
cc5silum********), keep the masked format and add a comment prompting the user to replace with real values
- If a parameter value is a JSON string (e.g., a
Config field), format it clearly and comment each sub-field
Example: for VKE CreateAddon, requestDemo contains:
{
"ClusterId": "cc5silum********",
"Name": "ingress-nginx",
"DeployMode": "Unmanaged",
"DeployNodeType": ["VirtualNode"],
"Config": "{\"Replica\":1,\"Resource\":{\"Request\":{\"Cpu\":\"0.25\",\"Memory\":\"512Mi\"},\"Limit\":{\"Cpu\":\"0.5\",\"Memory\":\"1024Mi\"}},\"PrivateNetwork\":{\"SubnetId\":\"subnet-2d61qn69iji****\",\"IpVersion\":\"IPV4\"}}"
}
Use these example values directly instead of empty placeholders.
2f. Retrieve detailed configuration for complex parameters
Some parameter description fields contain documentation links (e.g., https://www.volcengine.com/docs/...) pointing to detailed configuration guides. For complex parameters, fetch these links for more information:
When to consult documentation:
- The parameter value is a JSON string with a "see detailed configuration" reference in the description (e.g., VKE
Config)
- The parameter is a nested structure whose sub-field format is documented externally
- The
enum values have unclear meanings that are explained in the documentation
Processing flow:
- Check whether the parameter
description contains a volcengine.com/docs link
- If so, use WebFetch to retrieve the linked page and extract configuration details relevant to the parameter
- Incorporate documentation examples into the generated code as comments or structured parameters
- If the documentation is inaccessible, fall back to requestDemo example values
2g. Determine required and recommended parameters
Required-field detection relies on multiple sources, not just the required array:
- Explicitly required: listed in the Swagger
required array
- Implied by description: the description contains phrases like "must specify", "required", or equivalent
- Logically required: semantically essential even if not formally marked (e.g., instance type and network config when creating resources)
- Conditionally required: the description states "required when X=Y" — if the user's scenario matches, include it
Parameter value priority:
- requestDemo example values (highest priority): use the official examples directly
example field: individual parameter example values from the Swagger spec
- enum values: pick the most common or general-purpose option
- Documentation recommendations: values extracted from linked docs
- Industry conventions: reasonable defaults following cloud-computing norms (e.g.,
172.16.0.0/16 for CIDR, descriptive names for instances)
Step 3: Consult SDK Configuration References (as needed)
If Step 1 identified advanced configuration needs, read the corresponding reference file for the target language to get accurate configuration code:
| Language |
Reference File |
| Go |
references/sdk-integration-go.md |
| Python |
references/sdk-integration-python.md |
| Java |
references/sdk-integration-java.md |
| Node.js |
references/sdk-integration-nodejs.md |
| PHP |
references/sdk-integration-php.md |
These files contain verified code snippets for retry, timeout, credentials, proxy, connection pooling, and debug configuration. Use these patterns directly rather than writing from memory — SDK configuration varies significantly across languages, and the reference files ensure accuracy.
Step 4: Generate Complete SDK Code
Generate a complete, runnable code example following these rules:
General Rules (all languages)
- Authentication: read AK/SK from environment variables
VOLCENGINE_ACCESS_KEY and VOLCENGINE_SECRET_KEY by default. If the user needs a different auth method (STS, AssumeRole, OIDC), use the corresponding pattern from the reference files. The exact reading mechanism varies by language — see each language section and the reference files.
- Region: default to
cn-beijing for regional services. Add a comment noting that users can change this.
- Required parameters: include all required parameters (sources per step 2g), using realistic example values from requestDemo or example fields. Add a comment next to each value explaining its meaning and source.
- Parameter value quality: values must follow realistic formats and business semantics, not simple placeholders:
- Instance IDs: use masked format like
i-abc123****** (from requestDemo)
- CIDRs: use reasonable ranges like
172.16.0.0/16
- Enums: use the most common option
- Nested JSON configs: expand into readable multi-line format with per-field comments
- Complex parameter handling: for parameters whose value is a JSON string (e.g., VKE Config), build a struct/dict first and then serialize to JSON, rather than hardcoding a long string. This makes the code more readable and easier to modify.
- Optional parameters: include commonly-used optional parameters (e.g., pagination) as commented-out lines with explanations.
- Error handling: include standard error handling for the target language.
- Output: print the response in a readable format (e.g., formatted JSON).
- Comments: add a header comment describing the code's purpose. Add inline comments for non-obvious parameters. Match comment language to the user's prompt language.
- Advanced configuration integration: when the user has advanced config needs, weave the configuration naturally into the main code (not as a separate block), producing a single runnable file:
- Retry: add retry settings during client/config initialization, with comments explaining defaults and tunable parameters
- Timeout: set global timeout during client initialization; show per-request timeout usage if needed
- Credentials: replace the default AK/SK auth code with the user-specified method (STS, AssumeRole, etc.)
- Proxy: add proxy settings in client configuration
- Debug: enable debug mode in client configuration
- Connection pooling: set pool parameters in client configuration
Go
The Go SDK uses {Action}Input structs (not Request). Services are instantiated via {service}.New(sess).
package main
import (
"fmt"
"os"
"github.com/volcengine/volcengine-go-sdk/service/{service}"
"github.com/volcengine/volcengine-go-sdk/volcengine"
"github.com/volcengine/volcengine-go-sdk/volcengine/credentials"
"github.com/volcengine/volcengine-go-sdk/volcengine/session"
)
func main() {
ak := os.Getenv("VOLCENGINE_ACCESS_KEY")
sk := os.Getenv("VOLCENGINE_SECRET_KEY")
region := "cn-beijing"
config := volcengine.NewConfig().
WithRegion(region).
WithCredentials(credentials.NewStaticCredentials(ak, sk, ""))
// [Advanced config — add as needed, see references/sdk-integration-go.md]
// Retry: config.WithMaxRetries(5)
// Timeout: config.WithHTTPClient(&http.Client{Timeout: 60 * time.Second})
// Proxy: config.WithHTTPProxy("http://proxy:8080")
// Debug: config.WithDebug(true)
sess, err := session.NewSession(config)
if err != nil {
panic(err)
}
svc := {service}.New(sess)
input := &{service}.{Action}Input{
// Set required parameters here
}
resp, err := svc.{Action}(input)
if err != nil {
panic(err)
}
fmt.Println(resp)
}
Key points:
- Package path:
github.com/volcengine/volcengine-go-sdk/service/{service} (lowercase, e.g., billing, ecs, vpc)
- Config chain:
volcengine.NewConfig().WithRegion(region).WithCredentials(credentials.NewStaticCredentials(ak, sk, ""))
- Session:
session.NewSession(config) (returns session and error)
- Service client:
{service}.New(sess) (e.g., billing.New(sess), ecs.New(sess))
- Request struct:
{Action}Input (e.g., ListAvailableInstancesInput, DescribeInstancesInput)
- Method:
svc.{Action}(input), PascalCase action name
Python
The Python SDK uses {SERVICE}Api (uppercase service name) and {Action}Request models.
from __future__ import print_function
import os
import volcenginesdkcore
import volcenginesdk{service}
from volcenginesdkcore.rest import ApiException
if __name__ == '__main__':
configuration = volcenginesdkcore.Configuration()
configuration.ak = os.environ.get("VOLCENGINE_ACCESS_KEY")
configuration.sk = os.environ.get("VOLCENGINE_SECRET_KEY")
configuration.region = "cn-beijing"
# [Advanced config — add as needed, see references/sdk-integration-python.md]
# Retry: configuration.max_retry_attempts = 5
# Timeout: configuration.connection_timeout = 10; configuration.read_timeout = 60
# Proxy: configuration.proxy = "http://proxy:8080"
# Debug: configuration.debug = True
volcenginesdkcore.Configuration.set_default(configuration)
api_instance = volcenginesdk{service}.{SERVICE}Api()
request = volcenginesdk{service}.{Action}Request(
# Set required parameters here
)
try:
resp = api_instance.{action_snake_case}(request)
print(resp)
except ApiException as e:
print("API exception: %s\n" % e)
Key points:
- Package:
volcenginesdkcore + volcenginesdk{service} (all lowercase, no separators, e.g., volcenginesdkbilling, volcenginesdkecs)
- Config:
volcenginesdkcore.Configuration(), set .ak, .sk, .region, then set_default()
- API class:
volcenginesdk{service}.{SERVICE}Api() — service name ALL CAPS (e.g., BILLINGApi, ECSApi, VPCApi)
- Request class:
volcenginesdk{service}.{Action}Request(...) (PascalCase, e.g., ListAvailableInstancesRequest)
- Method:
api_instance.{action_snake_case}(request) — snake_case (e.g., list_available_instances, describe_instances)
- Exception:
from volcenginesdkcore.rest import ApiException
Java
The Java SDK uses {ServiceName}Api and {Action}Request models under com.volcengine.{service}.
package com.volcengine.sample;
import com.volcengine.ApiClient;
import com.volcengine.ApiException;
import com.volcengine.sign.Credentials;
import com.volcengine.{service}.{ServiceName}Api;
import com.volcengine.{service}.model.*;
public class Example {
public static void main(String[] args) throws Exception {
String ak = System.getenv("VOLCENGINE_ACCESS_KEY");
String sk = System.getenv("VOLCENGINE_SECRET_KEY");
String region = "cn-beijing";
ApiClient apiClient = new ApiClient()
.setCredentials(Credentials.getCredentials(ak, sk))
.setRegion(region);
// [Advanced config — add as needed, see references/sdk-integration-java.md]
// Retry: apiClient.setRetrySettings(new RetrySettings().setMaxAttempts(5));
// Timeout: apiClient.setConnectionTimeout(5000); apiClient.setReadTimeout(30000);
// Proxy: apiClient.setHttpProxy("http://proxy:8080");
// Debug: apiClient.setDebugging(true);
{ServiceName}Api api = new {ServiceName}Api(apiClient);
{Action}Request request = new {Action}Request();
// request.setParamName(value);
try {
{Action}Response resp = api.{actionCamelCase}(request);
System.out.println(resp);
} catch (ApiException e) {
System.out.println(e.getResponseBody());
}
}
}
Key points:
- Package:
com.volcengine.{service} (lowercase, e.g., com.volcengine.billing, com.volcengine.ecs)
- ApiClient:
new ApiClient().setCredentials(Credentials.getCredentials(ak, sk)).setRegion(region)
- API class:
{ServiceName}Api (PascalCase, e.g., BillingApi, EcsApi) — constructor takes apiClient
- Request class:
{Action}Request (e.g., ListAvailableInstancesRequest) — set params via setters
- Method:
api.{actionCamelCase}(request) — camelCase (e.g., listAvailableInstances, describeInstances)
- Exception:
ApiException, use e.getResponseBody() for details
Node.js
The Node.js SDK uses a command pattern: {SERVICE}Client + {Action}Command.
import { {SERVICE}Client, {Action}Command } from "@volcengine/{service}";
// Automatically reads VOLCENGINE_ACCESS_KEY and VOLCENGINE_SECRET_KEY from env
const client = new {SERVICE}Client({
region: "cn-beijing",
// [Advanced config — add as needed, see references/sdk-integration-nodejs.md]
// maxRetries: 5, // retry count
// autoRetry: false, // disable auto-retry
// httpOptions: { timeout: 30000 }, // timeout (ms)
// httpOptions: { proxy: { protocol: "http", host: "127.0.0.1", port: 8888 } }, // proxy
});
async function main() {
try {
const command = new {Action}Command({
// Set required parameters here
});
const response = await client.send(command);
console.log(JSON.stringify(response, null, 2));
} catch (error) {
console.error("Error:", error);
}
}
main();
Key points:
- Package:
@volcengine/{service} (lowercase, e.g., @volcengine/ecs, @volcengine/vpc)
- Client:
{SERVICE}Client (ALL CAPS service name, e.g., ECSClient, VPCClient)
- Command:
{Action}Command (PascalCase, e.g., DescribeInstancesCommand, CreateVpcCommand)
- Invocation:
client.send(command) — async, returns a Promise
- Auth: automatically reads
VOLCENGINE_ACCESS_KEY and VOLCENGINE_SECRET_KEY from env; can also pass accessKeyId/secretAccessKey in the client constructor
PHP
The PHP SDK uses classes under the \Volcengine\{Service}\ namespace.
<?php
require_once(__DIR__ . '/vendor/autoload.php');
$config = \Volcengine\Common\Configuration::getDefaultConfiguration()
->setAk(getenv("VOLCENGINE_ACCESS_KEY"))
->setSk(getenv("VOLCENGINE_SECRET_KEY"))
->setRegion("cn-beijing");
// [Advanced config — add as needed, see references/sdk-integration-php.md]
// Proxy and timeout are configured via GuzzleHttp\Client options
$httpClient = new GuzzleHttp\Client([
// 'proxy' => 'http://proxy:8080', // proxy
// 'timeout' => 60, // request timeout (seconds)
// 'connect_timeout' => 10, // connection timeout (seconds)
]);
$apiInstance = new \Volcengine\{Service}\Api\{SERVICE}Api(
$httpClient,
$config
);
$request = new \Volcengine\{Service}\Model\{Action}Request();
// $request->setParamName("value");
try {
$resp = $apiInstance->{actionCamelCase}($request);
print_r($resp);
} catch (Exception $e) {
echo 'API exception: ', $e->getMessage(), PHP_EOL;
}
Key points:
- Config:
\Volcengine\Common\Configuration::getDefaultConfiguration()->setAk()->setSk()->setRegion()
- API class:
\Volcengine\{Service}\Api\{SERVICE}Api — namespace uses PascalCase Service (e.g., Billing), class name uses ALL CAPS (e.g., BILLINGApi)
- Constructor: takes
GuzzleHttp\Client() and $config
- Request class:
\Volcengine\{Service}\Model\{Action}Request (e.g., \Volcengine\Billing\Model\ListAvailableInstancesRequest)
- Set params via setters:
$request->setProduct("value")
- Method:
$apiInstance->{actionCamelCase}($request) (e.g., listAvailableInstances)
Step 5: Present Results
After generating code:
- Display the complete code in a code block with the correct language tag
- List the dependencies the user needs to install (
go get, pip install, npm install, composer require, Maven/Gradle coordinates)
- Remind the user to set environment variables:
export VOLCENGINE_ACCESS_KEY="your-access-key"
export VOLCENGINE_SECRET_KEY="your-secret-key"
- Note important constraints from the API spec (rate limits, required permissions, data range limits, etc.)
- If the code includes advanced configuration, briefly explain each setting's purpose, defaults, and tuning advice. For example:
- "Retry defaults to 3 attempts, covers network errors and throttling — adjust via
WithMaxRetries"
- "Connection timeout defaults to 30s; consider increasing for large batch queries"
Answering SDK Configuration Questions
When the user asks how to configure or use the Volcengine SDK (rather than generate API call code), follow this approach:
Step 1: Identify the User's Need
Common configuration topics:
- Authentication: AK/SK, STS Token, AssumeRole, OIDC, SAML
- Retry: enable/disable, max attempts, backoff strategy, custom retry conditions
- Timeout: connection timeout, read timeout, per-request timeout
- Proxy: HTTP/HTTPS proxy configuration
- Endpoint: custom endpoint, region-based resolution, dual-stack (IPv6)
- SSL/HTTPS: disable SSL verification, TLS version, HTTP vs. HTTPS
- Connection pooling: pool size, keep-alive, idle connections
- Debug: debug mode, logging, middleware
- Error handling: exception types, retryable vs. non-retryable errors
- Environment variables: supported env vars per SDK
Step 2: Consult the Reference Documentation
Read the reference file for the user's target language:
| Language |
Reference File |
| Go |
references/sdk-integration-go.md |
| Python |
references/sdk-integration-python.md |
| Java |
references/sdk-integration-java.md |
| Node.js |
references/sdk-integration-nodejs.md |
| PHP |
references/sdk-integration-php.md |
These files contain concise code examples for each major configuration topic. Read the relevant file and answer with accurate, copy-paste-ready code.
If the user's question is not covered in the reference file or requires more detail, fetch the full upstream documentation from GitHub:
| Language |
Upstream Documentation URL |
| Go |
https://raw.githubusercontent.com/volcengine/volcengine-go-sdk/master/SDK_Integration.md |
| Python |
https://raw.githubusercontent.com/volcengine/volcengine-python-sdk/master/SDK_Integration.md |
| Java |
https://raw.githubusercontent.com/volcengine/volcengine-java-sdk/master/SDK_Integration.md |
| Node.js |
https://raw.githubusercontent.com/volcengine/volcengine-nodejs-sdk/master/SDK_Integration.md |
| PHP |
https://raw.githubusercontent.com/volcengine/volcengine-php-sdk/main/SDK_Integration.md |
Step 3: Provide a Clear Answer
- Show complete, runnable code snippets demonstrating the configuration
- Explain each setting's purpose and default value
- Mention caveats (e.g., "disabling SSL verification is only appropriate in test environments")
- If the user has not specified a language, ask which one they are using
- Match the answer language to the user's prompt language
Important Notes
- Always fetch data from the API Explorer — Volcengine APIs are updated frequently, so the Explorer is the authoritative source. Do not rely on memory.
- If the user's description is ambiguous (could map to multiple services or operations), list the options and ask for confirmation.
- If a service has
IsSdkAvailable: false, inform the user that the official SDK may not yet support this service, and provide a raw HTTP request example as an alternative.
- For regional services, remind the user to change the region setting if their resources are not in
cn-beijing.
1---
2name: volcengine-sdk-generator
3description: >
4 Generate complete, runnable Volcengine SDK code and provide SDK configuration guidance.
5 Supports Go, Python, PHP, Java, and Node.js. Trigger this skill whenever the user wants to call
6 a Volcengine API, generate Volcengine SDK code, or describes a cloud operation on Volcengine
7 (e.g., "list ECS instances", "create a VPC on Volcengine", "query Volcengine billing with Python").
8 Also trigger when the user asks about Volcengine SDK configuration and best practices — including
9 retry, timeout, authentication (AK/SK, STS, AssumeRole), proxy, connection pooling, SSL, debug mode,
10 and error handling (e.g., "how to configure retry for Volcengine Go SDK", "volcengine python sdk
11 proxy setup"). Trigger when the user mentions Volcengine service names such as ECS, VPC, CDN, CLB,
12 RDS, Redis, Kafka, billing, IAM, DNS with code generation or SDK usage intent.
13 When the user only needs API specification queries (parameters, error codes, response structures),
14 hand off to the volcengine-api skill. When the user needs CLI-based operations, hand off to
15 the volcengine-cli skill. Supports both Chinese and English prompts.
16metadata:
17 source: https://skillmd.com/skills/bytedance/volcengine-sdk-generator
18---
19
20# Volcengine SDK Code Generator
21
22Generate complete, runnable Volcengine SDK code from natural-language descriptions, and answer SDK configuration questions.
23
24## Workflow
25
26When a user describes a Volcengine API operation, follow these steps:
27
28### Step 1: Identify Target Service, Operation, and Advanced Configuration Needs
29
30Parse the user's description to determine:
31- **Target service**: which Volcengine service (e.g., ECS, VPC, TOS, billing)
32- **Target operation**: what operation to perform (e.g., list instances, create a VPC, query billing)
33- **Target language**: which programming language (Go, Python, PHP, Java, Node.js). If not specified, ask the user.
34- **Advanced configuration needs**: whether the user mentions or the scenario implies any of the following:
35 - **Retry**: user mentions "retry", "fault tolerance", or the operation is a write/create type (prone to throttling)
36 - **Timeout**: user mentions "timeout", or the operation involves large data volumes (batch queries, file uploads)
37 - **Credentials**: user mentions "STS", "AssumeRole", "temporary credentials", "OIDC", or explicitly wants to avoid hardcoding AK/SK
38 - **Proxy/network**: user mentions "proxy" or "internal network"
39 - **Debug mode**: user mentions "debug" or "logging"
40 - **Connection pooling**: user mentions "connection pool", "high concurrency", or "pool"
41
42 If the user explicitly requests these, include the corresponding configuration in the generated code. If not explicitly requested but implied by the scenario (e.g., resource creation naturally warrants retry), include suggested configuration as comments.
43
44### Step 2: Query Service Metadata via Volcengine API Explorer
45
46Use the following APIs to find the correct service code, version, and action name. This step is critical because guessing often produces incorrect code — the API Explorer is the authoritative source.
47
48**2a. Find the ServiceCode**
49
50Fetch the service catalog:
51```
52GET https://api.volcengine.com/api/common/explorer/services
53```
54Response structure:
55```json
56{
57 "Result": {
58 "Categories": [
59 {
60 "CategoryName": "...",
61 "Services": [
62 {
63 "ServiceCn": "Cloud Server",
64 "ServiceCode": "ecs",
65 "Product": "ECS",
66 "IsSdkAvailable": true,
67 "RegionType": "regional"
68 }
69 ]
70 }
71 ]
72 }
73}
74```
75Match the user's intent to the correct `ServiceCode` based on `ServiceCn`, `Product`, and category name.
76
77**2b. Find the API version**
78
79```
80GET https://api.volcengine.com/api/common/explorer/versions?ServiceCode={ServiceCode}
81```
82Response:
83```json
84{
85 "Result": {
86 "Versions": [
87 {
88 "ServiceCode": "billing",
89 "Version": "2022-01-01",
90 "IsDefault": 0
91 }
92 ]
93 }
94}
95```
96Use the version with `IsDefault == 1`. If no default version exists, use the latest available.
97
98**2c. Find the Action name**
99
100```
101GET https://api.volcengine.com/api/common/explorer/apis?ServiceCode={ServiceCode}&Version={Version}&APIVersion={Version}
102```
103Response:
104```json
105{
106 "Result": {
107 "Groups": [
108 {
109 "Name": "Instance",
110 "Apis": [
111 {
112 "Action": "DescribeInstances",
113 "NameCn": "Query instance list",
114 "Description": "..."
115 }
116 ]
117 }
118 ]
119 }
120}
121```
122Match user intent using the `Action` name and `NameCn` (Chinese name).
123
124**2c-alt: Search API (when direct lookup fails)**
125
126If the service catalog or API list cannot clearly match the user's description — for example, the user uses vague terms, Chinese names that don't map directly to a ServiceCode, or the API list doesn't seem to contain what the user wants — use the search API as a fallback:
127
128```
129GET https://api.volcengine.com/api/common/search/all?Query={URL-encoded search term}&Channel=api&Limit=10
130```
131
132Search terms can be Chinese or English — use whichever best matches the user's description.
133
134Response structure:
135```json
136{
137 "Result": {
138 "List": [
139 {
140 "BizInfo": {
141 "Action": "ListProjects",
142 "ServiceCn": "Access Control",
143 "ServiceCode": "iam",
144 "Version": "2021-08-01"
145 },
146 "Highlight": [
147 {"Field": "title", "Summary": "Get <em>project</em> <em>list</em>"}
148 ]
149 }
150 ],
151 "Total": 200
152 }
153}
154```
155
156Select the best match based on `ServiceCn`, `Action`, and highlight text, then continue to step 2d.
157
158The search API is particularly useful when:
159- The user describes the operation in natural language but doesn't know which service owns it
160- A service has too many APIs to browse manually
161- The description spans multiple services (search returns results across all services)
162
163**2d. Get full API parameter details**
164
165```
166GET https://api.volcengine.com/api/common/explorer/api-swagger?ServiceCode={ServiceCode}&Version={Version}&APIVersion={Version}&ActionName={Action}
167```
168Returns the full Swagger/OpenAPI specification, including:
169- HTTP method (GET/POST)
170- All request parameters with types, required flags, and descriptions
171- Response structure
172- Constraints and validation rules
173- **`x-demo` field**: contains `requestDemo` and `responseDemo` with official examples
174
175Read this specification carefully — it is essential for generating accurate code.
176
177**2e. Extract parameter example values (from x-demo requestDemo)**
178
179The `info.x-demo` array in the Swagger response contains `requestDemo` — official request examples. Extract realistic parameter values from these to populate generated code.
180
181Extraction process:
1821. Locate `info.x-demo[0].requestDemo` and parse the request body JSON
1832. Use requestDemo values as example values in generated code — they are more accurate and realistic than invented values
1843. For masked values (e.g., `cc5silum********`), keep the masked format and add a comment prompting the user to replace with real values
1854. If a parameter value is a JSON string (e.g., a `Config` field), format it clearly and comment each sub-field
186
187Example: for VKE CreateAddon, requestDemo contains:
188```json
189{
190 "ClusterId": "cc5silum********",
191 "Name": "ingress-nginx",
192 "DeployMode": "Unmanaged",
193 "DeployNodeType": ["VirtualNode"],
194 "Config": "{\"Replica\":1,\"Resource\":{\"Request\":{\"Cpu\":\"0.25\",\"Memory\":\"512Mi\"},\"Limit\":{\"Cpu\":\"0.5\",\"Memory\":\"1024Mi\"}},\"PrivateNetwork\":{\"SubnetId\":\"subnet-2d61qn69iji****\",\"IpVersion\":\"IPV4\"}}"
195}
196```
197Use these example values directly instead of empty placeholders.
198
199**2f. Retrieve detailed configuration for complex parameters**
200
201Some parameter `description` fields contain documentation links (e.g., `https://www.volcengine.com/docs/...`) pointing to detailed configuration guides. For complex parameters, fetch these links for more information:
202
203When to consult documentation:
204- The parameter value is a JSON string with a "see detailed configuration" reference in the description (e.g., VKE `Config`)
205- The parameter is a nested structure whose sub-field format is documented externally
206- The `enum` values have unclear meanings that are explained in the documentation
207
208Processing flow:
2091. Check whether the parameter `description` contains a `volcengine.com/docs` link
2102. If so, use WebFetch to retrieve the linked page and extract configuration details relevant to the parameter
2113. Incorporate documentation examples into the generated code as comments or structured parameters
2124. If the documentation is inaccessible, fall back to requestDemo example values
213
214**2g. Determine required and recommended parameters**
215
216Required-field detection relies on multiple sources, not just the `required` array:
217
2181. **Explicitly required**: listed in the Swagger `required` array
2192. **Implied by description**: the description contains phrases like "must specify", "required", or equivalent
2203. **Logically required**: semantically essential even if not formally marked (e.g., instance type and network config when creating resources)
2214. **Conditionally required**: the description states "required when X=Y" — if the user's scenario matches, include it
222
223Parameter value priority:
2241. **requestDemo example values** (highest priority): use the official examples directly
2252. **`example` field**: individual parameter `example` values from the Swagger spec
2263. **enum values**: pick the most common or general-purpose option
2274. **Documentation recommendations**: values extracted from linked docs
2285. **Industry conventions**: reasonable defaults following cloud-computing norms (e.g., `172.16.0.0/16` for CIDR, descriptive names for instances)
229
230### Step 3: Consult SDK Configuration References (as needed)
231
232If Step 1 identified advanced configuration needs, read the corresponding reference file for the target language to get accurate configuration code:
233
234| Language | Reference File |
235|----------|---------------|
236| Go | `references/sdk-integration-go.md` |
237| Python | `references/sdk-integration-python.md` |
238| Java | `references/sdk-integration-java.md` |
239| Node.js | `references/sdk-integration-nodejs.md` |
240| PHP | `references/sdk-integration-php.md` |
241
242These files contain verified code snippets for retry, timeout, credentials, proxy, connection pooling, and debug configuration. Use these patterns directly rather than writing from memory — SDK configuration varies significantly across languages, and the reference files ensure accuracy.
243
244### Step 4: Generate Complete SDK Code
245
246Generate a complete, runnable code example following these rules:
247
248#### General Rules (all languages)
249
2501. **Authentication**: read AK/SK from environment variables `VOLCENGINE_ACCESS_KEY` and `VOLCENGINE_SECRET_KEY` by default. If the user needs a different auth method (STS, AssumeRole, OIDC), use the corresponding pattern from the reference files. The exact reading mechanism varies by language — see each language section and the reference files.
2512. **Region**: default to `cn-beijing` for regional services. Add a comment noting that users can change this.
2523. **Required parameters**: include all required parameters (sources per step 2g), using realistic example values from requestDemo or example fields. Add a comment next to each value explaining its meaning and source.
2534. **Parameter value quality**: values must follow realistic formats and business semantics, not simple placeholders:
254 - Instance IDs: use masked format like `i-abc123******` (from requestDemo)
255 - CIDRs: use reasonable ranges like `172.16.0.0/16`
256 - Enums: use the most common option
257 - Nested JSON configs: expand into readable multi-line format with per-field comments
2585. **Complex parameter handling**: for parameters whose value is a JSON string (e.g., VKE Config), build a struct/dict first and then serialize to JSON, rather than hardcoding a long string. This makes the code more readable and easier to modify.
2596. **Optional parameters**: include commonly-used optional parameters (e.g., pagination) as commented-out lines with explanations.
2607. **Error handling**: include standard error handling for the target language.
2618. **Output**: print the response in a readable format (e.g., formatted JSON).
2629. **Comments**: add a header comment describing the code's purpose. Add inline comments for non-obvious parameters. Match comment language to the user's prompt language.
26310. **Advanced configuration integration**: when the user has advanced config needs, weave the configuration naturally into the main code (not as a separate block), producing a single runnable file:
264 - **Retry**: add retry settings during client/config initialization, with comments explaining defaults and tunable parameters
265 - **Timeout**: set global timeout during client initialization; show per-request timeout usage if needed
266 - **Credentials**: replace the default AK/SK auth code with the user-specified method (STS, AssumeRole, etc.)
267 - **Proxy**: add proxy settings in client configuration
268 - **Debug**: enable debug mode in client configuration
269 - **Connection pooling**: set pool parameters in client configuration
270
271#### Go
272
273The Go SDK uses `{Action}Input` structs (not `Request`). Services are instantiated via `{service}.New(sess)`.
274
275```go
276package main
277
278import (
279 "fmt"
280 "os"
281 "github.com/volcengine/volcengine-go-sdk/service/{service}"
282 "github.com/volcengine/volcengine-go-sdk/volcengine"
283 "github.com/volcengine/volcengine-go-sdk/volcengine/credentials"
284 "github.com/volcengine/volcengine-go-sdk/volcengine/session"
285)
286
287func main() {
288 ak := os.Getenv("VOLCENGINE_ACCESS_KEY")
289 sk := os.Getenv("VOLCENGINE_SECRET_KEY")
290 region := "cn-beijing"
291
292 config := volcengine.NewConfig().
293 WithRegion(region).
294 WithCredentials(credentials.NewStaticCredentials(ak, sk, ""))
295
296 // [Advanced config — add as needed, see references/sdk-integration-go.md]
297 // Retry: config.WithMaxRetries(5)
298 // Timeout: config.WithHTTPClient(&http.Client{Timeout: 60 * time.Second})
299 // Proxy: config.WithHTTPProxy("http://proxy:8080")
300 // Debug: config.WithDebug(true)
301
302 sess, err := session.NewSession(config)
303 if err != nil {
304 panic(err)
305 }
306 svc := {service}.New(sess)
307
308 input := &{service}.{Action}Input{
309 // Set required parameters here
310 }
311 resp, err := svc.{Action}(input)
312 if err != nil {
313 panic(err)
314 }
315 fmt.Println(resp)
316}
317```
318
319Key points:
320- Package path: `github.com/volcengine/volcengine-go-sdk/service/{service}` (lowercase, e.g., `billing`, `ecs`, `vpc`)
321- Config chain: `volcengine.NewConfig().WithRegion(region).WithCredentials(credentials.NewStaticCredentials(ak, sk, ""))`
322- Session: `session.NewSession(config)` (returns session and error)
323- Service client: `{service}.New(sess)` (e.g., `billing.New(sess)`, `ecs.New(sess)`)
324- Request struct: `{Action}Input` (e.g., `ListAvailableInstancesInput`, `DescribeInstancesInput`)
325- Method: `svc.{Action}(input)`, PascalCase action name
326
327#### Python
328
329The Python SDK uses `{SERVICE}Api` (uppercase service name) and `{Action}Request` models.
330
331```python
332from __future__ import print_function
333import os
334import volcenginesdkcore
335import volcenginesdk{service}
336from volcenginesdkcore.rest import ApiException
337
338if __name__ == '__main__':
339 configuration = volcenginesdkcore.Configuration()
340 configuration.ak = os.environ.get("VOLCENGINE_ACCESS_KEY")
341 configuration.sk = os.environ.get("VOLCENGINE_SECRET_KEY")
342 configuration.region = "cn-beijing"
343
344 # [Advanced config — add as needed, see references/sdk-integration-python.md]
345 # Retry: configuration.max_retry_attempts = 5
346 # Timeout: configuration.connection_timeout = 10; configuration.read_timeout = 60
347 # Proxy: configuration.proxy = "http://proxy:8080"
348 # Debug: configuration.debug = True
349
350 volcenginesdkcore.Configuration.set_default(configuration)
351
352 api_instance = volcenginesdk{service}.{SERVICE}Api()
353 request = volcenginesdk{service}.{Action}Request(
354 # Set required parameters here
355 )
356
357 try:
358 resp = api_instance.{action_snake_case}(request)
359 print(resp)
360 except ApiException as e:
361 print("API exception: %s\n" % e)
362```
363
364Key points:
365- Package: `volcenginesdkcore` + `volcenginesdk{service}` (all lowercase, no separators, e.g., `volcenginesdkbilling`, `volcenginesdkecs`)
366- Config: `volcenginesdkcore.Configuration()`, set `.ak`, `.sk`, `.region`, then `set_default()`
367- API class: `volcenginesdk{service}.{SERVICE}Api()` — service name ALL CAPS (e.g., `BILLINGApi`, `ECSApi`, `VPCApi`)
368- Request class: `volcenginesdk{service}.{Action}Request(...)` (PascalCase, e.g., `ListAvailableInstancesRequest`)
369- Method: `api_instance.{action_snake_case}(request)` — snake_case (e.g., `list_available_instances`, `describe_instances`)
370- Exception: `from volcenginesdkcore.rest import ApiException`
371
372#### Java
373
374The Java SDK uses `{ServiceName}Api` and `{Action}Request` models under `com.volcengine.{service}`.
375
376```java
377package com.volcengine.sample;
378
379import com.volcengine.ApiClient;
380import com.volcengine.ApiException;
381import com.volcengine.sign.Credentials;
382import com.volcengine.{service}.{ServiceName}Api;
383import com.volcengine.{service}.model.*;
384
385public class Example {
386 public static void main(String[] args) throws Exception {
387 String ak = System.getenv("VOLCENGINE_ACCESS_KEY");
388 String sk = System.getenv("VOLCENGINE_SECRET_KEY");
389 String region = "cn-beijing";
390
391 ApiClient apiClient = new ApiClient()
392 .setCredentials(Credentials.getCredentials(ak, sk))
393 .setRegion(region);
394
395 // [Advanced config — add as needed, see references/sdk-integration-java.md]
396 // Retry: apiClient.setRetrySettings(new RetrySettings().setMaxAttempts(5));
397 // Timeout: apiClient.setConnectionTimeout(5000); apiClient.setReadTimeout(30000);
398 // Proxy: apiClient.setHttpProxy("http://proxy:8080");
399 // Debug: apiClient.setDebugging(true);
400
401 {ServiceName}Api api = new {ServiceName}Api(apiClient);
402
403 {Action}Request request = new {Action}Request();
404 // request.setParamName(value);
405
406 try {
407 {Action}Response resp = api.{actionCamelCase}(request);
408 System.out.println(resp);
409 } catch (ApiException e) {
410 System.out.println(e.getResponseBody());
411 }
412 }
413}
414```
415
416Key points:
417- Package: `com.volcengine.{service}` (lowercase, e.g., `com.volcengine.billing`, `com.volcengine.ecs`)
418- ApiClient: `new ApiClient().setCredentials(Credentials.getCredentials(ak, sk)).setRegion(region)`
419- API class: `{ServiceName}Api` (PascalCase, e.g., `BillingApi`, `EcsApi`) — constructor takes `apiClient`
420- Request class: `{Action}Request` (e.g., `ListAvailableInstancesRequest`) — set params via setters
421- Method: `api.{actionCamelCase}(request)` — camelCase (e.g., `listAvailableInstances`, `describeInstances`)
422- Exception: `ApiException`, use `e.getResponseBody()` for details
423
424#### Node.js
425
426The Node.js SDK uses a command pattern: `{SERVICE}Client` + `{Action}Command`.
427
428```javascript
429import { {SERVICE}Client, {Action}Command } from "@volcengine/{service}";
430
431// Automatically reads VOLCENGINE_ACCESS_KEY and VOLCENGINE_SECRET_KEY from env
432const client = new {SERVICE}Client({
433 region: "cn-beijing",
434 // [Advanced config — add as needed, see references/sdk-integration-nodejs.md]
435 // maxRetries: 5, // retry count
436 // autoRetry: false, // disable auto-retry
437 // httpOptions: { timeout: 30000 }, // timeout (ms)
438 // httpOptions: { proxy: { protocol: "http", host: "127.0.0.1", port: 8888 } }, // proxy
439});
440
441async function main() {
442 try {
443 const command = new {Action}Command({
444 // Set required parameters here
445 });
446 const response = await client.send(command);
447 console.log(JSON.stringify(response, null, 2));
448 } catch (error) {
449 console.error("Error:", error);
450 }
451}
452
453main();
454```
455
456Key points:
457- Package: `@volcengine/{service}` (lowercase, e.g., `@volcengine/ecs`, `@volcengine/vpc`)
458- Client: `{SERVICE}Client` (ALL CAPS service name, e.g., `ECSClient`, `VPCClient`)
459- Command: `{Action}Command` (PascalCase, e.g., `DescribeInstancesCommand`, `CreateVpcCommand`)
460- Invocation: `client.send(command)` — async, returns a Promise
461- Auth: automatically reads `VOLCENGINE_ACCESS_KEY` and `VOLCENGINE_SECRET_KEY` from env; can also pass `accessKeyId`/`secretAccessKey` in the client constructor
462
463#### PHP
464
465The PHP SDK uses classes under the `\Volcengine\{Service}\` namespace.
466
467```php
468<?php
469require_once(__DIR__ . '/vendor/autoload.php');
470
471$config = \Volcengine\Common\Configuration::getDefaultConfiguration()
472 ->setAk(getenv("VOLCENGINE_ACCESS_KEY"))
473 ->setSk(getenv("VOLCENGINE_SECRET_KEY"))
474 ->setRegion("cn-beijing");
475
476// [Advanced config — add as needed, see references/sdk-integration-php.md]
477// Proxy and timeout are configured via GuzzleHttp\Client options
478$httpClient = new GuzzleHttp\Client([
479 // 'proxy' => 'http://proxy:8080', // proxy
480 // 'timeout' => 60, // request timeout (seconds)
481 // 'connect_timeout' => 10, // connection timeout (seconds)
482]);
483
484$apiInstance = new \Volcengine\{Service}\Api\{SERVICE}Api(
485 $httpClient,
486 $config
487);
488
489$request = new \Volcengine\{Service}\Model\{Action}Request();
490// $request->setParamName("value");
491
492try {
493 $resp = $apiInstance->{actionCamelCase}($request);
494 print_r($resp);
495} catch (Exception $e) {
496 echo 'API exception: ', $e->getMessage(), PHP_EOL;
497}
498```
499
500Key points:
501- Config: `\Volcengine\Common\Configuration::getDefaultConfiguration()->setAk()->setSk()->setRegion()`
502- API class: `\Volcengine\{Service}\Api\{SERVICE}Api` — namespace uses PascalCase `Service` (e.g., `Billing`), class name uses ALL CAPS (e.g., `BILLINGApi`)
503- Constructor: takes `GuzzleHttp\Client()` and `$config`
504- Request class: `\Volcengine\{Service}\Model\{Action}Request` (e.g., `\Volcengine\Billing\Model\ListAvailableInstancesRequest`)
505- Set params via setters: `$request->setProduct("value")`
506- Method: `$apiInstance->{actionCamelCase}($request)` (e.g., `listAvailableInstances`)
507
508### Step 5: Present Results
509
510After generating code:
511
5121. Display the complete code in a code block with the correct language tag
5132. List the dependencies the user needs to install (`go get`, `pip install`, `npm install`, `composer require`, Maven/Gradle coordinates)
5143. Remind the user to set environment variables:
515 ```
516 export VOLCENGINE_ACCESS_KEY="your-access-key"
517 export VOLCENGINE_SECRET_KEY="your-secret-key"
518 ```
5194. Note important constraints from the API spec (rate limits, required permissions, data range limits, etc.)
5205. If the code includes advanced configuration, briefly explain each setting's purpose, defaults, and tuning advice. For example:
521 - "Retry defaults to 3 attempts, covers network errors and throttling — adjust via `WithMaxRetries`"
522 - "Connection timeout defaults to 30s; consider increasing for large batch queries"
523
524## Answering SDK Configuration Questions
525
526When the user asks how to configure or use the Volcengine SDK (rather than generate API call code), follow this approach:
527
528### Step 1: Identify the User's Need
529
530Common configuration topics:
531- **Authentication**: AK/SK, STS Token, AssumeRole, OIDC, SAML
532- **Retry**: enable/disable, max attempts, backoff strategy, custom retry conditions
533- **Timeout**: connection timeout, read timeout, per-request timeout
534- **Proxy**: HTTP/HTTPS proxy configuration
535- **Endpoint**: custom endpoint, region-based resolution, dual-stack (IPv6)
536- **SSL/HTTPS**: disable SSL verification, TLS version, HTTP vs. HTTPS
537- **Connection pooling**: pool size, keep-alive, idle connections
538- **Debug**: debug mode, logging, middleware
539- **Error handling**: exception types, retryable vs. non-retryable errors
540- **Environment variables**: supported env vars per SDK
541
542### Step 2: Consult the Reference Documentation
543
544Read the reference file for the user's target language:
545
546| Language | Reference File |
547|----------|---------------|
548| Go | `references/sdk-integration-go.md` |
549| Python | `references/sdk-integration-python.md` |
550| Java | `references/sdk-integration-java.md` |
551| Node.js | `references/sdk-integration-nodejs.md` |
552| PHP | `references/sdk-integration-php.md` |
553
554These files contain concise code examples for each major configuration topic. Read the relevant file and answer with accurate, copy-paste-ready code.
555
556If the user's question is not covered in the reference file or requires more detail, fetch the full upstream documentation from GitHub:
557
558| Language | Upstream Documentation URL |
559|----------|---------------------------|
560| Go | `https://raw.githubusercontent.com/volcengine/volcengine-go-sdk/master/SDK_Integration.md` |
561| Python | `https://raw.githubusercontent.com/volcengine/volcengine-python-sdk/master/SDK_Integration.md` |
562| Java | `https://raw.githubusercontent.com/volcengine/volcengine-java-sdk/master/SDK_Integration.md` |
563| Node.js | `https://raw.githubusercontent.com/volcengine/volcengine-nodejs-sdk/master/SDK_Integration.md` |
564| PHP | `https://raw.githubusercontent.com/volcengine/volcengine-php-sdk/main/SDK_Integration.md` |
565
566### Step 3: Provide a Clear Answer
567
568- Show complete, runnable code snippets demonstrating the configuration
569- Explain each setting's purpose and default value
570- Mention caveats (e.g., "disabling SSL verification is only appropriate in test environments")
571- If the user has not specified a language, ask which one they are using
572- Match the answer language to the user's prompt language
573
574## Important Notes
575
576- Always fetch data from the API Explorer — Volcengine APIs are updated frequently, so the Explorer is the authoritative source. Do not rely on memory.
577- If the user's description is ambiguous (could map to multiple services or operations), list the options and ask for confirmation.
578- If a service has `IsSdkAvailable: false`, inform the user that the official SDK may not yet support this service, and provide a raw HTTP request example as an alternative.
579- For regional services, remind the user to change the region setting if their resources are not in `cn-beijing`.