API 接口调用文档

本文面向需要通过代码、脚本、后端服务或自动化工具调用哈基米 API 的开发者。本站接口整体兼容 OpenAI 常用调用格式，同时提供 Gemini、Anthropic、图像、音频、视频等不同类型的接口入口。

快速接入

步骤 1：准备 API Key

INFO

先在控制台创建并复制令牌。令牌通常以 sk- 开头，请妥善保管，不要放进前端代码、公开仓库或截图中。

如果还没有令牌，请先阅读 快速开始。

步骤 2：确认接口地址

INFO

代码里直接请求具体接口时，请使用完整地址。不同软件填写 Base URL 时可能会自动拼接 /v1，但自己写请求时需要把完整路径写清楚。

场景	推荐填写
OpenAI 兼容 Base URL	https://api.gemai.cc/v1
直接请求完整接口	https://api.gemai.cc/v1/chat/completions
部分客户端 API Host	https://api.gemai.cc

步骤 3：添加鉴权请求头

INFO

绝大多数接口都使用 Bearer Token 鉴权。请求头中需要带上 Authorization 和 Content-Type。

Authorization: Bearer sk-你的令牌
Content-Type: application/json

步骤 4：选择合适的模型

INFO

请求中的 model 需要填写本站模型列表里的完整模型名。聊天、图像、向量、语音等接口可用模型不同，请优先以控制台或模型广场展示为准。

常用模型选择可以参考 模型分类一览。

接口分类

分类	独立接口页	适合场景
OpenAI 对话	Chat Completions、Responses	普通对话、多模态输入、流式输出、新版响应格式
OpenAI 图像	Images Generations、Images Edits	文生图、图生图、图片编辑
OpenAI 音频	Audio Speech、Audio Transcriptions	文本转语音、语音转文本
OpenAI 向量	Embeddings	文本向量化、RAG、相似度检索
Gemini 接口	Generate Content、图片 Generate Content	Gemini 原生对话、生图、改图
Anthropic 接口	Messages	Claude 对话、长上下文、缓存统计
Flux 出图	生成图像、查询任务、提示词生成	Flux 文生图、异步查询、提示词优化
视频生成	异步视频生成、任务状态、视频内容、Remix	通用视频任务提交、查询和下载
Sora-2	创建角色	创建可复用视频角色
Seedance 2.0	豆包原生提交、豆包原生查询、OpenAI 兼容提交、OpenAI 兼容查询、任务进度、任务结果	豆包原生、OpenAI 兼容和视频内容查询

通用请求示例

下面是最小可用的聊天请求，适合用来检查 Key、模型名和接口地址是否可用。代码示例默认从环境变量 GEMAI_API_KEY 读取密钥。

cURL

curl --location 'https://api.gemai.cc/v1/chat/completions' \
  --header "Authorization: Bearer $GEMAI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "[官逆]gemini-2.5-pro",
    "messages": [
      {
        "role": "user",
        "content": "你好，请简单介绍一下你自己。"
      }
    ]
  }'

JavaScript

const response = await fetch('https://api.gemai.cc/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.GEMAI_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: '[官逆]gemini-2.5-pro',
    messages: [
      { role: 'user', content: '你好，请简单介绍一下你自己。' },
    ],
  }),
})

const data = await response.json()
console.log(data.choices?.[0]?.message?.content)

Python

import os
import requests

response = requests.post(
    'https://api.gemai.cc/v1/chat/completions',
    headers={
        'Authorization': f"Bearer {os.environ['GEMAI_API_KEY']}",
        'Content-Type': 'application/json',
    },
    json={
        'model': '[官逆]gemini-2.5-pro',
        'messages': [
            {'role': 'user', 'content': '你好，请简单介绍一下你自己。'},
        ],
    },
    timeout=120,
)

response.raise_for_status()
data = response.json()
print(data['choices'][0]['message']['content'])

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class GemaiChatExample {
    public static void main(String[] args) throws Exception {
        String apiKey = System.getenv("GEMAI_API_KEY");
        String body = """
            {
              "model": "[官逆]gemini-2.5-pro",
              "messages": [
                {
                  "role": "user",
                  "content": "你好，请简单介绍一下你自己。"
                }
              ]
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.gemai.cc/v1/chat/completions"))
            .header("Authorization", "Bearer " + apiKey)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println(response.body());
    }
}

Go

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{
		"model": "[官逆]gemini-2.5-pro",
		"messages": [
			{
				"role": "user",
				"content": "你好，请简单介绍一下你自己。"
			}
		]
	}`)

	req, err := http.NewRequest(
		http.MethodPost,
		"https://api.gemai.cc/v1/chat/completions",
		bytes.NewReader(body),
	)
	if err != nil {
		panic(err)
	}

	req.Header.Set("Authorization", "Bearer "+os.Getenv("GEMAI_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	data, err := io.ReadAll(resp.Body)
	if err != nil {
		panic(err)
	}

	fmt.Println(string(data))
}

Rust

use reqwest::Client;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api_key = std::env::var("GEMAI_API_KEY")?;

    let response = Client::new()
        .post("https://api.gemai.cc/v1/chat/completions")
        .bearer_auth(api_key)
        .json(&json!({
            "model": "[官逆]gemini-2.5-pro",
            "messages": [
                {
                    "role": "user",
                    "content": "你好，请简单介绍一下你自己。"
                }
            ]
        }))
        .send()
        .await?
        .text()
        .await?;

    println!("{response}");
    Ok(())
}

常见状态码

状态码	含义	排查建议
200	请求成功	正常读取返回内容
400	请求参数错误	检查 model、messages、图片/音频字段格式
401	鉴权失败	检查 API Key 是否完整、是否带 Bearer 前缀
429	请求过于频繁或额度受限	降低并发，检查余额、令牌限制和模型可用性
500 / 502 / 503	服务或上游异常	稍后重试，或临时切换其他模型

注意事项

• API Key 只应放在服务端环境变量中，不要写入网页前端或公开客户端。
• 请求地址不要混用：直接请求完整接口时用 https://api.gemai.cc/v1/...，客户端自动拼路径时按对应教程填写。
• 如果返回“分组下模型无可用渠道”“正在加号请稍等”等提示，通常是上游渠道暂时不可用，请参考 常见问题。
• 流式响应需要设置 stream: true，并让客户端按 SSE 格式逐段读取返回内容。