Skip to content

模型 API ​

Yi Cloud 支持 OpenAI 的 chat completions、responses、embeddings、图片生成,以及 Anthropic 的 Messages。官方 SDK 改一下 base URL 就能用。每次调用按实际用的 token 计费。

Base URL 和 key ​

客户端Base URLkey 怎么传
OpenAI SDK、直接发 HTTPhttps://cloud.theyilabs.com/v1Authorization: Bearer <key>
Anthropic SDKhttps://cloud.theyilabs.comx-api-key: <key>(SDK 会自动带)或 Authorization: Bearer <key>

key 的「用途」里要有「模型 API」,见 API Key 与限额。key 从环境变量读,不要写进源码。

用 Python 版的 Anthropic SDK:

python
import os
import anthropic

client = anthropic.Anthropic(api_key=os.environ["YI_CLOUD_API_KEY"], base_url="https://cloud.theyilabs.com")
message = client.messages.create(
    model="gemini-4-argon",
    max_tokens=128,
    messages=[{"role": "user", "content": "Hello"}],
)
print(message.content)

控制台的「模型 API」页也有 curl、OpenAI SDK 和 Anthropic SDK 的示例,模型已经替你填好。想让 Codex 或 Claude Code 用 Yi Cloud,见 Codex 与 Claude Code。

模型 ​

  • GET https://cloud.theyilabs.com/v1/catalog 列出已开放的模型和价格,不需要 key。每个模型有 id、name、kind(chat、embedding 或 image)、price、responses_api(能不能用 /v1/responses)和 max_output_tokens。
  • GET https://cloud.theyilabs.com/v1/models 是 OpenAI 格式的列表,需要 key,只列出这个 key 能用的模型。
  • 控制台的价格页按美元列出每百万输入、输出和缓存输入 token 的价格,图片模型还有每百万图片输出 token 的价格。

请求里的 model 填模型的 id。不在目录里的 ID 会得到 404 not_found。每类模型有自己的接口:对话模型用 chat completions、responses 和 messages,向量模型用 /v1/embeddings,图片模型用 /v1/images/generations。发错接口会得到 400 invalid_request。

接口 ​

接口说明
POST /v1/chat/completionsOpenAI chat completions。普通 JSON 或流式。支持函数工具。
POST /v1/responsesOpenAI Responses,只用于目录里 responses_api: true 的模型。普通 JSON 或流式。
POST /v1/embeddings向量模型。不支持流式。
POST /v1/messagesAnthropic Messages。普通 JSON 或流式。由 chat completions 用的那些对话模型来回答。
POST /v1/images/generationsOpenAI 图片生成,用于图片模型。返回 b64_json。不支持流式。

Chat completions ​

  • messages 里有 1 到 4,096 条消息。
  • 工具只能是 type: "function",由你自己的代码执行。
  • 如果传了 n,只能是 1。
  • 输出上限可以写成 max_tokens、max_completion_tokens 或 max_output_tokens,Yi Cloud 会换成模型认的那个参数名。上限不能超过模型的 max_output_tokens,不传就按这个最大值。
  • 有些模型的采样参数是固定的。对这些模型,temperature、top_p、presence_penalty、frequency_penalty、logprobs、top_logprobs、logit_bias 和 stop 会在发给模型之前去掉。
  • store 只能是 false,发出去时也总是 false。

Responses ​

  • 必须有 input。
  • 什么都不保存:store 总是 false,background、previous_response_id 和 conversation 会被拒绝。
  • 只支持函数工具,内置的托管工具会被拒绝。
  • 引用已存内容的写法(item_reference、file_id)会被拒绝。

Embeddings ​

input 是一个字符串,或者最多 2,048 个字符串的数组。有些模型每次只接受一个字符串,gemini-embedding-001 就是。

sh
curl https://cloud.theyilabs.com/v1/embeddings \
  -H "Authorization: Bearer $YI_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gemini-embedding-001","input":"Hello"}'

返回 OpenAI 的格式,支持 encoding_format: "base64"。

图片生成 ​

图片模型按文字提示画一张图,返回 OpenAI 的格式。

python
import base64
import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["YI_CLOUD_API_KEY"], base_url="https://cloud.theyilabs.com/v1")
image = client.images.generate(model="gemini-nano-banana-2.1", prompt="A red cube on a white table", size="1536x1024")
open("image.png", "wb").write(base64.b64decode(image.data[0].b64_json))
  • 必须有 prompt,最多 32,000 个字符。
  • size 是 auto 或 宽x高,决定图片的形状。宽高比要和 1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9 中的一个相差不超过 2%。1024x1024、1536x1024、1024x1536、1792x1024 都可以。也可以直接传 aspect_ratio,比如 "16:9"。
  • image_size 决定分辨率:1K(默认)、2K 或 4K。用 OpenAI SDK 时放在 extra_body 里。Gemini 3.1 Flash-Lite Image 只能画 1K。
  • 图片以 base64 放在 data[0].b64_json。output_format 说明是 png 还是 jpeg。response_format 只能是 b64_json:图片不保存,所以没有 URL。
  • 图片文件里只有一个 XMP 标签,标明这是 AI 生成的图(IPTC 数字来源类型 trainedAlgorithmicMedia),没有其他元数据。部分模型还会在像素里留下肉眼看不见的水印。
  • 如果传了 n,只能是 1。quality、style 等其他 OpenAI 参数会被忽略。
  • usage 里有 input_tokens 和 output_tokens。output_tokens_details 把输出分成 image_tokens 和 text_tokens,文字 token 包括模型的思考。

模型拒绝了提示词,返回 400 content_filter;模型结束时没有出图,返回 502 no_image。这两种情况都按模型已用的 token(提示词和思考)收费。

Anthropic Messages ​

Messages 请求由目录里的对话模型回答,结果以 Anthropic 的 message 或流式事件返回。

  • 支持文本、图片(base64 或 URL)、工具调用和工具结果。
  • messages 里的 system 消息也可以用。它的文字并入相邻的用户轮次;放在最前面时并入系统提示词。
  • 工具只能是自定义工具,即 name、description 和 input_schema。服务端工具和其他类型的块(比如文档)会被拒绝,返回 400 invalid_request。
  • 之前轮次里的 thinking 块会被去掉,top_k 会被忽略。
  • stop_sequences 最多用前 4 个。
  • usage 里的缓存输入写在 cache_read_input_tokens。

流式输出 ​

传 stream: true,返回 server-sent events。

  • chat completions 只有在你传了 stream_options: {"include_usage": true} 时,才会发用量那一块。
  • 流开始之后如果断了,最后一个事件是错误。OpenAI 的接口上是 event: error,带 code: "incomplete_stream" 和 request_id。/v1/messages 上是 Anthropic 的 error 事件。
  • 你断开连接,调用就停止。已经生成的 token 照常计费。

自动切换 ​

一个模型可以有多个部署,Yi Cloud 按顺序尝试。

  • 在回答的第一个字节之前,遇到 429、5xx、连接断开,或者 60 秒内没有回应(图片是 180 秒),请求会换到同一模型的下一个部署。出错的部署会休息一段时间再接新请求。
  • 第一个字节之后,请求不会再发第二次。流断了就以错误事件结束。
  • 模型拒绝了请求、内容被拒,或者部署那边鉴权失败,都不会换部署。

所有部署都回答不了时,返回 502 upstream_failed、503 upstream_capacity 或 504 upstream_timeout,稍后再试。

限制 ​

项目上限
请求体4 MiB
非流式的回答16 MiB(图片 64 MiB)
单个流式事件4 MiB
每个请求的回答数1(n = 1)
每个部署等待第一个字节60 秒(图片 180 秒)
流式两块之间的间隔120 秒
整个请求29 分钟

以 URL 或内联数据给出的图片,按原样交给模型。预扣时用的输入估算,对媒体内容不是精确计量。

key 还可以设每分钟请求数,见 API Key 与限额。

一次调用怎么算钱 ​

  1. 调用之前,Yi Cloud 预扣这次调用最多可能花的钱:估算的输入 token 加上最大输出 token,按模型的输入和输出价格算。如果模型对长提示词或写入提示词缓存另有更高的价格,预扣按更高的价格算。
  2. 调用之后,按模型报告的用量扣费:输入 token、按缓存价算的缓存输入 token、输出 token(包括模型报告的推理 token)。金额向上取整到微美元,预扣剩下的部分释放。

图片模型多一个输出价格。图片输出 token 按图片输出价算,文字和思考按输出价算。一张 1K 或 2K 的图大约是 1,100 到 1,700 个图片 token,4K 最多约 3,800 个。画图的预扣按图片输出价算:1K 预扣 4,096 个输出 token,2K 6,144 个,4K 8,192 个。

扣费不会超过预扣。如果模型没有报告用量,Yi Cloud 会估算,这个请求在「最近请求」里标为「估算」。图片的估算就是整个预扣。还没有任何输出就失败的调用不收费。

max_tokens 越小,预扣越小。余额或 key 的花费上限快到时,这一点很有用。见计费与回执。

错误 ​

成功的回答在 x-request-id 响应头里带着请求 ID,每个错误体里也有它,字段名是 request_id。问我们某个请求时,请带上它。

状态码code含义
400invalid_request某个参数不被接受,消息里会写是哪个。
400upstream_invalid_request模型拒绝了输入或参数。
400content_filter模型拒绝了这段内容。
402insufficient_funds、key_limit_reached预扣超出了余额或 key 的上限。
403forbidden这个 key 不能用于模型,或者模型不在 key 允许的范围内。
404not_found没有这个 ID 的已开放模型。
429rate_limited超过了 key 的每分钟限制。按 Retry-After 里的秒数等一下。
502upstream_failed、provider_authentication、provider_configuration、response_too_large没有部署给出可用的回答。
502no_image图片模型结束时没有出图。已用的 token 照常收费。
503upstream_capacity、upstream_unavailable模型忙,或者模型 API 暂停了。
504upstream_timeout没有部署按时回答。

错误消息不会转述部署的原始报错。完整列表见 API 参考。

保存什么 ​

不保存提示词和输出。每个请求只保存模型、接口、token 数、费用、状态和耗时,保留 90 天。用量汇总和流水在那之后仍然保留。见安全与隐私。