跳到主要内容

API 参考

Knox 的请求和响应模式与 OpenAI Chat API 非常相似，仅有少量差异。从整体来看，Knox 在不同模型和提供商之间标准化了 schema，因此您只需要学习一套接口。

基础 URL​

所有 API 请求应发送到以下基础 URL：

https://api.knox.chat/v1

身份验证​

每个 API 请求都需要在请求头中包含您的 API key：

Authorization: Bearer sk-...

您可以在 Knox Token 页面查找或创建 API key。

主要端点​

Knox API 包含以下主要端点：

文本生成​

Jev（System One）​

结构化决策，而不是生成文本。提交 state 和 typed questions，得到代码可直接分支的 answers。这不是聊天补全。详见 Jev 指南。

模型信息​

实时语音​

通过 WebSocket 进行语音到语音的 Voice Agent（gpt-realtime-2.1、gpt-realtime-2.1-mini）。这不是对话补全。会话配置、计费和托管联网搜索请参阅 实时语音 指南。

视频生成​

视频生成是异步的：提交任务、轮询直到完成，然后下载文件。完整流程请参阅 视频生成 指南。

音乐生成​

根据提示词或作曲计划生成原创歌曲。这些路由面向 KnoxStudio，Base URL 为 https://api.knoxstudio.ai/v1（与 https://api.knox.chat/v1 共用同一后端）。完整流程请参阅 音乐生成 指南。

文本转语音​

使用 ElevenLabs 音色将文本转为音频。Base URL：https://api.knoxstudio.ai/v1。认证使用 Authorization: Bearer sk-... 或 xi-api-key。完整流程请参阅 文本转语音 指南。

语音转文本​

使用 Scribe 转写音频或视频。Base URL：https://api.knoxstudio.ai/v1。完整流程请参阅 语音转文本 指南。

音色​

搜索、克隆和管理 ElevenLabs 音色。Base URL：https://api.knoxstudio.ai/v1（搜索用 GET /v2/voices）。不按音频分钟计费。完整流程请参阅 音色 指南。

语音转换​

用目标 voice_id 改写源音频。Base URL：https://api.knoxstudio.ai/v1。按 每分钟 $0.17 计费。完整流程请参阅 语音转换 指南。

人声分离​

从混合音频或视频中分离人声。Base URL：https://api.knoxstudio.ai/v1。按 每分钟 $0.17 计费。完整流程请参阅 人声分离 指南。

音效生成​

根据文本生成短免版税片段。Base URL：https://api.knoxstudio.ai/v1。按 每分钟 $0.17 计费。完整流程请参阅 音效生成 指南。

配音​

把源音频或视频配成另一种语言。Base URL：https://api.knoxstudio.ai/v1。创建项目时预收第一种语言（dubbing_v2 每分钟 $2.25，dubbing_v1 每分钟 $0.38）。完整流程请参阅 配音 指南。

强制对齐​

将语音与转写对齐。Base URL：https://api.knoxstudio.ai/v1。按 每小时 $0.27 计费。完整流程请参阅 强制对齐 指南。

参数​

Knox 支持多种参数来控制模型行为和输出。详情请参阅 API 参数 章节。

错误处理​

API 使用标准 HTTP 状态码来表示请求的结果：

  • 200 - 请求成功
  • 202 - 请求已接受（异步视频生成）
  • 400 - 请求参数无效或缺失（包括未升级 WebSocket 就访问 WebSocket 端点）
  • 401 - 身份验证失败（API key 无效或已过期）
  • 402 - 账户余额不足
  • 403 - Token 无权使用请求的模型
  • 404 - 请求的资源未找到
  • 422 - 校验错误（Jev、音乐、文本转语音、语音转文本、音色、语音转换、人声分离、音效、配音、强制对齐）
  • 429 - 超出速率限制
  • 500 - 服务器内部错误
  • 502 - 上游提供商不可用或连接失败
  • 529 - 上游 Jev 过载；请退避重试

视频生成端点的错误格式为 { "error": { "code": 400, "message": "..." } }。status: "failed" 的轮询响应仍然是 HTTP 200。

Jev（POST /v1/systemone）以及音乐、文本转语音、语音转文本、音色、语音转换、人声分离、音效、配音和强制对齐端点返回 { "detail": "..." }，或 422 时为 { "detail": [{ "loc": [...], "msg": "...", "type": "value_error" }] }。音频路由除 Authorization: Bearer 外还接受 xi-api-key。Jev 仅使用 Knox Bearer 认证。

请求​

输出生成请求格式​

以下是请求 schema 的 TypeScript 类型定义。当您向 /v1/chat/completions 端点发送 POST 请求时，它将作为请求体使用（参见上方的 快速开始 示例）。

有关完整的参数列表，请参阅 Parameters 章节。

// Definitions of subtypes are below
type Request = {
  // Either "messages" or "prompt" is required
  messages?: Message[];
  prompt?: string;

  // If "model" is unspecified, uses the user's default
  model?: string; // See "Supported Models" section

  // Allows to force the model to produce specific output format.
  // See models page and note on this docs page for which models support it.
  response_format?: { type: 'json_object' };

  stop?: string | string[];
  stream?: boolean; // Enable streaming

  // See LLM Parameters (docs.knox.chat/api-reference/parameters)
  max_tokens?: number; // Range: [1, context_length)
  temperature?: number; // Range: [0, 2]

  // Tool calling
  // Will be passed down as-is for providers implementing OpenAI's interface.
  // For providers with custom interfaces, we transform and map the properties.
  // Otherwise, we transform the tools into a YAML template. The model responds with an assistant message.
  tools?: Tool[];
  tool_choice?: ToolChoice;

  // Advanced optional parameters
  seed?: number; // Integer only
  top_p?: number; // Range: (0, 1]
  top_k?: number; // Range: [1, Infinity) Not available for OpenAI models
  frequency_penalty?: number; // Range: [-2, 2]
  presence_penalty?: number; // Range: [-2, 2]
  repetition_penalty?: number; // Range: (0, 2]
  logit_bias?: { [key: number]: number };
  top_logprobs: number; // Integer only
  min_p?: number; // Range: [0, 1]
  top_a?: number; // Range: [0, 1]

  // Reduce latency by providing the model with a predicted output
  // https://platform.openai.com/docs/guides/latency-optimization#use-predicted-outputs
  prediction?: { type: 'content'; content: string };

  // Knox-only parameters
  // See "Prompt Transforms" section: docs.knox.chat/message-transforms
  transforms?: string[];
  // See "Model Routing" section: docs.knox.chat/model-routing
  models?: string[];
  route?: 'fallback';
  // See "Provider Routing" section: docs.knox.chat/provider-routing
  provider?: ProviderPreferences;
};

// Subtypes:

type TextContent = {
  type: 'text';
  text: string;
};

type ImageContentPart = {
  type: 'image_url';
  image_url: {
    url: string; // URL or base64 encoded image data
    detail?: string; // Optional, defaults to "auto"
  };
};

type ContentPart = TextContent | ImageContentPart;

type Message =
  | {
      role: 'user' | 'assistant' | 'system';
      // ContentParts are only for the "user" role:
      content: string | ContentPart[];
      // If "name" is included, it will be prepended like this
      // for non-OpenAI models: `{name}: {content}`
      name?: string;
    }
  | {
      role: 'tool';
      content: string;
      tool_call_id: string;
      name?: string;
    };

type FunctionDescription = {
  description?: string;
  name: string;
  parameters: object; // JSON Schema object
};

type Tool = {
  type: 'function';
  function: FunctionDescription;
};

type ToolChoice =
  | 'none'
  | 'auto'
  | {
      type: 'function';
      function: {
        name: string;
      };
    };

response_format 参数确保您从大语言模型（LLM）接收到结构化响应。此参数仅受 OpenAI 模型、Nitro 模型以及其他部分模型支持。

:::info 非标准参数 如果所选模型不支持某个请求参数（例如，非 OpenAI 模型中的 logit_bias，或 OpenAI 中的 top_k），该参数将被忽略。 其余参数将被转发到底层模型 API。 :::

预填充助手消息​

Knox 支持让模型续写部分响应。这可以用来引导模型以特定方式回答。

要使用此功能，只需在 messages 数组的末尾添加一条 role: "assistant" 的消息。

TypeScript
fetch('https://api.knox.chat/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <KNOXCHAT_API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'openai/gpt-5.2',
    messages: [
      { role: 'user', content: 'What is the meaning of life?' },
      { role: 'assistant', content: "I'm not sure, but my best guess is" },
    ],
  }),
});

图像与多模态​

图像等多模态请求通过 /v1/chat/completions API 实现，需要多部分的 messages 参数。image_url 可以是 URL 或 Base64 编码的图像数据。实时语音到语音请使用 /v1/realtime。

"messages": [
  {
    "role": "user",
    "content": [
      {
        "type": "text",
        "text": "What's in this image?"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
        }
      }
    ]
  }
]

LLM 响应示例：

{
  "choices": [
    {
      "role": "assistant",
      "content": "This image depicts a scenic natural landscape featuring a long wooden boardwalk that stretches out through an expansive field of green grass. The boardwalk provides a clear path and invites exploration through the lush environment. The scene is surrounded by a variety of shrubbery and trees in the background, indicating a diverse plant life in the area."
    }
  ]
}

图像生成​

部分模型支持原生图像生成能力。要生成图像，您可以在请求中添加 modalities: ["image", "text"]。模型将以 OpenAI ContentPartImage 格式返回图像，其中 image_url 包含 Base64 data URL。

{
  "model": "openai/dall-e-3",
  "messages": [
    {
      "role": "user",
      "content": "Create a beautiful sunset over mountains"
    }
  ],
  "modalities": ["image", "text"]
}

图像生成响应示例：

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": [
          {
            "type": "text",
            "text": "Here's your requested sunset over mountains."
          },
          {
            "type": "image_url",
            "image_url": {
              "url": "data:image/png;base64,..."
            }
          }
        ]
      }
    }
  ]
}

上传 Base64 编码图像​

对于本地存储的图像，您可以通过 Base64 编码将其发送给模型。以下是示例：

import { readFile } from "fs/promises";

const getFlowerImage = async (): Promise<string> => {
  const imagePath = new URL("flower.jpg", import.meta.url);
  const imageBuffer = await readFile(imagePath);
  const base64Image = imageBuffer.toString("base64");
  return `data:image/jpeg;base64,${base64Image}`;
};

...

"messages": [
  {
    role: "user",
    content: [
      {
        type: "text",
        text: "What's in this image?",
      },
      {
        type: "image_url",
        image_url: {
          url: `${await getFlowerImage()}`,
        },
      },
    ],
  },
];

发送 Base64 编码数据字符串时，请确保包含图像的 content-type。示例：

data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAABlBMVEX///+/v7+jQ3Y5AAAADklEQVQI12P4AIX8EAgALgAD/aNpbtEAAAAASUVORK5CYII

支持的图像类型：

  • image/png
  • image/jpeg
  • image/webp

响应​

CompletionsResponse 格式​

Knox 在不同模型和提供商之间标准化了 schema，以符合 OpenAI Chat API 规范。

这意味着 choices 始终是一个数组，即使模型仅返回单个补全结果。如果请求了流式响应，每个 choice 将包含一个 delta 属性；否则将包含一个 message 属性。这使得对所有模型使用相同的代码变得更加容易。

响应 schema 的 TypeScript 类型定义如下：

// Definitions of subtypes are below
type Response = {
  id: string;
  // Depending on whether you set "stream" to "true" and
  // whether you passed in "messages" or a "prompt", you
  // will get a different output shape
  choices: (NonStreamingChoice | StreamingChoice | NonChatChoice)[];
  created: number; // Unix timestamp
  model: string;
  object: 'chat.completion' | 'chat.completion.chunk';

  system_fingerprint?: string; // Only present if the provider supports it

  // Usage data is always returned for non-streaming.
  // When streaming, you will get one usage object at
  // the end accompanied by an empty choices array.
  usage?: ResponseUsage;
};
// If the provider returns usage, we pass it down
// as-is. Otherwise, we count using the GPT-4 tokenizer.

type ResponseUsage = {
  /** Including images and tools if any */
  prompt_tokens: number;
  /** The tokens generated */
  completion_tokens: number;
  /** Sum of the above two fields */
  total_tokens: number;
};
// Subtypes:
type NonChatChoice = {
  finish_reason: string | null;
  text: string;
  error?: ErrorResponse;
};

type NonStreamingChoice = {
  finish_reason: string | null;
  native_finish_reason: string | null;
  message: {
    content: string | null;
    role: string;
    tool_calls?: ToolCall[];
  };
  error?: ErrorResponse;
};

type StreamingChoice = {
  finish_reason: string | null;
  native_finish_reason: string | null;
  delta: {
    content: string | null;
    role?: string;
    tool_calls?: ToolCall[];
  };
  error?: ErrorResponse;
};

type ErrorResponse = {
  code: number; // See "Error Handling" section
  message: string;
  metadata?: Record<string, unknown>; // Contains additional error information such as provider details, the raw error message, etc.
};

type ToolCall = {
  id: string;
  type: 'function';
  function: FunctionCall;
};

示例：

{
  "id": "gen-xxxxxxxxxxxxxx",
  "choices": [
    {
      "finish_reason": "stop", // Normalized finish_reason
      "native_finish_reason": "stop", // The raw finish_reason from the provider
      "message": {
        // will be "delta" if streaming
        "role": "assistant",
        "content": "Hello there!"
      }
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 4,
    "total_tokens": 4
  },
  "model": "anthropic/claude-sonnet-4.6" // Could also be "anthropic/claude-2.1", etc, depending on the "model" that ends up being used
}

完成原因​

Knox 将每个模型的 finish_reason 标准化为以下值之一：tool_calls、stop、length、content_filter 或 error。

部分模型和提供商可能包含额外的补全原因。模型返回的原始 finish_reason 字符串可通过 native_finish_reason 属性访问。

查询费用与统计​

输出生成/补全 API 响应中返回的 token 计数并非使用模型的原生分词器计算，而是使用标准化的、与模型无关的计数方式（通过 GPT-5.2 分词器实现）。这是因为某些提供商无法可靠地返回原生 token 计数。但是，这种情况正变得越来越少见，未来我们可能会在响应对象中添加原生 token 计数。

余额使用和模型定价基于原生 token 计数（而非 API 响应中返回的"标准化" token 计数）。