vitepress/apidoc/guide/api-reference.md

# AI 模型接口文档 

IkunCode API 兼容 OpenAI 接口协议，一个 Key 即可调用 Claude、GPT、Gemini、DeepSeek 等主流模型。

## 接口基础信息 

项目| 说明  
---|---  
**Base URL**| `https://api.oneinai.com/v1`  
**认证方式**|  Bearer Token  
**协议兼容**|  OpenAI API 格式  
  
所有请求均需在 Header 中携带认证信息：
    
    
    Authorization: Bearer sk-你的API Key
    Content-Type: application/json

1  
2  

## 模型列表 

获取当前可用的模型列表。

**请求**
    
    
     GET https://api.oneinai.com/v1/models

1  

**示例**

bash
    
    
    curl https://api.oneinai.com/v1/models \\
      -H "Authorization: Bearer sk-xxxx"

1  
2  

**响应**

json
    
    
    {
      "object": "list",
      "data": [
        {
          "id": "claude-sonnet-4-20250514",
          "object": "model",
          "created": 1700000000,
          "owned_by": "anthropic"
        }
      ]
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

## 聊天完成 

对话补全接口，最常用的 AI 对话接口。

**请求**
    
    
     POST https://api.oneinai.com/v1/chat/completions

1  

**请求参数**

参数| 类型| 必填| 默认值| 说明  
---|---|---|---|---  
model| string| 是| -| 模型名称，如 `claude-sonnet-4-20250514`  
messages| array| 是| -| 对话消息列表  
temperature| number| 否| 1.0| 采样温度，0~2，越低越确定  
top_p| number| 否| 1.0| 核采样参数，0~1  
max_tokens| integer| 否| 4096| 最大生成 token 数  
stream| boolean| 否| false| 是否启用流式输出  
presence_penalty| number| 否| 0| 存在惩罚，-2.0~2.0  
frequency_penalty| number| 否| 0| 频率惩罚，-2.0~2.0  
stop| array/string| 否| null| 停止序列  
tools| array| 否| null| 工具/函数调用定义  
tool_choice| string/object| 否| "auto"| 工具选择策略  
  
**messages 结构**

json
    
    
    {
      "role": "system" | "user" | "assistant" | "tool",
      "content": "消息内容"
    }

1  
2  
3  
4  

支持的 role 类型：

  * **system** ：系统提示，设定 AI 角色和行为
  * **user** ：用户输入
  * **assistant** ：模型回复（多轮对话上下文）
  * **tool** ：工具调用返回结果

**示例请求（cURL）**

bash
    
    
    curl -X POST "https://api.oneinai.com/v1/chat/completions" \\
      -H "Content-Type: application/json" \\
      -H "Authorization: Bearer sk-xxxx" \\
      -d '{
        "model": "claude-sonnet-4-20250514",
        "messages": [
          {
            "role": "system",
            "content": "你是一个有帮助的AI助手。"
          },
          {
            "role": "user",
            "content": "你好，请介绍一下自己。"
          }
        ],
        "temperature": 0.7,
        "max_tokens": 1024,
        "stream": false
      }'

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  

**示例请求（Python）**

python
    
    
    from openai import OpenAI
    
    client = OpenAI(
        api_key="sk-xxxx",
        base_url="https://api.oneinai.com/v1"
    )
    
    response = client.chat.completions.create(
        model="claude-sonnet-4-20250514",
        messages=[
            {"role": "system", "content": "你是一个有帮助的AI助手。"},
            {"role": "user", "content": "你好，请介绍一下自己。"}
        ],
        temperature=0.7,
        max_tokens=1024
    )
    
    print(response.choices[0].message.content)

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  

**示例请求（Node.js）**

javascript
    
    
    import OpenAI from 'openai';
    
    const client = new OpenAI({
      apiKey: 'sk-xxxx',
      baseURL: 'https://api.oneinai.com/v1',
    });
    
    const response = await client.chat.completions.create({
      model: 'claude-sonnet-4-20250514',
      messages: [
        { role: 'system', content: '你是一个有帮助的AI助手。' },
        { role: 'user', content: '你好，请介绍一下自己。' },
      ],
      temperature: 0.7,
      max_tokens: 1024,
    });
    
    console.log(response.choices[0].message.content);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  

**响应格式（非流式）**

json
    
    
    {
      "id": "chatcmpl-abc123",
      "object": "chat.completion",
      "created": 1677858242,
      "model": "claude-sonnet-4-20250514",
      "choices": [
        {
          "index": 0,
          "message": {
            "role": "assistant",
            "content": "你好！我是一个AI助手，很高兴为你服务。"
          },
          "finish_reason": "stop"
        }
      ],
      "usage": {
        "prompt_tokens": 28,
        "completion_tokens": 18,
        "total_tokens": 46
      }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  

**流式响应（stream=true）**

采用 Server-Sent Events (SSE) 格式，每行以 `data: ` 开头，最后以 `data: [DONE]` 结束。

json
    
    
    data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1690000000,"model":"claude-sonnet-4-20250514","choices":[{"index":0,"delta":{"role":"assistant","content":"你"},"finish_reason":null}]}
    
    data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1690000000,"model":"claude-sonnet-4-20250514","choices":[{"index":0,"delta":{"content":"好"},"finish_reason":null}]}
    
    data: [DONE]

1  
2  
3  
4  
5  

## 文本嵌入 

文本嵌入向量生成接口，用于语义搜索、文本相似度计算等场景。

**请求**
    
    
     POST https://api.oneinai.com/v1/embeddings

1  

**请求参数**

参数| 类型| 必填| 说明  
---|---|---|---  
model| string| 是| 嵌入模型名称  
input| string/array| 是| 待嵌入的文本或文本数组  
encoding_format| string| 否| 返回格式，`float` 或 `base64`  
  
**示例**

bash
    
    
    curl -X POST "https://api.oneinai.com/v1/embeddings" \\
      -H "Content-Type: application/json" \\
      -H "Authorization: Bearer sk-xxxx" \\
      -d '{
        "model": "text-embedding-3-small",
        "input": "你好世界"
      }'

1  
2  
3  
4  
5  
6  
7  

**响应**

json
    
    
    {
      "object": "list",
      "data": [
        {
          "object": "embedding",
          "index": 0,
          "embedding": [0.0023, -0.0094, 0.0156, ...]
        }
      ],
      "model": "text-embedding-3-small",
      "usage": {
        "prompt_tokens": 4,
        "total_tokens": 4
      }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  

## 图像生成 

AI 图像生成接口。

**请求**
    
    
     POST https://api.oneinai.com/v1/images/generations

1  

**请求参数**

参数| 类型| 必填| 说明  
---|---|---|---  
model| string| 是| 图像模型名称  
prompt| string| 是| 图像描述文本  
n| integer| 否| 生成图片数量，默认 1  
size| string| 否| 图片尺寸，如 `1024x1024`  
response_format| string| 否| 返回格式，`url` 或 `b64_json`  
  
**示例**

bash
    
    
    curl -X POST "https://api.oneinai.com/v1/images/generations" \\
      -H "Content-Type: application/json" \\
      -H "Authorization: Bearer sk-xxxx" \\
      -d '{
        "model": "dall-e-3",
        "prompt": "一只可爱的猫咪坐在窗台上看雪景",
        "n": 1,
        "size": "1024x1024"
      }'

1  
2  
3  
4  
5  
6  
7  
8  
9  

**响应**

json
    
    
    {
      "created": 1700000000,
      "data": [
        {
          "url": "https://...",
          "revised_prompt": "..."
        }
      ]
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  

## 语音接口 

### 语音转文字 (STT) 
    
    
    POST https://api.oneinai.com/v1/audio/transcriptions

1  

### 文字转语音 (TTS) 
    
    
    POST https://api.oneinai.com/v1/audio/speech

1  

**TTS 示例**

bash
    
    
    curl -X POST "https://api.oneinai.com/v1/audio/speech" \\
      -H "Content-Type: application/json" \\
      -H "Authorization: Bearer sk-xxxx" \\
      -d '{
        "model": "tts-1",
        "input": "你好，欢迎使用 IkunCode。",
        "voice": "alloy"
      }' \\
      --output speech.mp3

1  
2  
3  
4  
5  
6  
7  
8  
9  

## 错误码参考 

状态码| 错误类型| 说明  
---|---|---  
400| invalid_request_error| 请求参数错误  
401| authentication_error| API Key 无效或过期  
403| permission_error| 无权访问该模型  
429| rate_limit_exceeded| 超过速率限制或余额不足  
500| internal_server_error| 服务端异常，请稍后重试  
502/504| gateway_error| 网关超时  
  
**错误响应格式**

json
    
    
    {
      "error": {
        "message": "错误详细信息",
        "type": "invalid_request_error",
        "code": "invalid_api_key"
      }
    }

1  
2  
3  
4  
5  
6  
7  

## 使用建议 

💡 最佳实践

  * **system 提示** 尽量精简明确，避免过长
  * **多轮对话** 时完整保留上下文历史
  * 生产环境始终设置合理的 `max_tokens` 和 `temperature`
  * 推荐使用官方 SDK（Python `openai`、Node.js `openai`）简化开发
  * 不同模型的上下文长度和能力差异较大，请根据需求选择

⚠️ 注意

请将示例中的 `sk-xxxx` 替换为你的真实 API Key。请勿将 Key 提交到公开代码仓库。