Skip to content

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 ​

ClientBase URLHow the key is sent
OpenAI SDKs, plain HTTPhttps://cloud.theyilabs.com/v1Authorization: Bearer <key>
Anthropic SDKshttps://cloud.theyilabs.comx-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:

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/catalog lists the enabled models with their prices. It needs no key. Each model has an id, a name, a kind (chat, embedding or image), a price, responses_api (whether it takes /v1/responses) and max_output_tokens.
  • GET https://cloud.theyilabs.com/v1/models is 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 ​

EndpointWhat it takes
POST /v1/chat/completionsOpenAI chat completions. JSON or streaming. Function tools.
POST /v1/responsesOpenAI Responses, for models whose catalog entry has responses_api: true. JSON or streaming.
POST /v1/embeddingsEmbedding models. No streaming.
POST /v1/messagesAnthropic Messages. JSON or streaming. Answered by the same chat models as chat completions.
POST /v1/images/generationsOpenAI image generation, for image models. Answers b64_json. No streaming.

Chat completions ​

  • messages holds 1 to 4,096 messages.
  • Tools must be type: "function". Your code runs them.
  • n must be 1 if you send it.
  • Send the output limit as max_tokens, max_completion_tokens or max_output_tokens. Yi Cloud passes it on under the name the model expects. It can't go above the model's max_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_bias and stop are removed before the request goes to the model.
  • store may only be false, and is always sent as false.

Responses ​

  • input is required.
  • Nothing is stored. store is always false, and background, previous_response_id and conversation are refused.
  • Only function tools. Built-in hosted tools are refused.
  • References to stored content (item_reference items, 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.

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"}'

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.

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 is required, up to 32,000 characters.
  • size is auto or WIDTHxHEIGHT. 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, 1024x1536 and 1792x1024 all work. You can send aspect_ratio (for example "16:9") instead.
  • image_size sets the resolution: 1K (the default), 2K or 4K. With the OpenAI SDK, send it in extra_body. Gemini 3.1 Flash-Lite Image draws 1K only.
  • The image comes back as base64 in data[0].b64_json. output_format says whether it is png or jpeg. response_format may only be b64_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.
  • n must be 1 if you send it. quality, style and other OpenAI options are ignored.
  • usage has input_tokens and output_tokens. output_tokens_details splits the output into image_tokens and text_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 system message inside messages is accepted. Its text joins the user turn next to it, or the system prompt if it comes first.
  • Tools must be custom tools: name, description and input_schema. Server tools and other block types, such as documents, are refused with 400 invalid_request.
  • Thinking blocks from earlier turns are dropped, and top_k is ignored.
  • Up to 4 stop_sequences are used.
  • usage reports cached input as cache_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: error with code: "incomplete_stream" and the request_id. On /v1/messages it is an Anthropic error event.
  • 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, a 5xx, 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 ​

LimitValue
Request body4 MiB
Answer without streaming16 MiB (64 MiB for an image)
One stream event4 MiB
Answers per request1 (n = 1)
Wait for the first byte, per deployment60 seconds (180 seconds for an image)
Gap between stream chunks120 seconds
Whole request29 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 ​

  1. 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.
  2. 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.

StatuscodeMeaning
400invalid_requestA parameter isn't accepted. The message says which.
400upstream_invalid_requestThe model rejected the input or parameters.
400content_filterThe model refused this content.
402insufficient_funds, key_limit_reachedThe hold doesn't fit the balance or the key's limit.
403forbiddenThe key may not be used for models, or the model is outside what the key allows.
404not_foundNo enabled model with this ID.
429rate_limitedThe key's per-minute limit. Wait the seconds in Retry-After.
502upstream_failed, provider_authentication, provider_configuration, response_too_largeNo deployment gave a usable answer.
502no_imageThe image model ended without an image. The tokens it used are charged.
503upstream_capacity, upstream_unavailableThe model is busy, or the model API is paused.
504upstream_timeoutNo 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.