Developer platform

SenseNova API

Developer overview for SenseTime, including API access, pricing, SDK support, endpoints, capabilities and platform policies.

Documentation API reference

API key Required

Primary API SenseNova Token Plan API with OpenAI-compatible image endpoints and SenseNova conversational APIs

SDK support Raw HTTPS and OpenAI-compatible clients are supported. An official current Python, JavaScript, or PHP SDK package for the Token Plan API was not reliably verified.

Rate limits The current public-beta announcement documents 1,500 requests every five hours for SenseNova U1.5 Lite. Broader account, model, and production rate limits were not reliably verified.

Platform

API overview

Endpoints

API access

Base URL


					https://token.sensenova.cn/v1

Primary API SenseNova Token Plan API with OpenAI-compatible image endpoints and SenseNova conversational APIs

Pricing

API pricing

Pricing model Usage- and quota-based API pricing; selected models may have public-beta quotas

SenseNova U1.5 Lite currently has a documented free public-beta quota of 1,500 requests every five hours. General commercial model pricing was not reliably verified from the accessible official pages.

Developer experience

SDKs & usability

SDKs Raw HTTPS and OpenAI-compatible clients are supported. An official current Python, JavaScript, or PHP SDK package for the Token Plan API was not reliably verified.

Ease of use Moderate; REST and OpenAI-compatible patterns are familiar, but endpoint generations and model-specific documentation require careful verification.

Documentation Moderate; official endpoint documentation is available, but much of the canonical material is Chinese-language and the public English coverage is incomplete.

Resources

Developer links

Documentation ↗ API reference ↗ Playground ↗

Features

API capabilities

✓ Streaming

✓ Function calling

✓ Assistants API

✓ Image input

✓ Playground

Feature notes

The current documented Token Plan API uses Bearer API keys and exposes image generation at /images/generations and image editing at /images/edits. The latest public announcement documents the sensenova-u1.5-lite model, reference-image editing, prompt expansion, temporary image URLs, Base64 output, watermark controls, and up to 4096x4096 output. Earlier official documentation documents conversational multimodal calls at https://api.sensenova.cn/v1/llm/chat-completions, including image and video inputs and SSE streaming. SenseTime publicly announced function calling and an Assistants API in 2024. Current public documentation does not provide a complete, verifiable matrix for structured JSON output, general file upload, fine-tuning, latency tiers, or all assistant-runtime features, so those should be checked in the live console and account-specific documentation.

Examples

API examples

#!/usr/bin/env bash
set -euo pipefail

: "${SENSENOVA_API_KEY:?Set SENSENOVA_API_KEY first}"
BASE_URL="${SENSENOVA_BASE_URL:-https://token.sensenova.cn/v1}"
MODEL="${SENSENOVA_IMAGE_MODEL:-sensenova-u1.5-lite}"

response=$(curl --fail-with-body --silent --show-error \
  --request POST "$BASE_URL/images/generations" \
  --header "Authorization: Bearer $SENSENOVA_API_KEY" \
  --header "Content-Type: application/json" \
  --data "$(cat <<JSON
{
  "model": "$MODEL",
  "prompt": "A realistic photograph of a red fox in a snowy forest at sunrise",
  "n": 1,
  "size": "1024x1024",
  "watermark": true,
  "prompt_extend": true,
  "response_format": "url"
}
JSON
)")

printf '%s\n' "$response"

if command -v jq >/dev/null 2>&1; then
  printf 'Generated image URL: %s\n' "$(printf '%s' "$response" | jq -r '.data[0].url // empty')"
fi

# Installation: python -m pip install requests
import os
import sys
import requests

BASE_URL = os.getenv("SENSENOVA_BASE_URL", "https://token.sensenova.cn/v1")
API_KEY = os.getenv("SENSENOVA_API_KEY")
MODEL = os.getenv("SENSENOVA_IMAGE_MODEL", "sensenova-u1.5-lite")

if not API_KEY:
    raise SystemExit("Set SENSENOVA_API_KEY before running this program")

def generate_image(prompt: str) -> str:
    response = requests.post(
        f"{BASE_URL}/images/generations",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json={
            "model": MODEL,
            "prompt": prompt,
            "n": 1,
            "size": "1024x1024",
            "watermark": True,
            "prompt_extend": True,
            "response_format": "url",
        },
        timeout=120,
    )
    try:
        response.raise_for_status()
    except requests.HTTPError as exc:
        raise RuntimeError(f"SenseNova API error {response.status_code}: {response.text}") from exc
    payload = response.json()
    try:
        return payload["data"][0]["url"]
    except (KeyError, IndexError, TypeError) as exc:
        raise RuntimeError(f"Unexpected SenseNova response: {payload}") from exc

try:
    image_url = generate_image("A small sailboat on a calm blue lake under dramatic clouds")
    print(image_url)
except (requests.RequestException, RuntimeError) as exc:
    print(str(exc), file=sys.stderr)
    sys.exit(1)

// Installation: npm install openai
import OpenAI from "openai";

const apiKey = process.env.SENSENOVA_API_KEY;
if (!apiKey) {
  throw new Error("Set SENSENOVA_API_KEY before running this program");
}

const client = new OpenAI({
  apiKey,
  baseURL: process.env.SENSENOVA_BASE_URL || "https://token.sensenova.cn/v1"
});

try {
  const result = await client.images.generate({
    model: process.env.SENSENOVA_IMAGE_MODEL || "sensenova-u1.5-lite",
    prompt: "A futuristic glass greenhouse on Mars, cinematic lighting",
    n: 1,
    size: "1024x1024",
    response_format: "url",
    watermark: true,
    prompt_extend: true
  });

  const imageUrl = result.data?.[0]?.url;
  if (!imageUrl) {
    throw new Error(`Unexpected SenseNova response: ${JSON.stringify(result)}`);
  }
  console.log(imageUrl);
} catch (error) {
  const status = error?.status ? `HTTP ${error.status}: ` : "";
  console.error(`${status}${error.message}`);
  process.exitCode = 1;
}

<?php
$apiKey = getenv('SENSENOVA_API_KEY');
if (!$apiKey) {
    fwrite(STDERR, "Set SENSENOVA_API_KEY before running this program\n");
    exit(1);
}

$baseUrl = getenv('SENSENOVA_BASE_URL') ?: 'https://token.sensenova.cn/v1';
$model = getenv('SENSENOVA_IMAGE_MODEL') ?: 'sensenova-u1.5-lite';
$url = rtrim($baseUrl, '/') . '/images/generations';

$payload = json_encode([
    'model' => $model,
    'prompt' => 'A quiet Japanese garden after rain, realistic photography',
    'n' => 1,
    'size' => '1024x1024',
    'watermark' => true,
    'prompt_extend' => true,
    'response_format' => 'url'
], JSON_THROW_ON_ERROR);

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 15,
    CURLOPT_TIMEOUT => 120,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
        'Accept: application/json'
    ],
    CURLOPT_POSTFIELDS => $payload
]);

$body = curl_exec($ch);
if ($body === false) {
    $error = curl_error($ch);
    curl_close($ch);
    fwrite(STDERR, "Network error: {$error}\n");
    exit(1);
}

$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($body, true);
if ($status < 200 || $status >= 300) {
    fwrite(STDERR, "SenseNova API error {$status}: {$body}\n");
    exit(1);
}
if (!is_array($data) || !isset($data['data'][0]['url'])) {
    fwrite(STDERR, "Unexpected SenseNova response: {$body}\n");
    exit(1);
}

echo $data['data'][0]['url'] . PHP_EOL;
?>

Policies

Data & usage

Data training

The current SenseNova privacy policy states that customer data submitted through API services is not used to train models unless SenseNova has obtained the customer's explicit consent. The policy separately states that de-identified inputs and outputs may be used to maintain, secure, and enhance services and underlying technologies where applicable legal bases exist.

Data retention

The current privacy policy states that customer data may be stored on servers in Malaysia and that computing resources in mainland China may process inputs and generate outputs. Data is temporarily stored to provide API services or comply with law, and is deleted after termination of the applicable terms unless legal retention obligations apply.

Rate limits

The current public-beta announcement documents 1,500 requests every five hours for SenseNova U1.5 Lite. Broader account, model, and production rate limits were not reliably verified.

Developer guide

SenseNova API Guide: Access, Endpoints, Capabilities and Limits

SenseTime's SenseNova API gives developers access to selected conversational, multimodal, image-generation, image-editing and related AI services. The current documented Token Plan API uses Bearer API keys and an OpenAI-compatible HTTP format, with image endpoints at token.sensenova.cn/v1. SenseNova U1.5 Lite currently has a free public-beta quota of 1,500 requests every five hours, while broader commercial pricing and several advanced capabilities remain model- and account-dependent.

SenseNova is SenseTime's developer platform for connecting applications to selected foundation models and AI services. This guide explains how to obtain an API key, make a first image-generation request, understand the current endpoint structure, evaluate multimodal and conversational features, and account for unresolved questions around pricing, files, structured outputs and production limits.

SenseNova is SenseTime's developer platform for conversational, multimodal, image-generation and image-editing services. The guide covers access, Bearer authentication, current Token Plan endpoints, cURL and Python examples, the U1.5 Lite public-beta quota, streaming, function calling, privacy, SDK options and unresolved limits around files and structured outputs.

What is the SenseNova API?

SenseNova is SenseTime's current developer platform for accessing selected AI models and services through HTTPS APIs. It is intended for developers building applications rather than for people using SenseTime's consumer-facing assistants directly.

The platform covers more than one type of service. Depending on the model and account, developers may encounter conversational language models, multimodal requests, image generation, image editing, character or assistant experiences, and other SenseTime AI services. The most clearly documented current Token Plan interface uses an OpenAI-compatible request style for image generation and editing.

The documented Token Plan base URL is https://token.sensenova.cn/v1. The current public announcement identifies sensenova-u1.5-lite as an image model and documents the following endpoints:

POST /images/generations for creating images from prompts.
POST /images/edits for image editing and reference-image workflows.

SenseNova is a reasonable API to evaluate when an application needs China-oriented AI services, Chinese-language generation, image creation, image editing or multimodal processing. It is a less obvious choice when a project requires a mature global subscription ecosystem, consistently complete English documentation, broadly published commercial pricing or a fully documented feature matrix across every model.

Who should use SenseNova?

SenseNova is mainly relevant to:

Developers building Chinese-language or China-focused applications.
Teams that need text-to-image generation or image editing through an API.
Applications that need multimodal requests involving text and supported image or video inputs.
Organizations evaluating SenseTime's enterprise-oriented AI ecosystem.
Developers comfortable using raw HTTPS requests or OpenAI-compatible clients while platform details are still evolving.

It may be a poor fit for a project that depends on a stable, globally consistent consumer service, extensive third-party integrations, a fully documented official SDK for a particular programming language, or a universal no-configuration file and structured-output workflow. Several of those capabilities are either model-specific, incompletely documented, or not reliably verified in the current public materials.

How to get access and obtain an API key

API access begins in the SenseNova platform and developer console. A typical setup is:

Create or register a SenseNova account.
Complete any required account verification.
Open the developer or Token Plan area in the console.
Create an API key.
Check which models, quotas and endpoints are enabled for the account.

SenseNova API keys are sent as Bearer tokens. Keys reportedly begin with sk-, although applications should not depend on the prefix for validation. Store the key in an environment variable or secret manager. Do not place it in browser JavaScript, a mobile application bundle or source-control files, because anyone who receives the application can potentially extract it.

For example, set the key in a server-side shell before running an integration:

export SENSENOVA_API_KEY="your-api-key"
export SENSENOVA_BASE_URL="https://token.sensenova.cn/v1"
export SENSENOVA_IMAGE_MODEL="sensenova-u1.5-lite"

The console is important because SenseNova has multiple API generations and model-specific interfaces. Do not assume that an endpoint or model listed in older documentation is available for every account.

Choosing the appropriate API and model

Choose the API based on the operation rather than treating SenseNova as one interchangeable endpoint.

Task	Documented route or interface	What to verify
Text-to-image generation	`/images/generations` at the Token Plan base URL	Enabled image model, output format, size and quota
Image editing or reference-image workflows	`/images/edits` at the Token Plan base URL	Accepted image format, editing parameters and model access
Conversational or multimodal requests	SenseNova conversational API documentation	Current endpoint, model, supported media types and account access
Function calling or assistants	Announced SenseChat platform capabilities	Whether the feature is enabled and currently documented for the target API

For a new image integration, the current public example uses sensenova-u1.5-lite with https://token.sensenova.cn/v1. For conversational and multimodal work, the official documentation has described a SenseNova chat-completions interface with streaming and image or video inputs. Because the platform is changing, confirm the exact endpoint and model in the live console before deploying.

Make a first request with cURL

The simplest currently documented starting point is an image-generation request. This example uses the Token Plan API, Bearer authentication and a JSON body. It asks for one 1024-by-1024 image and requests a temporary URL in the response.

curl --fail-with-body --silent --show-error 
  --request POST "${SENSENOVA_BASE_URL}/images/generations" 
  --header "Authorization: Bearer ${SENSENOVA_API_KEY}" 
  --header "Content-Type: application/json" 
  --data '{
    "model": "sensenova-u1.5-lite",
    "prompt": "A realistic photograph of a red fox in a snowy forest at sunrise",
    "n": 1,
    "size": "1024x1024",
    "watermark": true,
    "prompt_extend": true,
    "response_format": "url"
  }'

A successful response contains generated data, including an image URL when response_format is set to url. The current announcement says these image URLs expire after 24 hours, so download or copy the image into durable storage if the application needs it later.

The same request in Python

The accessible official examples use ordinary HTTP requests rather than requiring a SenseNova-specific Python package. The following example uses the widely available requests library and includes basic status and response-shape checks.

import os
import requests

base_url = os.getenv("SENSENOVA_BASE_URL", "https://token.sensenova.cn/v1")
api_key = os.environ["SENSENOVA_API_KEY"]
model = os.getenv("SENSENOVA_IMAGE_MODEL", "sensenova-u1.5-lite")

response = requests.post(
    f"{base_url}/images/generations",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "model": model,
        "prompt": "A small sailboat on a calm blue lake under dramatic clouds",
        "n": 1,
        "size": "1024x1024",
        "watermark": True,
        "prompt_extend": True,
        "response_format": "url",
    },
    timeout=120,
)

response.raise_for_status()
payload = response.json()
image_url = payload["data"][0]["url"]
print(image_url)

Production code should handle network failures, non-JSON error responses, missing fields and temporary URLs rather than assuming every successful HTTP response has the expected shape.

Understanding the response

The documented image examples use a data array. For URL responses, the first generated item is read from a path such as data[0].url. If the API is configured to return Base64 output instead, the response shape and storage process will differ, so the application should inspect the selected response format and validate the returned field.

Do not treat the returned URL as permanent storage. The documented lifetime is 24 hours. A practical workflow is to check the HTTP status, parse the JSON, retrieve the image promptly and save it to storage controlled by the application.

For conversational APIs, the documentation describes usage information and streaming fields. A streaming response sends partial results as Server-Sent Events rather than waiting for the complete answer. The client must keep reading events, handle connection interruptions and assemble the final text or tool-related result according to the endpoint's response format.

How SenseNova pricing and quotas work

SenseNova does not currently present one universal subscription price for every API capability. Its API access is usage- or quota-based, with conditions varying by model, account and plan.

The current public-beta announcement for sensenova-u1.5-lite states that the model is available at no charge with a quota of 1,500 requests every five hours. The allowance is a public-beta quota, not a guarantee that all SenseNova models or future production accounts will remain free.

A complete, reliable commercial price table for all models was not verified from the accessible official material. Before budgeting a production system, check the live pricing page and console for:

Whether the selected model is free, token-priced, request-priced or otherwise metered.
Quota windows and account-level restrictions.
Production rate limits.
Image size, output-count or media-related charges.
Changes that may apply when the public beta ends.

What developers can access

Image generation and editing

The current Token Plan documentation supports text-to-image generation and image editing. The documented image model supports reference-image workflows, prompt expansion, watermark controls and output sizes up to 4096 by 4096. The API can return temporary URLs or Base64 output, depending on the request.

Multimodal input

SenseNova conversational documentation describes requests that can include text together with supported image and video inputs. Media limits and accepted formats are model-specific, so applications should use the limits shown for the enabled model rather than assuming that every conversational model accepts the same files or media sizes.

Streaming

Streaming is documented for conversational APIs through Server-Sent Events, commonly abbreviated as SSE. Instead of receiving one completed response, the client receives a sequence of events and can display or process partial output as it arrives. Streaming is useful for interactive interfaces, but it requires handling disconnects, incomplete streams and final usage or status information.

Function calling and assistants

SenseTime has publicly announced function calling and an Assistants API as part of the SenseChat platform. Function calling allows a model to request that an application invoke a defined function, such as looking up an order or calculating a value; the application remains responsible for executing and validating that operation.

The current public Token Plan material does not provide a complete, current reference for every tool-calling or assistant-runtime feature. Treat these capabilities as dependent on the product surface, model and account. Confirm the exact request schema and availability in the live developer documentation before building around them.

Files and structured outputs

General file upload is not reliably verified as a current, universally available Token Plan feature. Multimodal image and video inputs are documented for relevant conversational models, but that is not the same as a general-purpose file API.

Likewise, a complete current guarantee for structured JSON output was not verified. If an application requires schema-validated output, confirm that the selected model and endpoint explicitly support it. Do not infer this capability merely from the API's JSON transport format.

Advanced integration patterns

Image-editing workflow

For editing or reference-image generation, use the documented /images/edits route rather than sending an image-generation operation to the generation endpoint. Confirm the required multipart or JSON request format, accepted reference-image representation and model access in the current SenseNova documentation. The public materials establish the endpoint and capability, but do not provide a complete universal schema for every editing workflow.

Build a reliable client

A production client should keep the base URL and model name configurable. It should also:

Keep API keys on a trusted server.
Set connection and overall request timeouts.
Check HTTP status codes before parsing a response.
Handle rate-limit and transient-service failures with bounded retries.
Validate the response schema before using URLs, Base64 data or generated text.
Record request identifiers or safe operational metadata without logging private prompts or secrets.
Download temporary image URLs before they expire.
Use a model-specific test suite when changing models or endpoints.

SDKs, playground and developer tools

The safest currently documented integration method is raw HTTPS using requests, cURL or another ordinary HTTP client. The Token Plan interface is described as OpenAI-compatible for its documented image operations, and compatible clients may work when configured with the SenseNova base URL and key. However, the accessible official material did not verify a current first-party Python, JavaScript or PHP SDK package for the Token Plan API. Avoid assuming that examples for another provider's SDK are officially supported.

A SenseNova console and playground-like developer environment are available through the platform. Use them to create keys, inspect enabled services and test requests before moving code into production. The console is also the best place to confirm current model names, quotas and account-specific documentation.

Privacy and data handling

The current SenseNova privacy policy states that customer data submitted through API services is not used to train models unless SenseNova has obtained the customer's explicit consent. It separately describes possible use of de-identified inputs and outputs for maintaining, securing and improving services where applicable legal bases exist.

The policy states that customer data may be stored on servers in Malaysia and that computing resources in mainland China may process inputs and generate outputs. Data may be retained temporarily to provide the service or comply with legal obligations and is described as being deleted after termination of the applicable terms unless legal retention is required.

Organizations handling regulated, confidential or personal information should review the current privacy policy, data-processing terms, regional processing arrangements and any enterprise agreement before sending production data.

Important limits and uncertainties

SenseNova's public API information is not yet a complete single-version reference. The main issues to plan for are:

Multiple API generations: newer Token Plan examples use token.sensenova.cn/v1, while older conversational documentation uses a different SenseNova API surface.
Incomplete English coverage: important canonical documentation is largely Chinese-language, and public English material may not describe every parameter.
Model-specific features: media inputs, image sizes, quotas and response options can differ by model.
Unclear universal limits: broader rate limits, latency tiers, fine-tuning and general file upload were not reliably verified.
Temporary image results: documented image URLs expire after 24 hours.
Public-beta changes: the 1,500-request allowance for U1.5 Lite can change as the service moves beyond beta.
Regional availability: the ecosystem is strongly China-oriented, and account verification or access may vary by region.

These are reasons to test the exact account and model combination that will be used in production. They are not necessarily defects in every SenseNova deployment, but they make configuration discovery and monitoring important.

Advantages and limitations at a glance

Advantages	Limitations
Current image endpoints use a familiar OpenAI-compatible HTTP pattern.	Commercial pricing is not fully verifiable from the accessible public materials.
Supports documented image generation, editing and reference-image workflows.	API generations and endpoint documentation are not consolidated into one complete reference.
Conversational APIs document multimodal inputs and SSE streaming.	Files, structured outputs, fine-tuning and broader production limits are not fully documented.
A free public-beta quota is available for the documented U1.5 Lite model.	Availability and documentation are more China-oriented and less complete in English.
Raw HTTPS integration does not require a provider-specific SDK.	Temporary image URLs require prompt downloading and durable storage.

When SenseNova is a good or poor choice

SenseNova is a good candidate when the target users or deployment region align with SenseTime's China-focused ecosystem, when image generation or editing is central to the application, or when a team is comfortable integrating through documented HTTP endpoints and validating model-specific behavior.

It is a weaker choice when the project needs a globally uniform service with extensive English documentation, a clearly published price sheet for every capability, a guaranteed official SDK for a specific language, or a thoroughly documented file, structured-output and assistant-runtime stack. In those cases, compare the exact requirements against the live SenseNova console rather than relying only on high-level platform announcements.

For an evaluation, start with the free public-beta allowance where eligible, build a small server-side integration, measure response behavior and quota consumption, and verify privacy, regional processing and production pricing before committing application data or traffic.

Sources 7

platform.sensenova.cn/docs ↗ platform.sensenova.cn/product/APIService/document ↗ platform.sensenova.cn/product/APIService/pricing ↗ sensetime.com/en/news/sensenova-u1-5-lite-token-plan-20260911-1741 ↗ sensetime.com/en/news/51167493 ↗ platform.sensenova.ai/html/PrivacyPolicy.html ↗ www.sensetime.com/en/ ↗