模型 API
Yi Cloud 支持 OpenAI 的 chat completions、responses、embeddings、图片生成,以及 Anthropic 的 Messages。官方 SDK 改一下 base URL 就能用。每次调用按实际用的 token 计费。
Base URL 和 key
| 客户端 | Base URL | key 怎么传 |
|---|---|---|
| OpenAI SDK、直接发 HTTP | https://cloud.theyilabs.com/v1 | Authorization: Bearer <key> |
| Anthropic SDK | https://cloud.theyilabs.com | x-api-key: <key>(SDK 会自动带)或 Authorization: Bearer <key> |
key 的「用途」里要有「模型 API」,见 API Key 与限额。key 从环境变量读,不要写进源码。
用 Python 版的 Anthropic SDK:
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/completions | OpenAI chat completions。普通 JSON 或流式。支持函数工具。 |
POST /v1/responses | OpenAI Responses,只用于目录里 responses_api: true 的模型。普通 JSON 或流式。 |
POST /v1/embeddings | 向量模型。不支持流式。 |
POST /v1/messages | Anthropic Messages。普通 JSON 或流式。由 chat completions 用的那些对话模型来回答。 |
POST /v1/images/generations | OpenAI 图片生成,用于图片模型。返回 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 就是。
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 的格式。
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 与限额。
一次调用怎么算钱
- 调用之前,Yi Cloud 预扣这次调用最多可能花的钱:估算的输入 token 加上最大输出 token,按模型的输入和输出价格算。如果模型对长提示词或写入提示词缓存另有更高的价格,预扣按更高的价格算。
- 调用之后,按模型报告的用量扣费:输入 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 | 含义 |
|---|---|---|
| 400 | invalid_request | 某个参数不被接受,消息里会写是哪个。 |
| 400 | upstream_invalid_request | 模型拒绝了输入或参数。 |
| 400 | content_filter | 模型拒绝了这段内容。 |
| 402 | insufficient_funds、key_limit_reached | 预扣超出了余额或 key 的上限。 |
| 403 | forbidden | 这个 key 不能用于模型,或者模型不在 key 允许的范围内。 |
| 404 | not_found | 没有这个 ID 的已开放模型。 |
| 429 | rate_limited | 超过了 key 的每分钟限制。按 Retry-After 里的秒数等一下。 |
| 502 | upstream_failed、provider_authentication、provider_configuration、response_too_large | 没有部署给出可用的回答。 |
| 502 | no_image | 图片模型结束时没有出图。已用的 token 照常收费。 |
| 503 | upstream_capacity、upstream_unavailable | 模型忙,或者模型 API 暂停了。 |
| 504 | upstream_timeout | 没有部署按时回答。 |
错误消息不会转述部署的原始报错。完整列表见 API 参考。
保存什么
不保存提示词和输出。每个请求只保存模型、接口、token 数、费用、状态和耗时,保留 90 天。用量汇总和流水在那之后仍然保留。见安全与隐私。