开发者文档

接入黑云 API Hub，快速集成主流 AI 模型。

快速开始

1. 注册账号

访问 https://2685336309.icu 注册黑云账户。新用户注册即获赠 100,000 Token 免费额度，无需信用卡，开箱即用。

2. 创建 API Key

登录 黑云控制台，在「API 密钥」页面创建一个新的密钥。请妥善保管 API Key，创建后仅显示一次。

3. 发起首次 API 请求

获得 API Key 后，使用以下命令进行首次调用：

curl https://2685336309.icu/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-chat",
    "messages": [{"role": "user", "content": "你好，请介绍一下自己"}]
  }'

认证方式

Bearer Token 认证

黑云 API 采用标准的 Bearer Token 认证方式。所有请求必须在 HTTP Header 中包含 Authorization 字段：

Authorization: Bearer sk-你的API密钥

安全建议

• 切勿将 API Key 暴露在客户端代码（前端 JavaScript、移动端应用）中
• 建议将 API Key 存储在环境变量或密钥管理服务中
• 定期轮换 API Key，降低泄露风险
• 可以为不同项目创建独立的 API Key 以实现权限隔离
• 监控控制台中的用量统计，留意异常调用模式

模型列表

黑云支持多个渠道的 AI 模型。每个模型有独立的定价和上下文长度限制。以下为完整价格表。

DeepSeek

Kimi Moonshot

通义千问 Alibaba Qwen

智谱 ChatGLM

SiliconFlow

MXAPI-AI

API 参考 — 聊天补全

黑云 API 完全兼容 OpenAI 的 Chat Completions 接口格式，主流 SDK 无需额外适配即可使用。

POST /v1/chat/completions

创建一个聊天补全请求。

请求参数

请求示例

cURL

curl https://2685336309.icu/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-chat",
    "messages": [
      {"role": "system", "content": "你是一位助手"},
      {"role": "user", "content": "介绍一下大模型的基本原理"}
    ],
    "max_tokens": 1024,
    "temperature": 0.7
  }'

Python

from openai import OpenAI

client = OpenAI(
    base_url="https://2685336309.icu/v1",
    api_key="sk-your-api-key"
)

response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[
        {"role": "system", "content": "你是一位助手"},
        {"role": "user", "content": "介绍一下大模型的基本原理"}
    ],
    max_tokens=1024,
    temperature=0.7
)

print(response.choices[0].message.content)

Node.js

import OpenAI from 'openai';

const client = new OpenAI({
    baseURL: 'https://2685336309.icu/v1',
    apiKey: 'sk-your-api-key'
});

const response = await client.chat.completions.create({
    model: 'deepseek-chat',
    messages: [
        {role: 'system', content: '你是一位助手'},
        {role: 'user', content: '介绍一下大模型的基本原理'}
    ],
    max_tokens: 1024,
    temperature: 0.7
});

console.log(response.choices[0].message.content);

Java (OkHttp)

// Maven 依赖：
// com.squareup.okhttp3:okhttp:4.12.0
// com.google.code.gson:gson:2.10.1

import okhttp3.*;
import com.google.gson.JsonObject;
import java.io.IOException;

public class ChatCompletionExample {
    public static void main(String[] args) throws IOException {
        OkHttpClient client = new OkHttpClient();

        JsonObject body = new JsonObject();
        body.addProperty("model", "deepseek-chat");

        JsonObject msg = new JsonObject();
        msg.addProperty("role", "user");
        msg.addProperty("content", "介绍一下大模型的基本原理");
        body.add("messages", new com.google.gson.JsonArray());
        body.getAsJsonArray("messages").add(msg);

        Request request = new Request.Builder()
            .url("https://2685336309.icu/v1/chat/completions")
            .addHeader("Authorization", "Bearer sk-your-api-key")
            .addHeader("Content-Type", "application/json")
            .post(RequestBody.create(
                MediaType.parse("application/json"),
                body.toString()
            ))
            .build();

        try (Response response = client.newCall(request).execute()) {
            System.out.println(response.body().string());
        }
    }
}

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

func main() {
    requestBody, _ := json.Marshal(map[string]interface{}{
        "model": "deepseek-chat",
        "messages": []map[string]string{
            {"role": "user", "content": "介绍一下大模型的基本原理"},
        },
        "max_tokens":  1024,
        "temperature": 0.7,
    })

    req, _ := http.NewRequest(
        "POST",
        "https://2685336309.icu/v1/chat/completions",
        bytes.NewBuffer(requestBody),
    )
    req.Header.Set("Authorization", "Bearer sk-your-api-key")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        fmt.Println("Error:", err)
        return
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

响应格式

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1680000000,
  "model": "deepseek-chat",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "大模型..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 200,
    "total_tokens": 215
  }
}

流式响应

设置 stream: true 即可启用流式响应，API 会以 Server-Sent Events (SSE) 格式逐块返回数据。每个数据块包含一个 delta 字段而非 message。

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"大"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"模型"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

API 参考 — 图像生成

通过图像生成 API，可以将文本描述转换为图像。兼容 OpenAI DALL-E 接口风格。

POST /v1/images/generations

curl https://2685336309.icu/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dall-e-3",
    "prompt": "一只橘猫坐在服务器机房里，科技感，数字艺术",
    "n": 1,
    "size": "1024x1024"
  }'

多语言 SDK 示例

以下为各语言的完整可运行示例。只需替换 your-api-key 为真实 API Key 即可。

Python

使用 OpenAI 官方 Python SDK：

from openai import OpenAI

client = OpenAI(
    base_url="https://2685336309.icu/v1",
    api_key="your-api-key"
)

response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[{"role": "user", "content": "你好"}]
)

print(response.choices[0].message.content)

Node.js

使用 OpenAI 官方 Node.js SDK：

import OpenAI from 'openai';

const client = new OpenAI({
    baseURL: 'https://2685336309.icu/v1',
    apiKey: 'your-api-key'
});

const response = await client.chat.completions.create({
    model: 'deepseek-chat',
    messages: [{role: 'user', content: '你好'}]
});

console.log(response.choices[0].message.content);

cURL

curl https://2685336309.icu/v1/chat/completions \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-chat","messages":[{"role":"user","content":"你好"}]}'

Java (OkHttp)

在 pom.xml 中添加依赖：

<dependency>
    <groupId>com.squareup.okhttp3</groupId>
    <artifactId>okhttp</artifactId>
    <version>4.12.0</version>
</dependency>
<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>2.10.1</version>
</dependency>

Java 源代码：

import okhttp3.*;
import com.google.gson.JsonObject;
import com.google.gson.JsonArray;
import java.io.IOException;

public class BlackCloudChat {
    public static void main(String[] args) throws IOException {
        OkHttpClient client = new OkHttpClient();

        JsonObject msg = new JsonObject();
        msg.addProperty("role", "user");
        msg.addProperty("content", "你好");

        JsonArray messages = new JsonArray();
        messages.add(msg);

        JsonObject body = new JsonObject();
        body.addProperty("model", "deepseek-chat");
        body.add("messages", messages);

        Request request = new Request.Builder()
            .url("https://2685336309.icu/v1/chat/completions")
            .addHeader("Authorization", "Bearer your-api-key")
            .addHeader("Content-Type", "application/json")
            .post(RequestBody.create(
                MediaType.parse("application/json"),
                body.toString()
            ))
            .build();

        try (Response response = client.newCall(request).execute()) {
            System.out.println(response.body().string());
        }
    }
}

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

func main() {
    body := map[string]interface{}{
        "model": "deepseek-chat",
        "messages": []map[string]string{
            {"role": "user", "content": "你好"},
        },
    }

    jsonData, _ := json.Marshal(body)

    req, _ := http.NewRequest(
        "POST",
        "https://2685336309.icu/v1/chat/completions",
        bytes.NewBuffer(jsonData),
    )
    req.Header.Set("Authorization", "Bearer your-api-key")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        fmt.Println("请求失败:", err)
        return
    }
    defer resp.Body.Close()

    respBody, _ := io.ReadAll(resp.Body)
    fmt.Println(string(respBody))
}

错误码说明

使用限制

频率限制

为保障服务稳定性，API 接口有以下频率限制：

• 标准用户：每分钟最多 60 次请求
• 高级用户：每分钟最多 300 次请求（需联系申请）
• 图像生成：每分钟最多 10 次请求

上下文长度

不同模型的上下文长度不同，详见上方 模型列表。超出上下文长度的请求会被截断或拒绝。

额度计算

费用按实际消耗的 Token 数量进行计费。Token 是模型处理文本的基本单位，一般约 750 个汉字 ≈ 1000 tokens。

最佳实践

• 为生成类任务设置合理的 max_tokens，避免不必要的输出消耗
• 使用短而精确的提示词，减少输入 token 消耗
• 利用 stream 模式优化用户体验，首字延迟更低
• 实现指数退避重试机制处理 429/500 错误