Java 快速开始

准备工作

在开始之前，请确保您已完成以下准备：

1. 开通云开发环境：开通云开发环境
2. 获取 API 访问凭证：在 CloudBase 控制台 获取环境 ID 和 API 密钥

更多详情请参考：Java 完整文档

添加 CloudBase AI 开发插件

可选：如果你使用 AI 编程助手（如 Cursor、Claude Code、CodeBuddy 等）进行开发，建议先完成本步骤，让 AI 具备 CloudBase 开发能力。

复制 AI Prompt 粘贴到 AI IDE

在 AI 对话中输入：

帮我把 CloudBase 接好，按下面做：
1. 打开 https://docs.cloudbase.net/skill.md，按说明完成接入。
2. 接入完成后告诉我，并建议最相关的下一步。

查看 skill.md →

使用 Skills 开发

对 AI 说：

使用 CloudBase Skills：在 Java 后端服务中集成 CloudBase HTTP API，包括数据库和存储功能

Skills 使用文档 →

也可以手动安装 CloudBase Skills：

npx skills add tencentcloudbase/cloudbase-skills -y

身份认证

import com.cloudbase.CloudBaseClient;
import com.google.gson.JsonObject;
import java.util.HashMap;
import java.util.Map;

public class Example {
    public static void main(String[] args) {
        CloudBaseClient cloudbase = new CloudBaseClient();

        // 账号密码登录
        Map<String, String> credentials = new HashMap<>();
        credentials.put("username", "your_username");
        credentials.put("password", "your_password");

        JsonObject result = cloudbase.request("POST", "/auth/v1/signin", credentials);

        if (result != null) {
            String accessToken = result.get("access_token").getAsString();
            String refreshToken = result.get("refresh_token").getAsString();
            String userId = result.get("sub").getAsString();

            System.out.println("登录成功! 用户ID: " + userId);
            System.out.println("访问令牌: " + accessToken.substring(0, 20) + "...");
        }
    }
}

云存储

上传文件

import com.cloudbase.CloudBaseClient;
import com.google.gson.JsonArray;
import com.google.gson.JsonObject;
import okhttp3.*;

import java.io.File;
import java.io.IOException;
import java.nio.file.Files;
import java.util.*;

public class Example {
    public static void main(String[] args) throws IOException {
        CloudBaseClient cloudbase = new CloudBaseClient();

        // 上传文件到云存储
        String filePath = "./example.jpg";
        String objectId = "uploads/" + System.currentTimeMillis() + "-" + new File(filePath).getName();

        // 1. 获取上传信息
        List<Map<String, String>> uploadInfoRequest = new ArrayList<>();
        Map<String, String> objectInfo = new HashMap<>();
        objectInfo.put("objectId", objectId);
        uploadInfoRequest.add(objectInfo);

        JsonObject uploadInfoResponse = cloudbase.request("POST", "/v1/storages/get-objects-upload-info", uploadInfoRequest);

        if (uploadInfoResponse == null) {
            System.err.println("获取上传信息失败");
            return;
        }

        JsonObject uploadInfo = uploadInfoResponse.getAsJsonArray().get(0).getAsJsonObject();
        String uploadUrl = uploadInfo.get("uploadUrl").getAsString();
        String authorization = uploadInfo.get("authorization").getAsString();
        String token = uploadInfo.get("token").getAsString();
        String cloudObjectMeta = uploadInfo.get("cloudObjectMeta").getAsString();

        // 2. 上传文件
        File file = new File(filePath);
        byte[] fileData = Files.readAllBytes(file.toPath());

        OkHttpClient client = new OkHttpClient();
        RequestBody requestBody = RequestBody.create(fileData, MediaType.parse("application/octet-stream"));

        Request uploadRequest = new Request.Builder()
                .url(uploadUrl)
                .put(requestBody)
                .addHeader("Authorization", authorization)
                .addHeader("X-Cos-Security-Token", token)
                .addHeader("X-Cos-Meta-Fileid", cloudObjectMeta)
                .build();

        try (Response response = client.newCall(uploadRequest).execute()) {
            if (response.isSuccessful()) {
                String cloudObjectId = uploadInfo.get("cloudObjectId").getAsString();
                String downloadUrl = uploadInfo.get("downloadUrl").getAsString();

                System.out.println("文件上传成功:");
                System.out.println("- 对象ID: " + objectId);
                System.out.println("- 云对象ID: " + cloudObjectId);
                System.out.println("- 下载URL: " + downloadUrl);
            } else {
                System.err.println("文件上传失败: " + response.code());
            }
        }
    }
}

获取文件链接

import com.cloudbase.CloudBaseClient;
import com.google.gson.JsonArray;
import com.google.gson.JsonObject;
import java.util.*;

public class Example {
    public static void main(String[] args) {
        CloudBaseClient cloudbase = new CloudBaseClient();

        // 获取云存储文件的临时访问链接
        String cloudObjectId = "cloud://xxx.png";

        List<Map<String, String>> request = new ArrayList<>();
        Map<String, String> objectInfo = new HashMap<>();
        objectInfo.put("cloudObjectId", cloudObjectId);
        request.add(objectInfo);

        JsonObject result = cloudbase.request("POST", "/v1/storages/get-objects-download-info", request);

        if (result != null) {
            String downloadUrl = result.getAsJsonArray().get(0).getAsJsonObject().get("downloadUrl").getAsString();
            System.out.println("文件链接: " + downloadUrl);
        }
    }
}

下载文件

import com.cloudbase.CloudBaseClient;
import com.google.gson.JsonObject;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;

import java.io.FileOutputStream;
import java.io.IOException;
import java.util.*;

public class Example {
    public static void main(String[] args) throws IOException {
        CloudBaseClient cloudbase = new CloudBaseClient();

        // 下载云存储文件到本地
        String cloudObjectId = "cloud://xxx.png";
        String savePath = "./downloaded.png";

        // 1. 获取下载链接
        List<Map<String, String>> request = new ArrayList<>();
        Map<String, String> objectInfo = new HashMap<>();
        objectInfo.put("cloudObjectId", cloudObjectId);
        request.add(objectInfo);

        JsonObject result = cloudbase.request("POST", "/v1/storages/get-objects-download-info", request);

        if (result == null) {
            System.err.println("获取下载链接失败");
            return;
        }

        String downloadUrl = result.getAsJsonArray().get(0).getAsJsonObject().get("downloadUrl").getAsString();

        // 2. 下载文件
        OkHttpClient client = new OkHttpClient();
        Request downloadRequest = new Request.Builder().url(downloadUrl).build();

        try (Response response = client.newCall(downloadRequest).execute()) {
            if (response.isSuccessful() && response.body() != null) {
                try (FileOutputStream fos = new FileOutputStream(savePath)) {
                    fos.write(response.body().bytes());
                }
                System.out.println("下载成功! 文件已保存到: " + savePath);
            } else {
                System.err.println("下载失败: " + response.code());
            }
        }
    }
}

删除文件

import com.cloudbase.CloudBaseClient;
import com.google.gson.JsonObject;
import java.util.*;

public class Example {
    public static void main(String[] args) {
        CloudBaseClient cloudbase = new CloudBaseClient();

        // 删除云存储文件
        String cloudObjectId = "cloud://xxx.png";

        List<Map<String, String>> request = new ArrayList<>();
        Map<String, String> objectInfo = new HashMap<>();
        objectInfo.put("cloudObjectId", cloudObjectId);
        request.add(objectInfo);

        JsonObject result = cloudbase.request("POST", "/v1/storages/delete-objects", request);

        if (result != null) {
            System.out.println("删除成功!");
        }
    }
}

云函数

import com.cloudbase.CloudBaseClient;
import com.google.gson.JsonObject;
import java.util.HashMap;
import java.util.Map;

public class Example {
    public static void main(String[] args) {
        CloudBaseClient cloudbase = new CloudBaseClient();

        // 调用云函数
        Map<String, Object> data = new HashMap<>();
        // data.put("key", "value"); // 可选参数

        JsonObject result = cloudbase.request("POST", "/v1/functions/{%FUNCTION_NAME%}", data);

        if (result != null) {
            System.out.println("云函数调用结果: " + result);
        }
    }
}

大模型

生文模型

import com.cloudbase.CloudBaseClient;
import com.google.gson.JsonObject;
import okhttp3.*;

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.nio.charset.StandardCharsets;
import java.util.*;

public class Example {
    public static void main(String[] args) throws IOException {
        CloudBaseClient cloudbase = new CloudBaseClient();

        // 流式文本生成
        String model = "{%AI_MODEL_NAME%}";
        String subModel = "{%AI_SUB_MODEL_NAME%}";

        // 准备消息
        List<Map<String, String>> messages = new ArrayList<>();
        Map<String, String> systemMsg = new HashMap<>();
        systemMsg.put("role", "system");
        systemMsg.put("content", "请严格按照七言绝句或七言律诗的格律要求创作，平仄需符合规则，押韵要和谐自然，韵脚字需在同一韵部。");
        messages.add(systemMsg);

        Map<String, String> userMsg = new HashMap<>();
        userMsg.put("role", "user");
        userMsg.put("content", "春天");
        messages.add(userMsg);

        // 准备请求体
        Map<String, Object> payload = new HashMap<>();
        payload.put("model", subModel);
        payload.put("messages", messages);
        payload.put("stream", true);

        // 使用 CloudBaseClient 的配置构建流式请求
        String url = "https://" + cloudbase.getEnvId() + ".api.tcloudbasegateway.com/v1/ai/" + model + "/chat/completions";
        String jsonPayload = cloudbase.getGson().toJson(payload);

        RequestBody requestBody = RequestBody.create(jsonPayload, MediaType.parse("application/json"));

        Request request = new Request.Builder()
                .url(url)
                .post(requestBody)
                .addHeader("Content-Type", "application/json")
                .addHeader("Accept", "text/event-stream")
                .addHeader("Authorization", "Bearer " + cloudbase.getAccessToken())
                .build();

        System.out.println("AI 流式响应:");
        StringBuilder fullContent = new StringBuilder();

        try (Response response = cloudbase.getClient().newCall(request).execute()) {
            if (response.isSuccessful() && response.body() != null) {
                BufferedReader reader = new BufferedReader(
                    new InputStreamReader(response.body().byteStream(), StandardCharsets.UTF_8)
                );
                String line;

                while ((line = reader.readLine()) != null) {
                    if (line.startsWith("data: ")) {
                        String dataStr = line.substring(6);
                        if (!dataStr.trim().equals("[DONE]")) {
                            try {
                                JsonObject chunkData = cloudbase.getGson().fromJson(dataStr, JsonObject.class);
                                if (chunkData.has("choices") && chunkData.getAsJsonArray("choices").size() > 0) {
                                    JsonObject choice = chunkData.getAsJsonArray("choices").get(0).getAsJsonObject();
                                    if (choice.has("delta") && choice.getAsJsonObject("delta").has("content")) {
                                        String content = choice.getAsJsonObject("delta").get("content").getAsString();
                                        System.out.print(content);
                                        fullContent.append(content);
                                    }
                                }
                            } catch (Exception e) {
                                // 忽略JSON解析错误
                            }
                        }
                    }
                }
                System.out.println(); // 换行
            }
        }
    }
}

生图模型

生图模型通过调用云函数来实现，在生图模型页面点击「一键创建云函数」，函数调用示例如下：

import com.cloudbase.CloudBaseClient;
import com.google.gson.JsonObject;
import java.util.HashMap;
import java.util.Map;

public class Example {
    public static void main(String[] args) {
        CloudBaseClient cloudbase = new CloudBaseClient();

        try {
            // 准备调用参数
            Map<String, Object> data = new HashMap<>();
            data.put("prompt", "一只可爱的猫咪在阳光下玩耍");

            // 调用云函数生成图片
            JsonObject result = cloudbase.request("POST", "/v1/functions/<YOUR_FUNCTION_NAME>", data);

            if (result != null) {
                boolean success = result.has("success") && result.get("success").getAsBoolean();
                
                if (success) {
                    String imageUrl = result.get("imageUrl").getAsString();
                    String revisedPrompt = result.has("revised_prompt") 
                        ? result.get("revised_prompt").getAsString() 
                        : "";
                    
                    System.out.println("生成成功!");
                    System.out.println("图片URL: " + imageUrl);
                    System.out.println("优化后的提示词: " + revisedPrompt);
                    System.out.println("注意: 图片URL有效期为24小时");
                } else {
                    String code = result.has("code") ? result.get("code").getAsString() : "";
                    String message = result.has("message") ? result.get("message").getAsString() : "";
                    System.err.println("生成失败: " + code + " - " + message);
                }
            } else {
                System.err.println("请求失败");
            }
        } catch (Exception e) {
            System.err.println("生成图片时出错: " + e.getMessage());
        }
    }
}