Universe Frequently Asked Questions

This document compiles common questions and answers for developers using the Universe. If you encounter a problem not listed here, please submit feedback via the button in the top-right corner of the page, or contact the technical support team for assistance.

Account & Authentication

Q1: How to obtain an API Key?

Log in to the Universe API Console and create a new key on the API Keys Management Page. Each account can create multiple API Keys. It is recommended to use separate keys for different projects or environments (development/testing/production) for easier management and access control.

Security Reminder: Your API Key is your identity credential. Please keep it secure -- do not hardcode it in your code or commit it to public repositories. It is recommended to configure keys via environment variables or a secret management service.

Q2: What access controls does the API Key support?

The API Key currently supports the following dimensions of permission management:

Control Dimension	Description
Model Access Permission	Restrict which models a single Key can call (e.g., allow only Universe 3.0).
Call Rate Limit	Set the maximum number of requests per minute/hour (RPM/RPH).
Spending Cap	Set a maximum spending amount for a single Key to prevent unexpected overspending.
IP Whitelist	Restrict the Key to only allow requests from specified IP addresses.

Q3: What to do when a 401 Unauthorized error is returned?

A 401 error indicates authentication failure. Common causes and troubleshooting steps:

1. API Key not provided: Check that the request header includes Authorization: Bearer YOUR_API_KEY.
2. Key format error: Confirm that you copied the complete Key without extra spaces or line breaks.
3. Key expired or disabled: Log in to the console to check the Key status; recreate it if necessary.
4. Bearer misspelled: Note that there is a space after Bearer and the first letter is capitalized.

# Correct request header format
Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx

---

API Calls & Requests

Q4: What calling methods are supported?

Universe provides multiple calling methods to meet the needs of different technology stacks:

Calling Method	Description	Use Case
HTTP RESTful API	Standard HTTP requests, supported by all programming languages.	Any technology stack
Python SDK	Official Python toolkit with async call support.	Python projects
Java SDK	Official Java toolkit with high-concurrency support.	Java/Spring projects
OpenAI Compatible Interface	Compatible with OpenAI SDK protocol, only requires changing base_url.	Migrating from OpenAI
LangChain Integration	Native support for the LangChain framework.	AI Agent / RAG applications

Tip: For general use cases, use the endpoint https://open.universeapi.com/api/paas/v4; for specialized scenarios such as coding, use https://open.universeapi.com/api/coding/paas/v4. Please refer to the API documentation for details.

For detailed calling examples, please refer to the API Reference.

Q5: How to migrate from OpenAI SDK to Universe API?

Universe is compatible with the OpenAI SDK protocol. Migration only requires changing two parameters:

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_UNIVERSE_API_KEY",
    base_url="https://open.universeapi.com/api/paas/v4"
)

response = client.chat.completions.create(
    model="universe-3.0-pro",  # Replace with Universe model name
    messages=[
        {"role": "user", "content": "Hello"}
    ]
)

Simply point base_url to the Universe API endpoint and replace api_key with your Universe API Key for seamless migration. Please refer to the available model list in the Model Product Introduction for model names.

Q6: What is the difference between streaming and non-streaming calls?

Comparison	Non-Streaming (stream=false)	Streaming (stream=true)
Response Method	Waits for the model to finish generating and returns the complete result at once.	Pushes generated content token by token in real time.
First Token Latency	Higher, must wait for full generation to complete.	Extremely low, can start displaying from the first token.
Use Case	Backend batch processing, data extraction, and other scenarios that do not require real-time display.	Chat conversations, real-time interactions, and other scenarios that benefit from a "typewriter effect."
Parsing Method	Parse the JSON response body directly.	Parse line by line using the SSE (Server-Sent Events) protocol.

# Streaming call example
response = client.chat.completions.create(
    model="universe-3.0-pro",
    messages=[{"role": "user", "content": "Tell me a story"}],
    stream=True
)

for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

Recommendation: For user-facing interactive scenarios, streaming calls are recommended as they can significantly improve user experience.

Q7: How should the temperature and top_p parameters be set?

These two parameters control the randomness and diversity of model output. Typically, you only need to adjust one of them:

Scenario	Recommended temperature	Effect
Factual Q&A / Code Generation	0.0 - 0.3	More deterministic and consistent output
General Conversation / General Assistant	0.5 - 0.7	Balanced accuracy and diversity
Creative Writing / Brainstorming	0.7 - 1.0	More diverse and creative output

Note: It is not recommended to adjust temperature and top_p simultaneously, as modifying both may lead to unpredictable output behavior.

For more parameter tuning tips, please refer to the Prompt Engineering Guide.

---

Model & Output

Q8: How to choose the right model?

Universe API offers three models with different positioning. Choose based on task complexity and budget:

Model	Positioning	Use Case
Universe 3.0	Lightweight & Efficient	Daily Q&A, text classification, batch generation, and other high-frequency, low-cost scenarios
Universe 3.0 Pro	Professional & Enhanced	Professional content creation, code generation, data analysis, and other scenarios requiring strong reasoning
Universe 4.5	Flagship & Versatile	Complex reasoning, enterprise-level agents, professional consulting, and other demanding scenarios

If you are unsure which to choose, we recommend starting with Universe 3.0 Pro, which offers the best balance between capability and cost. For a detailed model comparison, please refer to the Model Product Introduction.

Q9: What to do when model output is unstable and results vary significantly each time?

Unstable output is usually caused by the following reasons:

Reason 1: temperature set too high For tasks requiring deterministic output (such as classification and extraction), set temperature to 0 or a value close to 0.

Reason 2: Prompt is not specific enough Vague prompts leave too much room for the model to "improvise." It is recommended to explicitly specify the output format, scope, and constraints in the prompt.

# Unstable approach
"Help me analyze this data"

# Stable approach
"Please analyze the following sales data from three dimensions: month-over-month growth rate, category breakdown, and anomaly detection.
Return the results in JSON format with three fields: growth_rate, category_breakdown, and anomalies."

Reason 3: Lack of example guidance Using Few-shot Learning to provide 2-3 input-output examples can significantly improve output consistency.

For more prompt writing tips, please refer to the Prompt Engineering Guide.

Q10: What to do when the model produces "hallucinations" (fabricating non-existent information)?

Model "hallucinations" refer to generating content that appears plausible but is actually inaccurate. The following strategies can effectively reduce the likelihood of hallucinations:

Strategy	Description
Set constraints in the System Prompt	Add an instruction such as "If you are unsure, clearly inform the user and do not fabricate information."
Use RAG to provide knowledge sources	Use knowledge base retrieval to let the model answer questions based on real documents rather than relying on training data.
Request source citations	Ask the model to annotate information sources in the prompt for verification of accuracy.
Lower the temperature	A lower temperature value makes output more conservative and closer to training data.
Break down tasks	Decompose complex tasks into simpler steps to reduce errors during long-chain reasoning.

Q11: What to do when output is truncated and incomplete?

Output truncation usually occurs because the max_tokens limit has been reached. Solutions:

1. Increase max_tokens: Raise this parameter according to the expected output length.
2. Use a continuation mechanism: After detecting truncation, include the existing output as context and send a new request to continue generation.
3. Streamline the Prompt: Shorten the input content to reserve more token space for output.

# Detect whether output was truncated
if response.choices[0].finish_reason == "length":
    print("Output was truncated due to reaching the max_tokens limit. Please increase this parameter or generate in segments.")

Q12: How to control model output in JSON format?

Explicitly request JSON output in the Prompt and provide a format template:

Please output the result in JSON format without any extra text or Markdown markers.
The format is as follows:
{"name": "...", "summary": "...", "tags": ["...", "..."]}

If the model occasionally wraps JSON in Markdown code block markers (such as triple backticks followed by "json"), you can remove them using a regular expression in post-processing, or emphasize in the System Prompt: "Output pure JSON directly, do not wrap in code blocks."

---

Error Codes & Troubleshooting

Q13: Common HTTP error codes and solutions

Status Code	Meaning	Common Cause	Solution
400 Bad Request	Request parameter error	Request body format is incorrect, required fields are missing, or parameter values are out of range.	Check whether the request body JSON format is correct and verify required parameters (model, messages).
401 Unauthorized	Authentication failure	API Key is invalid, missing, or not passed correctly.	Confirm the Key is correct and check the Authorization: Bearer YOUR_KEY request header.
403 Forbidden	No permission	The Key does not have permission to access the model, or a security policy was triggered.	Check the Key permission settings and confirm that the request content does not violate usage policies.
404 Not Found	Resource not found	Model name is misspelled, or an unsupported endpoint address was used.	Verify that the model name and API endpoint address are correct.
429 Too Many Requests	Rate limit exceeded	Too many requests sent in a short period, exceeding the quota limit.	Reduce call frequency and increase request intervals; or contact support to request a quota increase.
500 Internal Server Error	Internal server error	Temporary platform-side failure.	Retry later; if the error persists, contact technical support and provide the Request ID.
502 Bad Gateway	Gateway error	Upstream service is temporarily unavailable.	Retry later; this is usually a temporary issue.
503 Service Unavailable	Service unavailable	System maintenance or overload.	Wait a few minutes and retry.

Q14: What to do when a request times out?

Request timeouts are usually caused by the following:

Network issues: Check client network connectivity and confirm that https://open.universeapi.com is accessible.

# Test network connectivity
curl -I https://open.universeapi.com

Model response time too long: Complex tasks or long text generation require more time. Recommendations:

• Use streaming calls (stream=true) to avoid long waits for a complete response.
• Simplify the Prompt or break down the task to reduce the processing load per request.

Client timeout set too short: Adjust the client timeout based on the actual task complexity.

# Set timeout in Python SDK
client = UniverseClient(
    api_key="YOUR_API_KEY",
    timeout=120  # Unit: seconds, adjust according to business needs
)

Q15: What to do when receiving a 429 rate limit error?

A 429 error indicates that the request frequency has exceeded the current account's quota limit. Strategies:

Strategy	Description
Increase request interval	Add an appropriate delay between two requests, e.g., time.sleep(1).
Implement exponential backoff retry	Wait 1 second before the first retry, then 2 seconds, 4 seconds... gradually increasing.
Use a request queue	Place requests in a queue and send them at a steady rate according to the rate limit policy.
Request a quota increase	Contact technical support to apply for a higher RPM/RPH limit based on your business needs.

import time
from openai import RateLimitError  # If using the official SDK, import from universeai.exceptions instead

def call_with_retry(client, messages, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(
                model="universe-3.0-pro",
                messages=messages
            )
        except RateLimitError:
            wait_time = 2 ** attempt  # 1s, 2s, 4s
            print(f"Rate limit triggered, retrying after {wait_time} seconds...")
            time.sleep(wait_time)
    raise Exception("Maximum retry count exceeded, please try again later")

---

Billing & Costs

Q16: How is Universe API billed?

Universe API uses a per-token billing model. A token is the smallest unit of text processed by the model. Generally, 1 Chinese word, 1 English word, or 1 punctuation mark is approximately 1 token.

Billing formula: Cost = Token consumption (in millions of tokens) x Model unit price

Costs are deducted from the recharge balance and include both input tokens and output tokens. For specific unit prices of each model, please refer to Pricing.

Q17: What is Prompt Cache?

Prompt Cache is an optimization mechanism that reduces the cost of repeated calls. When multiple requests contain the same input content (such as a fixed System Prompt or a long document prefix), the system caches the processing results for that portion.

• Cache hit: The cached portion of the input is billed at a discounted price (significantly lower than the standard price).
• Cache miss: Billed at the standard input price.

Taking Universe 3.0 as an example, the input price for a cache hit is 0.05 CNY per million tokens, which is only 2.5% of the non-cached price (2 CNY per million tokens). It is recommended to keep fixed System Prompts and commonly used prefix content consistent to maximize the use of the caching mechanism and reduce costs.

Q18: How to view spending details and balance?

Log in to the console and navigate to the Cost Center page to view:

• Current account balance
• Daily/monthly spending trends
• Token consumption details by model
• Independent spending statistics for each API Key

It is recommended to check spending regularly, set up spending alerts and Key quota limits to avoid unexpected overspending.

---

SDK & Integration

Q19: What to do when Python SDK installation fails?

Check Python version: The Universe AI Python SDK requires Python 3.8 or above.

python --version  # Confirm version >= 3.8

Use a virtual environment: It is recommended to install in a virtual environment to avoid dependency conflicts.

python -m venv myenv
source myenv/bin/activate  # Windows: myenv\Scripts\activate
pip install universeai

Network issues: If installation times out, try using a regional mirror.

pip install universeai -i https://pypi.tuna.tsinghua.edu.cn/simple

Q20: How to configure the Maven dependency for the Java SDK?

Add the following dependency to your project's pom.xml:

<dependency>
    <groupId>com.universeai</groupId>
    <artifactId>universeai-java-sdk</artifactId>
    <version>1.0.0</version>  <!-- Check Maven Central for the latest version number -->
</dependency>

Make sure to use the latest version to get the newest features and bug fixes. If dependency download fails, check that your Maven repository configuration is correct, or contact technical support for the latest version information.

Q21: How to integrate with LangChain?

Universe API natively supports the LangChain framework. Simply configure a custom endpoint:

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="universe-3.0-pro",
    api_key="YOUR_UNIVERSE_API_KEY",
    base_url="https://open.universeapi.com/api/paas/v4"
)

# Use LangChain's standard features directly
response = llm.invoke("Introduce Universe API")

Supports the full range of LangChain features, including Chain, Agent, Tool Calling, Memory, and other modules.

---

Performance & Stability

Q22: How to optimize API call response speed?

Optimization Strategy	Description	Expected Effect
Use streaming calls	Set stream=true so the first token starts returning immediately.	Significantly reduces first-token latency and improves perceived performance.
Streamline input content	Remove unnecessary context and conversation history to reduce input token count.	Reduces model processing time.
Leverage Prompt Cache	Keep the System Prompt consistent so repeated content hits the cache.	Reduces input processing time and cost.
Choose the right model	Use Universe 3.0 for simple tasks -- avoid using a sledgehammer to crack a nut.	Lightweight models have faster inference speed.
Control output length	Set max_tokens appropriately to avoid unnecessarily long output.	Reduces generation time.

Q23: How to handle high-concurrency scenarios?

For business scenarios requiring high-concurrency calls, the following architecture is recommended:

Async concurrency: The official SDK provides the AsyncUniverseClient async client (corresponding to the synchronous UniverseClient), which can send multiple requests simultaneously without blocking -- ideal for high-concurrency scenarios.

import asyncio
from universeai import AsyncUniverseClient

async def process_batch(prompts):
    client = AsyncUniverseClient(api_key="YOUR_API_KEY")
    tasks = [
        client.chat.completions.create(
            model="universe-3.0",
            messages=[{"role": "user", "content": p}]
        )
        for p in prompts
    ]
    return await asyncio.gather(*tasks)

results = asyncio.run(process_batch(["Question 1", "Question 2", "Question 3"]))

Connection pool management: Reuse HTTP connections to avoid the overhead of frequently establishing and tearing down connections.

Rate control: Use a token bucket or leaky bucket algorithm to control the request sending rate and avoid triggering 429 rate limits.

Multi-Key rotation: Assign multiple API Keys for different business scenarios to distribute request load.

Q24: What to do when encountering platform failures or service instability?

If you encounter service unavailability or abnormal responses, follow these troubleshooting steps:

1. Check the official status page: Confirm whether there is a known platform-level issue.
2. Rule out local issues: Check your own network, DNS resolution, and firewall settings.
3. Retry mechanism: Implement exponential backoff retry for 5xx errors; temporary failures usually recover within a few minutes.
4. Backup endpoint: If possible, configure a backup API endpoint for failover.
5. Contact technical support: If the issue persists for more than 15 minutes, provide the Request ID and error information to the technical support team.

---

More Help

If this document does not resolve your issue, you can get help through the following channels:

• View full documentation: API Reference - Model Product Introduction - Prompt Engineering Guide
• Submit feedback: Click the feedback button in the top-right corner of the page and describe the issue you encountered
• Contact technical support: Provide your account information and Request ID, and the technical team will respond as soon as possible