Hy3 API Quick Start for Agentic and Long-Context Workflows

Tencent’s Hy3 is available on Novita AI with the model ID tencent/hy3, an OpenAI-compatible chat/completions endpoint, a 256K context window, and support for function calling, structured outputs, and three reasoning modes. This quick start covers the developer setup: configure your client, send your first request, use function calling, enable reasoning, and understand the rate limits before you build.

When to Use This Quick Start

Use this guide when you need a working request to Hy3 before writing any additional code. It covers a practical path: pick the model ID, authenticate, send one test request, then extend to function calling or reasoning as your workload needs.

Hy3’s architecture — a 295B total, 21B active MoE — is designed to balance quality and efficiency at scale. It is worth considering when you need:

• Long-context document processing (the 256K window fits roughly 200,000 words in one call).
• Multi-turn dialogue that benefits from a large active parameter budget.
• Agentic tasks where tool calling and reliable argument formatting matter.
• Coding assistance that spans large codebases without chunking.

This guide covers only the API integration path via Novita AI. It does not cover self-hosting, fine-tuning, or porting to other inference backends.

Step 1: Get Your Novita API Key

Create a Novita AI account and navigate to the API keys section of your console. Generate a key and store it in an environment variable. Keep it out of client-side code, frontend bundles, and public repositories.

export NOVITA_API_KEY="your_api_key"

If you already use the OpenAI Python SDK or OpenAI-compatible clients in other projects, the setup here is the same — change the base URL and the model name, nothing else.

Step 2: Confirm the Model ID and Endpoint

These three values are all you need for configuration:

Item	Value
API key	Your Novita AI API key, stored as an environment variable
OpenAI-compatible base URL	https://api.novita.ai/openai
Chat completions endpoint	POST https://api.novita.ai/openai/v1/chat/completions
Model ID	tencent/hy3

Use tencent/hy3 in all API calls. In user-facing UI or documentation, use the display name “Hy3”.

The Novita AI documentation index lists the OpenAI-compatible base URL, and the chat completions API reference documents the full request and response shape.

Step 3: Check Pricing, Limits, and Model Details

Current values from the Hy3 model page on Novita AI:

Field	Value
Display name	Hy3
API model ID	tencent/hy3
Model series	Hunyuan
Architecture	MoE, 295B total / 21B active
Endpoint	chat/completions
Input modalities	Text
Output modalities	Text
Context window	262,144 tokens
Max output tokens	262,144 tokens
Features	Serverless, function calling, structured outputs, reasoning
Input price	Listed at $0 / M tokens (verify current rate on model page)
Output price	Listed at $0 / M tokens (verify current rate on model page)

Rate limits scale by account tier (T1–T5) and are measured in requests per minute (RPM) and tokens per minute (TPM). Current tier thresholds and limits are listed in the Novita AI rate limits documentation.

Pricing and rate limits can change. Check the Hy3 model page and the Novita AI pricing page before committing to any cost estimate.

Step 4: Send Your First Request

Start with a simple text request to confirm authentication, model routing, and response parsing. Keep the prompt short so you are testing connectivity, not output quality.

cURL Example

curl "https://api.novita.ai/openai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${NOVITA_API_KEY}" \
  -d '{
    "model": "tencent/hy3",
    "messages": [
      {
        "role": "system",
        "content": "You are a concise technical assistant."
      },
      {
        "role": "user",
        "content": "Describe the main trade-off between MoE and dense transformer architectures in three sentences."
      }
    ],
    "max_tokens": 256,
    "temperature": 0.3
  }'

A successful response returns the standard chat completions shape: a choices array, a message with content, model and created metadata, and a usage object with prompt, completion, and total token counts.

Use this smoke test to verify:

• The API key is valid and the authorization header is correctly formatted.
• The model ID tencent/hy3 is accepted without a 404 or model-not-found error.
• Your client can parse choices[0].message.content.
• Token usage is logged so you can monitor costs from the first request.

Python Example

The OpenAI Python SDK works with Novita AI when you set the base URL:

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai",
    api_key=os.environ["NOVITA_API_KEY"],
)

response = client.chat.completions.create(
    model="tencent/hy3",
    messages=[
        {"role": "system", "content": "You are a concise technical assistant."},
        {
            "role": "user",
            "content": "Describe the main trade-off between MoE and dense transformer architectures in three sentences.",
        },
    ],
    max_tokens=256,
    temperature=0.3,
)

print(response.choices[0].message.content)
print("Tokens used:", response.usage.total_tokens)

Step 5: Read the Response

The response follows the standard OpenAI chat completions format:

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1751000000,
  "model": "tencent/hy3",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "MoE models activate only a fraction of their total parameters..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 52,
    "completion_tokens": 80,
    "total_tokens": 132
  }
}

The finish_reason field tells you why generation stopped. stop means the model reached a natural ending. length means max_tokens was hit. If you see length on short prompts, raise max_tokens or reduce the prompt.

Key Parameters

Parameter	Type	Effect
model	string	Must be tencent/hy3
messages	array	Conversation history. system, user, and assistant roles are supported.
max_tokens	integer	Cap on output tokens. Set explicitly; the default may vary by client.
temperature	float (0–2)	Lower values produce more deterministic output. Use 0.1–0.3 for code and factual tasks; 0.7–1.0 for creative or varied outputs.
top_p	float (0–1)	Alternative to temperature for sampling. Avoid setting both at once.
stream	boolean	Set true to receive tokens as a stream. Requires server-sent event handling on your client.
tools	array	Tool definitions for function calling. See the function calling section below.
tool_choice	string or object	Controls which tool the model calls. "auto" lets the model decide.

For long-context workloads, Hy3 supports up to 262,144 input tokens. Budget token usage per call and monitor cumulative cost if you are processing large documents or long conversation histories.

Function Calling

Hy3 supports function calling through the tools parameter. Use it when you want the model to return structured arguments instead of prose — routing a request to a specific action, parsing user input into typed fields, or driving a multi-step workflow.

import os
import json
from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai",
    api_key=os.environ["NOVITA_API_KEY"],
)

tools = [
    {
        "type": "function",
        "function": {
            "name": "search_knowledge_base",
            "description": "Search a product knowledge base for answers to customer queries.",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "The customer's question or topic to search for.",
                    },
                    "max_results": {
                        "type": "integer",
                        "description": "Maximum number of results to return. Default is 5.",
                    },
                },
                "required": ["query"],
            },
        },
    }
]

response = client.chat.completions.create(
    model="tencent/hy3",
    messages=[
        {"role": "system", "content": "You are a customer support assistant. Use the search tool to find relevant answers."},
        {
            "role": "user",
            "content": "What is your return policy for electronics purchased in the last 30 days?",
        },
    ],
    tools=tools,
    tool_choice="auto",
    temperature=0.1,
)

message = response.choices[0].message
if message.tool_calls:
    for call in message.tool_calls:
        print(f"Tool: {call.function.name}")
        args = json.loads(call.function.arguments)
        print(f"Arguments: {args}")
else:
    print(message.content)

When the model returns a tool call, your application executes the function, then sends the result back in the conversation:

# After executing your search function, send the result back
tool_result = "Returns accepted within 30 days with original receipt. Electronics must be unopened."

follow_up = client.chat.completions.create(
    model="tencent/hy3",
    messages=[
        {"role": "system", "content": "You are a customer support assistant."},
        {"role": "user", "content": "What is your return policy for electronics purchased in the last 30 days?"},
        message,  # the assistant's tool call message
        {
            "role": "tool",
            "tool_call_id": message.tool_calls[0].id,
            "content": tool_result,
        },
    ],
    temperature=0.1,
)

print(follow_up.choices[0].message.content)

Test your tool schemas on representative queries before routing production traffic. The quality of function argument extraction depends on how clearly you describe each parameter and its expected values.

Reasoning Mode

Hy3 lists reasoning as a supported feature on the Novita AI model page. Reasoning-capable models think through a problem before producing a final answer, which can improve output quality on complex multi-step problems — code debugging, multi-step math, long-document analysis, and planning tasks.

The Novita AI chat completions API supports reasoning-related parameters (separate_reasoning, enable_thinking) for select models. Whether these parameters are accepted by tencent/hy3 and the exact request format are not confirmed in current Novita documentation. Before building reasoning behavior into a production workflow with Hy3, run a test call and check whether the response includes a reasoning_content field in choices[0].message.

For verified parameter names and supported model IDs, see the Novita AI chat completions API reference and the Reasoning Models guide.

Long-Context Usage

Hy3’s 256K context window is a practical advantage for tasks that require holding a large body of text in a single call. Use cases where this matters:

• Document analysis: Send a full contract, research paper, or specification as context and ask targeted questions without chunking.
• Codebase review: Pass a large file or multiple related files and ask for architecture observations, bug patterns, or refactoring suggestions.
• Long conversation history: Agentic workflows that accumulate many turns can stay in context longer before requiring summarization or truncation.

For long-context calls, set max_tokens explicitly based on your expected output length. Sending 200K tokens of input and leaving the output token budget at its default wastes context budget and may produce truncated responses.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai",
    api_key=os.environ["NOVITA_API_KEY"],
)

with open("large_document.txt") as f:
    document_text = f.read()

response = client.chat.completions.create(
    model="tencent/hy3",
    messages=[
        {
            "role": "system",
            "content": "You are a document analysis assistant. Provide specific, referenced answers.",
        },
        {
            "role": "user",
            "content": f"Here is the document:\n\n{document_text}\n\nSummarize the key obligations and deadlines in this document.",
        },
    ],
    max_tokens=1024,
    temperature=0.2,
)

print(response.choices[0].message.content)

Monitor usage.prompt_tokens in the response to track how many tokens your inputs consume. For workloads that repeatedly send the same system prompt or document preamble, rate limit and cost planning depends on the actual prompt token count, not just the document character count.

Troubleshooting

401 Unauthorized: The API key is missing, expired, or incorrectly formatted. Check that the Authorization header reads Bearer <your_key> with a space and no extra characters.

404 or model not found: The model ID is wrong. Confirm the exact string tencent/hy3 matches the ID shown on the Novita AI model page. Model IDs are case-sensitive.

429 Rate Limit: You have exceeded the requests or tokens per minute for your tier. Add retry logic with exponential backoff, or request a higher tier if your workload requires it consistently.

finish_reason: length: The response was cut short because it hit max_tokens. Raise the max_tokens value if you need longer outputs, but remember that output tokens affect cost and latency.

Slow first response: Large model deployments can have a brief cold-start latency on the first request. Subsequent requests to the same endpoint are typically faster. If latency is a hard requirement, test throughput at your target concurrency level before production launch.

Tool call returns unexpected arguments: Revise your tool schema. Add more specific descriptions to each parameter, include example values in the description field, and list required fields explicitly. Test with simplified schemas first, then layer in complexity.

FAQ

Is Hy3 available on Novita AI?

Yes. Novita AI lists Hy3 as a Serverless LLM with the API model ID tencent/hy3.

What is the correct model ID?

Use tencent/hy3 in all API calls. Use “Hy3” in user-facing text.

What endpoint should I use?

Use the OpenAI-compatible chat completions endpoint: POST https://api.novita.ai/openai/v1/chat/completions. Set the base URL to https://api.novita.ai/openai when using the OpenAI SDK.

How large is the context window?

Hy3 supports a 262,144-token context window and up to 262,144 output tokens, as listed on the Novita AI model page.

Does Hy3 support function calling?

Yes. Hy3 supports function calling through the tools parameter in the chat completions request. Novita lists function calling and structured outputs as supported features.

Does Hy3 support reasoning?

Reasoning is listed as a feature on the Novita AI model page. The specific request parameters for enabling reasoning with tencent/hy3 are not confirmed in current Novita documentation. Check the Novita AI chat completions API reference and run a test call to verify the parameter format before building reasoning behavior into production.

What inputs does Hy3 accept?

Hy3 accepts text inputs only. It does not list image or video modalities on the Novita AI model page.

What is Hy3’s architecture?

Hy3 uses a MoE (Mixture of Experts) architecture with 295B total parameters and 21B active parameters per forward pass. This allows it to serve large-context requests at lower compute cost compared to dense models of similar quality.

How do I get a higher rate limit?

Rate limits scale by account tier. Current tier thresholds and limits are listed in the Novita AI rate limits documentation. Contact Novita AI support for upgrade options.

Recommended Articles

• Function Calling and Structured Outputs on Novita AI
• How to Develop a Deep Search Agentic Workflow With LangChain and Novita AI’s LLM API
• Hunyuan Image 3 API on Novita AI: Text-to-Image Generation Guide