API REFERENCE

Build with Yugos

One model ID, three familiar API formats.

Authentication and setup

Create a project key in API keys and add credit in Billing. Use yugos as the model in your application. Keep your key on your server.

python -m pip install openai httpx
export YUGO_API_KEY="<your project key>"

The OpenAI Python SDK works with Chat Completions and Responses when its base URL is https://api.yugos.ai/v1. The Messages example below uses HTTP directly. Client retries are disabled in these examples; see retry guidance.

curl https://api.yugos.ai/v1/chat/completions \
  -H "Authorization: Bearer $YUGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "yugos",
    "messages": [{"role": "user", "content": "Hello, Yugos."}],
    "max_tokens": 512
  }'

curl https://api.yugos.ai/v1/responses \
  -H "Authorization: Bearer $YUGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "yugos", "input": "Hello, Yugos.", "max_output_tokens": 512, "store": false}'

curl https://api.yugos.ai/v1/messages \
  -H "x-api-key: $YUGO_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model": "yugos", "messages": [{"role": "user", "content": "Hello, Yugos."}], "max_tokens": 512}'

Streaming

All three formats accept stream: true and return server-sent events. Chat Completions emits incremental choices[].delta chunks; Responses and Messages emit their native typed events. Read through the terminal event and handle errors during the stream.

import os
from openai import OpenAI

client = OpenAI(base_url="https://api.yugos.ai/v1", api_key=os.environ["YUGO_API_KEY"], max_retries=0)
stream = client.chat.completions.create(
    model="yugos",
    messages=[{"role": "user", "content": "Explain automatic routing briefly."}],
    max_tokens=512,
    stream=True,
)
try:
    for chunk in stream:
        if chunk.choices:
            print(chunk.choices[0].delta.content or "", end="", flush=True)
finally:
    stream.close()

HTTP 200 means the stream opened; it does not guarantee the entire response completed. Headers can still show pending billing after a successful stream. Check the request receipt for the final outcome and cost before retrying an interrupted response.

Function tools

Yugos selects a model that supports the tools in your request. Your application executes the tool and sends its result in the next turn. Preserve the entire assistant response, including signed reasoning or thinking fields.

import json
import os
from openai import OpenAI

client = OpenAI(base_url="https://api.yugos.ai/v1", api_key=os.environ["YUGO_API_KEY"], max_retries=0)
messages = [{"role": "user", "content": "Convert 20 Celsius to Fahrenheit using the tool."}]
tools = [{"type": "function", "function": {
    "name": "convert_temperature",
    "description": "Convert Celsius to Fahrenheit.",
    "parameters": {"type": "object", "properties": {"celsius": {"type": "number"}}, "required": ["celsius"], "additionalProperties": False},
}}]
first = client.chat.completions.create(model="yugos", messages=messages, tools=tools, max_tokens=512)
message = first.choices[0].message
messages.append(message.model_dump(exclude_none=True))
if message.tool_calls:
    for call in message.tool_calls:
        if call.type != "function" or call.function.name != "convert_temperature":
            raise ValueError("Unexpected tool")
        args = json.loads(call.function.arguments)
        result = {"fahrenheit": float(args["celsius"]) * 9 / 5 + 32}
        messages.append({"role": "tool", "tool_call_id": call.id, "content": json.dumps(result)})
    final = client.chat.completions.create(model="yugos", messages=messages, tools=tools, max_tokens=512)
    print(final.choices[0].message.content)
else:
    print(message.content)

The tool example can make two billed API requests. In production, validate tool arguments, allow only intended actions, and handle additional tool rounds with an explicit limit. For Responses, pair each function_call with a function_call_output using its call_id. For Messages, preserve the assistant’s content blocks and return matching tool_result blocks for each tool_use ID.

Request IDs and receipts

Save the x-request-id response header. When a request was admitted, x-yugo-receipt and Location identify its receipt path. Authenticate with a key from the same project to retrieve it.

curl https://api.yugos.ai/v1/requests/"$REQUEST_ID"/receipt \
  -H "Authorization: Bearer $YUGO_API_KEY"

The receipt shows the executed model, usage, execution status and billing confirmation. Token usage can arrive later than the provider’s cost evidence. You can also open Requests to search the ID and inspect the outcome.

See errors, limits and retries for handling failures, or the routing guide for capabilities and Yugos Free.