Your first working request
You need a TalkNova account and a personal API key. Free accounts can use the API too.
- 1
Get your key
Sign in and open API Access. Create a personal key and keep it private.
- 2
Set it on your computer or server
Pick your operating system. Replace the placeholder, then run the command in your terminal.
macOS / Linux · environment variable# macOS / Linux: replace the placeholder with your personal key. export TALKNOVA_API_KEY='YOUR_TALKNOVA_KEY' - 3
Choose a model and copy an example
The example uses your selection below. Copying it does not run a request or use your allowance.
Examples use the published catalog while the live list loads.
curl --fail-with-body 'https://talknova.site/v1/chat/completions' \
-H "Authorization: Bearer $TALKNOVA_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "claude-opus-5-5",
"messages": [
{
"role": "user",
"content": "Hello from TalkNova!"
}
],
"max_tokens": 4096
}'cURL examples use Bash on macOS/Linux. Select PowerShell for Windows. Run Python or JavaScript examples on your server; never put a personal API key in public browser code.
Base URL & endpoints
For OpenAI-compatible applications, choose Chat Completions or stateless Responses. Text keys discover their permitted text models; a separate video-only key discovers video models and cannot run text chat. A model copied from another service is not automatically a TalkNova model: fetch the current IDs with your own key.
Paste https://talknova.site/v1 into your client’s OpenAI-compatible base URL field. Add the endpoint only when making a raw HTTP request.
https://talknova.site/v1Full chat endpointhttps://talknova.site/v1/chat/completionsDo not put /chat/completions in an SDK’s base URL field. The canonical version is /v1, with the letter v immediately followed by 1. Clients such as eGPT can choose Responses with store:false. Both protocols use the same key, model permissions and usage accounting.
| Task | Method | Endpoint after the base URL |
|---|---|---|
| List text models | GET | /models |
| List all model types | GET | /models?type=all |
| Send a message | POST | /chat/completions |
| Stateless Responses | POST | /responses |
| Roleplay message | POST | /roleplay/chat/completions |
| Check usage | GET | /usage |
| Video options | GET | /video/models |
| Create a video | POST | /video |
| Read a video job | GET | /video/{id} |
| Download a video | GET | /video/{id}/content |
| Generate an image | POST | /images/generations |
Open API discovery for a machine-readable list. All examples here use TalkNova’s public connection address.
Claude Sonnet 5.5
For Chat Completions, use claude-sonnet-5-5 with reasoning_effort set to low, medium, high, xhigh, or max. Set function tool selection to auto and use parallel_tool_calls: false if your client sends that setting.
For Anthropic-compatible clients, the full endpoint is https://talknova.site/v1/messages. Anthropic SDKs that append /v1/messages use https://talknova.site as their base URL. Supply the same TalkNova text API key. Use thinking.type: adaptive with output_config.effort. Between-tools mode skips up-front thinking and accepts low, medium, or high effort.
Responses API
POST /v1/responses supports stateless text/image conversations and function tools using the same key and model IDs. Set store:false and send the full input history on every turn. Stored-response retrieval, previous_response_id, background mode and hosted tools are unavailable.
const response = await client.responses.create({
model: "claude-opus-5-5",
store: false,
instructions: "Give concise, accurate answers.",
input: "Explain this code.",
max_output_tokens: 4096,
reasoning: { effort: "medium" },
include: ["reasoning.encrypted_content"]
});
console.log(response.output_text);Use flat function tools: {type:"function", name:"read_file", parameters:{type:"object", properties:{}, additionalProperties:false}, strict:true}. Selection accepts auto, none, required or {type:"function", name:"read_file"}; parallel_tool_calls:false requests one call at a time. Your application executes the tool with its own permission checks.
const next = await client.responses.create({
model: "claude-opus-5-5", store: false,
input: [
...previousInput, ...response.output,
{ type: "function_call_output", call_id: call.call_id, output: toolResult }
],
tools, max_output_tokens: 4096
});With stream:true, read response.output_text.delta and response.function_call_arguments.delta. A successful stream ends with response.completed, including the full response and complete arguments. Check status before executing a call: interrupted/provider failures produce response.failed; output limits produce response.incomplete. Partial output is never automatically replayed.
Use the model’s advertised reasoning efforts (GPT-6.1 Sol includes low, medium and high). include:["reasoning.encrypted_content"] returns encrypted continuation only when the provider produces reasoning. This is TalkNova’s opaque continuation format, bound to your current key and model for24hours; it is not interchangeable with another provider’s ciphertext. Preserve the full reasoning item in history. No raw reasoning summary is generated. safety_identifier accepts an opaque identifier; never send an email or other unnecessary personal data. Responses are not saved for later retrieval; existing usage/security metadata retention still applies.
Structured output uses text.format: text, json_object or json_schema with name/schema/strict. Validate generated JSON and tool arguments in your application.
Your API key
Send your personal tn-live- key in the Authorization header:
Authorization: Bearer YOUR_TALKNOVA_KEY- Use one personal key across your trusted clients. Its usage belongs to your account.
- Rotating your key stops new requests with the old key. It does not reset usage or cancel already running work.
- Keep the key out of screenshots, public code and browser JavaScript. If exposed, rotate it on API Access.
What about an admin-issued custom key?
An active tn-custom- key is a separate, admin-managed chat-only balance, with its own model restrictions. It does not inherit an account’s monthly allowances. Revoked or disabled keys cannot be used. The examples in this guide use personal account keys.
Choose a model
Use the exact public id from GET /v1/models. Display names are for reading; IDs go into requests. Your selected example ID is claude-opus-5-5.
curl --fail-with-body 'https://talknova.site/v1/models?type=all' \
-H "Authorization: Bearer $TALKNOVA_API_KEY"| Field | How to use it |
|---|---|
id | Copy it into the model field. |
capabilities | Check tool_calling, vision, streaming, web_search and reasoning_efforts. |
context_length | The advertised context size, where reported. It is not a guarantee every request size is accepted. |
max_output_tokens | TalkNova’s current output cap. Reasoning tokens also consume this budget. |
health | Available, checking, degraded or unavailable. Try another model if a route is unavailable. |
usage_policy | The shared text, monthly USD allowances and model-specific input/output rates. |
Browse the model directory . Retired IDs are rejected; an old saved conversation remains readable.
For the models in this guide, start with OpenAI-compatible Chat Completions. A client’s protocol and requested model ID must both be supported; changing only its base URL cannot add an unsupported model or protocol.
Send a message
POST /v1/chat/completions accepts a model ID and conversation history. Include earlier user and assistant messages when you want the model to remember the conversation.
{
"model": "claude-opus-5-5",
"messages": [
{
"role": "user",
"content": "Hello from TalkNova!"
}
],
"max_tokens": 4096
}| Parameter | Use it for |
|---|---|
model | Required. A current public model ID. |
messages | Required. User, assistant, system and tool messages; at most 10,000. |
max_tokens | Output budget. max_completion_tokens is also accepted. Start with 4,096 for reasoning tasks; the live model cap and your remaining allowance still apply. |
stream | true for a stream; false or omitted for one JSON response. |
reasoning_effort | Use only an effort listed by the chosen model. Unsupported values return 400. |
tools / tool_choice | Function calling, where advertised. |
temperature / top_p / stop | Sampling controls. Support varies by model. |
response_format | JSON output where supported. Always validate the generated result. |
What does a JSON response look like?
{
"id": "chatcmpl-example",
"object": "chat.completion",
"model": "claude-opus-5-5",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Hello!"
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 25,
"completion_tokens": 8,
"total_tokens": 33
}
}stop means the answer ended. length means the output budget was reached. Check message.tool_calls when using tools; do not rely only on the finish reason.
Streaming
Use stream: true to show an answer as it arrives. The format is Server-Sent Events (SSE), ending with data: [DONE].
curl -N 'https://talknova.site/v1/chat/completions' \
-H "Authorization: Bearer $TALKNOVA_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "claude-opus-5-5",
"messages": [
{
"role": "user",
"content": "Write a short greeting."
}
],
"stream": true,
"max_tokens": 4096,
"stream_options": {
"include_usage": true
}
}'data: {"choices":[{"delta":{"content":"Hello"},"finish_reason":null}]}
data: {"choices":[],"usage":{"prompt_tokens":25,"completion_tokens":8,"total_tokens":33}}
data: [DONE]- Read
choices[].delta.contentfor answer text. A model may also send reasoning or tool-call deltas. - Usage-only chunks have an empty
choicesarray. Check the array before accessing its first element. - A stream can contain an
errorevent after HTTP headers were sent. HTTP 200 alone does not prove success. - Preserve partial output on disconnect. Do not automatically replay a request that may already have run.
Tool calling
Choose a model reporting capabilities.tool_calling: true. Your application defines the functions and executes approved calls; a model response alone does not execute code.
- Send your function definitions in
tools. - Read
message.tool_calls. Validate the function name and JSON arguments against your allowlist. - Run the permitted function, then append the original assistant message and a
role: "tool"result with the sametool_call_id. - Send the updated history to get the final answer.
{
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get weather for a city",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string"
}
},
"required": [
"city"
]
}
}
}
],
"tool_choice": "auto"
}Use tool_choice: "auto" to start. Forced tool selection is model-dependent. In streams, assemble tool arguments across chunks before parsing them. Tool calls and reasoning use the model’s normal token rates; validate side effects in your own application.
Understand attached images
Vision means a chat model can read an image. It is separate from generating a new image. Select a model reporting capabilities.vision: true.
import base64
import json
import os
from urllib.request import Request, urlopen
with open("photo.png", "rb") as file:
image = base64.b64encode(file.read()).decode()
body = {
"model": "claude-opus-5-5",
"max_tokens": 4096,
"messages": [{"role": "user", "content": [
{"type": "text", "text": "Describe this image."},
{"type": "image_url", "image_url": {"url": "data:image/png;base64," + image}}
]}]
}
request = Request("https://talknova.site/v1/chat/completions",
data=json.dumps(body).encode(),
headers={"Authorization": "Bearer " + os.environ["TALKNOVA_API_KEY"],
"Content-Type": "application/json"})
with urlopen(request) as response:
result = json.load(response)
if result.get("error"):
raise RuntimeError(result["error"])
print(result["choices"][0]["message"]["content"])Send validated image data URLs. Keep each image within the API’s size limit and the complete request under 24 MB. A public URL is not a substitute for a supported data URL.
Reasoning & web search
Reasoning levels vary by model. Use the chosen model’s live capabilities.reasoning_efforts and default_reasoning_effort. There is no universal Low-to-Max scale.
Currently listed efforts: low, medium, high, xhigh, max.
Where capabilities.reasoning_effort_mapping is listed, the selected effort is a gateway target. For example, Muse Spark’s Max target currently uses High upstream, including coding mode. Read x-talknova-requested-effort separately from the applied x-talknova-reasoning-effort header. A target is not proof of provider-native Max. No verified Nova thinking-off mode is offered.
Some models require a minimum output budget to finish reasoning before answering. TalkNova applies a floor where needed; a request can still be capped by your remaining USD allowance. Reasoning tokens count toward output usage.
Use web_search: true only if the model reports capabilities.web_search: true. A model without that capability returns 400. Search being enabled does not mean the model used it. If usage.search_status is pending_reconciliation, keep the completed answer. Verified token charges and a temporary search hold are tracked separately. Do not retry generation to settle a search hold.
Generate an image
Use a personal key and a model from /models?type=image. One image per request; the monthly image count is shared with the site and apps.
curl --fail-with-body 'https://talknova.site/v1/images/generations' \
-H "Authorization: Bearer $TALKNOVA_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "nano-banana-pro",
"prompt": "A watercolor fox in a snowy forest"
}'Check the JSON body for an error even if HTTP 200 was sent as a keep-alive. Save the returned data[0].b64_json image locally.
Generate and download a video
Video generation returns a job. Create it, check its progress, then download the MP4. Use a personal key.
- Read
GET /v1/video/modelsfor supported durations, qualities, aspect ratios and starting/ending image rules. - Create the job with
POST /v1/video. Use only options listed by that model. - Poll
GET /v1/video/{id}every few seconds until completed or failed. - Download
GET /v1/video/{id}/contentwhile the file is available.
curl --fail-with-body 'https://talknova.site/v1/video' \
-H "Authorization: Bearer $TALKNOVA_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "seedance-2.0-fast",
"prompt": "A paper boat floating down a rainy street",
"duration": 5
}'# Replace JOB_ID with the id returned by the create request.
curl 'https://talknova.site/v1/video/JOB_ID' \
-H "Authorization: Bearer $TALKNOVA_API_KEY"
# Run after status becomes completed.
curl --fail-with-body -o video.mp4 'https://talknova.site/v1/video/JOB_ID/content' \
-H "Authorization: Bearer $TALKNOVA_API_KEY"One unfinished video per account. Each job reserves one monthly video unit; a failed or undelivered render is refunded. Finished files normally expire after 14 days. Download important results before they expire.
Roleplay apps
Use the same key, model IDs and monthly allowance. The roleplay endpoint preserves the caller’s character/system messages and skips TalkNova’s optional formatting prompt.
| Your client asks for | Paste this |
|---|---|
| OpenAI-compatible base URL | https://talknova.site/v1 |
| Full roleplay/proxy endpoint | https://talknova.site/v1/roleplay/chat/completions |
| API key | Your personal TalkNova key |
| Model | An exact ID from GET /v1/models |
For Janitor AI, choose its proxy option and use the full roleplay endpoint. Other compatible clients can use the public X-TalkNova-Plain: 1 header. Plain mode omits TalkNova’s formatting instructions; it does not change key permissions, model access, rate limits, accounting or the model provider’s policies. Usage reflects the input actually sent and generated output, with estimates identified when exact usage is unavailable.
Usage & limits
Your plan has one monthly text USD allowance you can spend on any text model, shared across the website, Mac, Windows, Android and your personal API key. Images and video have separate generation counts.
| Monthly usage | Free | Basic | Plus | Max |
|---|---|---|---|---|
| Text | $15 / month | $300 / month | $600 / month | $1000 / month |
| Images | 2 / month | 50 / month | 200 / month | 400 / month |
| Videos | 1 / month | 10 / month | 15 / month | 30 / month |
Monthly allowances reset on the 1st of each month, UTC. Switching devices/models, rotating a key or opening more terminals does not reset usage. Check GET /v1/usage for used, remaining, reserved, reset time and max_concurrent_generations.
usage_policy on each model lists its input/output USD rate and shared text. TalkNova internal USD rates are usage-metering amounts, not a statement of upstream expenditure. Account-issued personal keys use this shared text allowance; standalone admin-issued custom keys use their independent balance.
When a response reports usage.estimated: true, the model service omitted complete token counts. TalkNova conservatively meters the reserved input estimate and output maximum, including possible hidden thinking. Set max_tokens to what your task needs. Tool-call rounds and their follow-up answers are metered separately.
Requests, concurrent work and reserved usage
| Limit | What it means |
|---|---|
| Concurrent generations | Two active generations per personal account across the website, apps, CLI, API keys and models. Extra calls may queue before inference starts. Standalone prepaid keys use their own policy. |
| Nova Spectrum requests/minute | Free: 5 · Basic: 15 · Plus: 30 · Max: 60 |
| Other request limits | Model, endpoint and account rate limits also apply. Follow Retry-After and the structured error. |
| Output size | Read the live max_output_tokens. The remaining allowance may lower your request cap. |
| Conversation size | At most 10,000 supplied messages. Long contexts may be trimmed; x-talknova-context-truncated reports omitted messages. |
| Reserved USD | Running or uncertain requests hold part of the allowance. It is already excluded from remaining USD; do not subtract it twice. |
When your shared text allowance is exhausted, a new request is refused before model generation. If a previous request has an uncertain outcome, its hold may remain until reconciliation. A confirmed partial response can still incur usage.
Troubleshooting
Check the HTTP status, error code and TalkNova request ID. Use streaming for long generations. SSE may send heartbeat comments while queued or reasoning, and a later failure can arrive as an error event after HTTP 200. A response with cf-mitigated: challenge is an edge challenge.
{"error":{"message":"Your monthly allowance is used.","type":"insufficient_quota","code":"allowance_exhausted"}}| Status | Meaning | Next step |
|---|---|---|
| 400 | Invalid parameters, unsupported effort/tools/images or model ID. | Read the message and model capabilities; change the request before retrying. |
| 401 | Missing, invalid or revoked key. | Check your personal key in API Access. Repeated failed attempts are throttled (429). |
| 402 | Your account shared text allowance or standalone key balance cannot cover the request. | Read shared text, remaining/held amounts and resets_at. Use a smaller request, upgrade or wait for reset. |
| 429 | Rate limit, busy account or model capacity. | Respect Retry-After. Do not open parallel clients to bypass it. |
| 502 / 503 / 504 | Unavailable service, interrupted connection or uncertain generation. | Read error.code and usage.status. Avoid replaying uncertain work automatically. |
TalkNova retries definite transient rejections within a bounded budget. If autoRetryExhausted is true, wait or choose another model. A request marked pending_reconciliation may already have started; it is not safe to assume nothing happened. Keep your request ID when contacting support, and never send your key.
Connected tools (MCP)
MCP lets TalkNova web chat call external tools you connect. Add a server in chat’s tool settings, test the connection, and choose a model with tool support.
The website blocks localhost, private networks and internal addresses. A local stdio server cannot be reached directly by the website. If you bridge it to HTTP, expose it through a secure authenticated public endpoint and connect that URL.
Only connect tools you trust. Your configured server receives the requests and authentication needed to use it. Review permissions and tool arguments before granting access to files, accounts or actions. Tool-loop limits and network protections still apply.
Privacy & policies
Chats sync automatically to your account. Covered API/chat requests and responses also enter default-on 72-hour support logs, accessible to authorized administrators with audited access. External AI infrastructure processes the prompts and attachments needed for a response.
Read the Privacy Policy, Terms and Acceptable Use rules. Do not submit passwords, API secrets or unnecessary sensitive data. Developers integrating TalkNova must give their own users appropriate notices.
Policy endpoints and acknowledgements
GET /v1/legal reports the current policy. Personal-key clients can read GET /v1/legal/status and record an actual user agreement using POST /v1/legal/acknowledge with {"version":"2026-11-14.1","agreeTerms":true,"acknowledgePrivacy":true}. Never accept on someone else’s behalf. An acknowledgement is not blanket consent or a waiver of statutory rights.