DOCS / 开发文档

从一次请求开始。

玉米code 提供与 OpenAI 兼容的 HTTP 接口。如果你已经有可用的 SDK，只需要替换端点与密钥；如果从零开始，下面的示例可以直接复制。

API V1 OPENAI COMPATIBLE ZH-CN

本页目录

所有请求都发送到同一个基础地址，通过请求体中的模型标识选择具体模型。演示文档中的域名为示例，接入时请替换为控制台给出的端点。

快速开始

一个最小的调用包含三件事：基础地址、API 密钥，以及一个模型标识。下面以 deepseek-v3.2 为例。

1. 创建密钥

在控制台的 API 密钥页面创建一把新密钥。密钥的查看、复制及停用以控制台实际功能为准。请保存到环境变量或密钥管理服务中，不要写进前端代码或提交到仓库。

2. 配置环境变量

export YUMI_API_KEY="YOUR_NEW_API_TOKEN"
export YUMI_BASE_URL="https://xingying.dev/v1"

import os

api_key = os.environ["YUMI_API_KEY"]
base_url = "https://xingying.dev/v1"

// 在应用启动时读取，不要硬编码
const apiKey = process.env.YUMI_API_KEY;
const baseURL = "https://xingying.dev/v1";

3. 发出第一个请求

curl https://xingying.dev/v1/chat/completions \
  -H "Authorization: Bearer $YUMI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v3.2",
    "messages": [
      {"role": "user", "content": "用三句话介绍你自己"}
    ]
  }'

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["YUMI_API_KEY"],
    base_url="https://xingying.dev/v1",
)

response = client.chat.completions.create(
    model="deepseek-v3.2",
    messages=[{"role": "user", "content": "用三句话介绍你自己"}],
)

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

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.YUMI_API_KEY,
  baseURL: "https://xingying.dev/v1",
});

const response = await client.chat.completions.create({
  model: "deepseek-v3.2",
  messages: [{ role: "user", content: "用三句话介绍你自己" }],
});

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

演示说明：本页仅展示示例代码，不会自动发起模型调用。控制台和 API 已连接真实后端，实际请求按后台配置处理与计费。示例模型名需替换为控制台提供的可用标识。

认证

模型调用接口使用请求头中的 Bearer Token 认证。密钥的额度、有效期、分组及模型限制由控制台配置决定；管理接口使用独立的用户认证机制。

HEADER Authorization: Bearer <YUMI_API_KEY>

不要在前端代码、公开仓库或日志中暴露完整密钥。
为不同项目创建不同密钥，便于单独停用与核算。
发现泄露时，先在控制台停用密钥，再创建新密钥替换。

对话补全

创建一次对话补全。请求与响应结构与 OpenAI Chat Completions 兼容，支持多轮消息、流式输出与常用采样参数。

POST /v1/chat/completions

请求参数

字段	类型	说明
model 必填	string	模型标识符，例如 deepseek-v3.2。完整列表见模型目录。
messages 必填	array	消息数组，每项包含 role 与 content。角色支持 system、user、assistant。
stream	boolean	设为 true 时以 SSE 逐段返回内容。默认 false。
temperature	number	采样温度，0–2。数值越低，输出越稳定。
max_tokens	integer	限制单次回复的最大 token 数。具体上限随模型而定。

响应示例

JSON · 200 OK

{
  "id": "chatcmpl_yumi_7f3a",
  "object": "chat.completion",
  "created": 1792694400,
  "model": "deepseek-v3.2",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "..." },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 96,
    "total_tokens": 124
  }
}

流式输出

把 stream 设为 true，服务端会以 text/event-stream 返回增量内容，直到收到 data: [DONE]。适合聊天界面与需要首字延迟的场景。

curl -N https://xingying.dev/v1/chat/completions \
  -H "Authorization: Bearer $YUMI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v3.2","stream":true,"messages":[{"role":"user","content":"写一段产品介绍"}]}'

stream = client.chat.completions.create(
    model="deepseek-v3.2",
    messages=[{"role": "user", "content": "写一段产品介绍"}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

const stream = await client.chat.completions.create({
  model: "deepseek-v3.2",
  messages: [{ role: "user", content: "写一段产品介绍" }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

网络中断或客户端取消时，建议在应用层记录最后收到的内容，避免把不完整的回复写入数据库。用量按实际生成的 token 计算。

模型列表

返回当前密钥可访问的模型。可以用它来渲染应用内的模型选择器，而不必在客户端硬编码模型名。

GET /v1/models

JSON · 200 OK

{
  "object": "list",
  "data": [
    { "id": "deepseek-v3.2", "owned_by": "deepseek" },
    { "id": "qwen3-max", "owned_by": "qwen" },
    { "id": "claude-sonnet-4.5", "owned_by": "anthropic" }
  ]
}

错误与限流

错误以标准 HTTP 状态码返回，响应体包含 error.type 与 error.message。下表仅为常见错误示例，具体状态码、error.code/type 与 error.message 以后端实际响应为准。

状态码	类型	处理建议
400	invalid_request_error	检查请求体结构与字段类型；确认 messages 非空。
401	invalid_api_key	密钥缺失、格式错误或已停用。重新生成并更新环境变量。
403	以 error.code/type 为准	额度不足或模型未授权。检查余额与密钥的模型范围。
404	model_not_found	模型标识不存在。调用 /v1/models 获取可用列表。
429	rate_limit_exceeded	触发限流。按指数退避重试，并检查并发设置。
502	upstream_error	上游或网关异常。是否重试或切换取决于后台策略；持续失败请检查渠道状态。

限流

限流维度与阈值由后台配置及上游策略决定。收到 429 时，请读取响应头中的重试提示（如存在）并退避，不要在循环中立即重试。

提示：所有示例数据均为演示内容。接入真实服务前，请以控制台中的端点、模型目录与计费规则为准。