Models API
Yi Cloud answers OpenAI's chat completions, responses, embeddings and image generation, and Anthropic's Messages. The official SDKs work once you change the base URL. Each call is billed by the tokens it used.
Base URL and key
| Client | Base URL | How the key is sent |
|---|---|---|
| OpenAI SDKs, plain HTTP | https://cloud.theyilabs.com/v1 | Authorization: Bearer <key> |
| Anthropic SDKs | https://cloud.theyilabs.com | x-api-key: <key> (the SDK does this) or Authorization: Bearer <key> |
The key needs "Model API" under "Use for". See API keys and limits. Read the key from an environment variable, never from source code.
With the Anthropic SDK for 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)The Model API page in the console shows the same examples for curl, the OpenAI SDK and the Anthropic SDK, filled in with a model from your catalog. To run Codex or Claude Code on Yi Cloud, see Codex and Claude Code.
Models
GET https://cloud.theyilabs.com/v1/cataloglists the enabled models with their prices. It needs no key. Each model has anid, aname, akind(chat,embeddingorimage), aprice,responses_api(whether it takes/v1/responses) andmax_output_tokens.GET https://cloud.theyilabs.com/v1/modelsis the OpenAI-style list. It needs a key and shows only the models that key may use.- The console's price page shows the price per million input, output and cached input tokens in US dollars, and per million image output tokens for image models.
Send the model's id as model. An ID that isn't in the catalog gets 404 not_found. Each kind has its own endpoints: chat models take chat completions, responses and messages, embedding models take /v1/embeddings, and image models take /v1/images/generations. Anything else gets 400 invalid_request.
Endpoints
| Endpoint | What it takes |
|---|---|
POST /v1/chat/completions | OpenAI chat completions. JSON or streaming. Function tools. |
POST /v1/responses | OpenAI Responses, for models whose catalog entry has responses_api: true. JSON or streaming. |
POST /v1/embeddings | Embedding models. No streaming. |
POST /v1/messages | Anthropic Messages. JSON or streaming. Answered by the same chat models as chat completions. |
POST /v1/images/generations | OpenAI image generation, for image models. Answers b64_json. No streaming. |
Chat completions
messagesholds 1 to 4,096 messages.- Tools must be
type: "function". Your code runs them. nmust be 1 if you send it.- Send the output limit as
max_tokens,max_completion_tokensormax_output_tokens. Yi Cloud passes it on under the name the model expects. It can't go above the model'smax_output_tokens, and when you don't send one, that maximum is used. - Some models use fixed sampling. For them
temperature,top_p,presence_penalty,frequency_penalty,logprobs,top_logprobs,logit_biasandstopare removed before the request goes to the model. storemay only befalse, and is always sent asfalse.
Responses
inputis required.- Nothing is stored.
storeis alwaysfalse, andbackground,previous_response_idandconversationare refused. - Only function tools. Built-in hosted tools are refused.
- References to stored content (
item_referenceitems,file_id) are refused.
Embeddings
input is a string or an array of up to 2,048 strings. Some models, including gemini-embedding-001, take one string per request.
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"}'The answer is in OpenAI's format. encoding_format: "base64" is supported.
Image generation
Image models draw one image from a text prompt. The answer is in OpenAI's format.
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))promptis required, up to 32,000 characters.sizeisautoorWIDTHxHEIGHT. It sets the shape of the image: it must be within 2 % of one of the ratios 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9 or 21:9.1024x1024,1536x1024,1024x1536and1792x1024all work. You can sendaspect_ratio(for example"16:9") instead.image_sizesets the resolution:1K(the default),2Kor4K. With the OpenAI SDK, send it inextra_body. Gemini 3.1 Flash-Lite Image draws1Konly.- The image comes back as base64 in
data[0].b64_json.output_formatsays whether it ispngorjpeg.response_formatmay only beb64_json: images are not stored, so there is no URL. - The image file carries no metadata except one XMP tag marking it as made by AI (IPTC digital source type
trainedAlgorithmicMedia). Some models also leave an invisible watermark in the pixels. nmust be 1 if you send it.quality,styleand other OpenAI options are ignored.usagehasinput_tokensandoutput_tokens.output_tokens_detailssplits the output intoimage_tokensandtext_tokens. Text tokens include the model's thinking.
If the model refuses the prompt, you get 400 content_filter. If it ends without an image, you get 502 no_image. In both cases the tokens it used, the prompt and its thinking, are charged.
Anthropic Messages
A Messages request is answered by a chat model from the catalog, and the answer comes back as an Anthropic message or Anthropic stream events.
- Text, images (base64 or URL), tool use and tool results are supported.
- A
systemmessage insidemessagesis accepted. Its text joins the user turn next to it, or the system prompt if it comes first. - Tools must be custom tools:
name,descriptionandinput_schema. Server tools and other block types, such as documents, are refused with400 invalid_request. - Thinking blocks from earlier turns are dropped, and
top_kis ignored. - Up to 4
stop_sequencesare used. usagereports cached input ascache_read_input_tokens.
Streaming
Send stream: true to get server-sent events.
- For chat completions, the usage chunk is sent only when you ask for it with
stream_options: {"include_usage": true}. - If a stream breaks after it started, the last event is an error. On the OpenAI paths it is
event: errorwithcode: "incomplete_stream"and therequest_id. On/v1/messagesit is an Anthropicerrorevent. - If you disconnect, the call stops. Tokens already produced are charged.
Failover
A model can have several deployments. Yi Cloud tries them in order.
- Before the first byte of the answer, a
429, a5xx, a broken connection or no answer within 60 seconds (180 seconds for an image) moves the request to the next deployment of the same model. The deployment that failed rests for a while before it gets new requests. - After the first byte, a request is never sent again. A stream that breaks ends with an error event.
- A request the model rejects, a content refusal, or an authentication failure at the deployment doesn't move to another deployment.
When no deployment can answer, you get 502 upstream_failed, 503 upstream_capacity or 504 upstream_timeout. Try again shortly.
Limits
| Limit | Value |
|---|---|
| Request body | 4 MiB |
| Answer without streaming | 16 MiB (64 MiB for an image) |
| One stream event | 4 MiB |
| Answers per request | 1 (n = 1) |
| Wait for the first byte, per deployment | 60 seconds (180 seconds for an image) |
| Gap between stream chunks | 120 seconds |
| Whole request | 29 minutes |
Images given as URLs or inline data go to the model as you sent them. The input estimate used for the hold doesn't measure media exactly.
A key can also have a requests-per-minute limit. See API keys and limits.
What a call costs
- Before the call, Yi Cloud holds the most it can cost: the estimated input tokens plus the maximum output tokens, all at the input and output prices of the model. If the model has a higher price for long prompts or for writing to the prompt cache, the hold uses the higher price.
- After the call, it charges what the model reports: input tokens, cached input tokens at the cached price, and output tokens, including any reasoning tokens. The amount is rounded up to a whole micro-dollar. The rest of the hold is released.
Image models have a second output price. Image output tokens are charged at the image output price, and text and thinking at the output price. A 1K or 2K image is about 1,100 to 1,700 image tokens; a 4K image up to about 3,800. The hold for an image covers 4,096 output tokens for 1K, 6,144 for 2K and 8,192 for 4K, all at the image output price.
You're never charged more than the hold. If the model doesn't report its usage, Yi Cloud estimates it, and the request shows as "Estimated" under "Recent requests". For an image, the estimate is the whole hold. A call that fails before any output isn't charged.
A smaller max_tokens means a smaller hold, which matters when your balance or a key's spend limit is close. See Billing and receipts.
Errors
A successful answer carries the request's ID in the x-request-id header, and every error body has it as request_id. Give it to us when you ask about a request.
| Status | code | Meaning |
|---|---|---|
| 400 | invalid_request | A parameter isn't accepted. The message says which. |
| 400 | upstream_invalid_request | The model rejected the input or parameters. |
| 400 | content_filter | The model refused this content. |
| 402 | insufficient_funds, key_limit_reached | The hold doesn't fit the balance or the key's limit. |
| 403 | forbidden | The key may not be used for models, or the model is outside what the key allows. |
| 404 | not_found | No enabled model with this ID. |
| 429 | rate_limited | The key's per-minute limit. Wait the seconds in Retry-After. |
| 502 | upstream_failed, provider_authentication, provider_configuration, response_too_large | No deployment gave a usable answer. |
| 502 | no_image | The image model ended without an image. The tokens it used are charged. |
| 503 | upstream_capacity, upstream_unavailable | The model is busy, or the model API is paused. |
| 504 | upstream_timeout | No deployment answered in time. |
Error messages never pass on a deployment's raw error text. The full list is in the API reference.
What is stored
Prompts and outputs are not stored. For each request Yi Cloud keeps the model, the endpoint, the token counts, the cost, the status and the latency, for 90 days. Usage totals and the ledger are kept after that. See Security and privacy.