TOKENSTAR DEVELOPER

Use one key for multi-model APIs

The page automatically uses the China or Global API root from the current domain, then lets you copy text, image, and video API examples. The temporary key only replaces examples in memory and is never uploaded or saved.

1Get an API key

2Confirm environment

Visible URLs and copied examples follow the current domain.

3Copy examples

Pick the API shape that matches your integration.

FAQ

Error codes, environment checks, and client troubleshooting now live on a dedicated FAQ page.

Open FAQ

Environment & Auth

Display and copy output automatically use the base URL for the current domain.

Temporary API Key

Used only in page memory and cleared after refresh.

Gateway roothttps://api.tokenstar.io

OpenAI Base URLhttps://api.tokenstar.io/v1

Claude Base URLhttps://api.tokenstar.io

Auth rule

All APIs use a platform API key. OpenAI-compatible APIs use Authorization: Bearer ${API_KEY}; Claude / Anthropic APIs use x-api-key: ${API_KEY}.

Base URL rules

OpenAI-compatible clients usually use a URL ending in /v1. Claude Code ANTHROPIC_BASE_URL uses the gateway root without /v1.

TokenStar Agent Skill

Package the public TokenStar docs into an AI-readable SKILL.md covering text, image, video, assets, callbacks, and client config.

Skill pathtokenstar-codex-gateway/SKILL.md

After downloading, place the file in this folder shape or pass the content to your agent or skill manager.

Key safetyThe Skill contains placeholders and environment variable names only. It never reads, stores, or writes the temporary API key entered on this page.

AGENT SKILL

SKILL.md preview

Text Generation APIs

Text generation supports OpenAI-compatible and Claude / Anthropic protocols. Choose by client or scenario.

POST/v1/chat/completionsOpenAI Chat CompletionsSync

Chat Completions

Call the OpenAI-compatible chat API with a platform API key.

Authentication

Authorization: Bearer <API_KEY>
Content-Type: application/json

Request parameters

Field	Required	Description
`model`	Yes	Built-in model ID
`messages`	Yes	OpenAI-compatible message array
`stream`	No	Whether to return an SSE-style stream
`max_tokens / temperature / top_p`	No	Compatible parameters passed through to the upstream model

Chat Completions

curl -sS "https://api.tokenstar.io/v1/chat/completions" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.7-plus",
    "messages": [
      {"role": "user", "content": "Reply only OK"}
    ]
  }'

Response example

Notes

Use this API for clients that support OpenAI Chat Completions.
Only verified built-in models should be used in runnable examples.

POST/v1/responsesOpenAI ResponsesSync

Responses API

Call the OpenAI Responses-compatible API, suitable for Codex custom providers.

Authentication

Authorization: Bearer <API_KEY>
Content-Type: application/json

Request parameters

Field	Required	Description
`model`	Yes	Built-in model ID
`input`	Yes	Text input or Responses-compatible input array
`stream`	No	Whether to stream the response

Responses API

curl -sS "https://api.tokenstar.io/v1/responses" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "input": "Reply only OK"
  }'

Notes

OpenAI-compatible clients should use a Base URL ending in /v1.
Codex custom providers can use wire_api = "responses".

POST/v1/messagesAnthropic MessagesSync

Claude Messages

Call Claude models through the Anthropic Messages protocol.

Authentication

x-api-key: <API_KEY>
anthropic-version: 2023-06-01

Request parameters

Field	Required	Description
`model`	Yes	Claude-compatible model ID
`messages`	Yes	Anthropic-compatible messages
`max_tokens`	Yes	Maximum output tokens

Messages request shape

Notes

The Claude Code Base URL uses the gateway root and must not include /v1.
This module remains preview unless the backend contract is verified.

Available models

See Model Plaza for the full model list, context windows, and input capabilities. Model Plaza

Image Generation APIs

Image APIs usually return synchronously. Read image data from the response field for each model family.

gpt-image

POST /v1/images/generations · POST /v1/images/edits

Response location: data[].b64_json

Applicable model: gpt-image-2.
Image generation uses JSON requests. Image edits and masked inpainting use multipart/form-data to upload image and optionally mask.
Common sizes include 1024x1024 and 2048x2048. Pass output formats within the model-supported range.

Image generation

Image edit

Masked inpainting

Gemini-compatible image models

POST /v1beta/models/{model}:generateContent

Response location: candidates[].content.parts[].inlineData

Applicable models: gemini-3-pro-image-preview, gemini-3.1-flash-image-preview, and gemini-2.5-flash-image.
parts may contain both text and images. Iterate through parts to find inlineData.

Gemini-compatible image request example

Video Generation APIs

Integration details for async tasks, assets, and callbacks.

Seedance video generation

After creating a Seedance task, poll by task ID until it reaches a terminal state, or pass callback_url for status callbacks.

No-reference-person video generationPOST /v1/video/generations · GET /v1/video/generations/{task_id}

Result: result_url

The no-reference-person entry uses seedance-2.0 or seedance-2.0-fast.
After task creation, store the returned id or task_id and poll the query API for results.

Create a no-reference-person task

Query video task

Asset groups, asset upload, and reference-person video generation

POST /volc/asset/CreateAssetGroup · POST /volc/asset/ListAssetGroups · POST /volc/asset/CreateAsset · POST /volc/asset/GetAsset · POST /v1/video/generations

Result: asset://<Id> · result_url

The reference-person entry uses seedance-2.0-asset or seedance-2.0-asset-fast.
Assets support images, videos, and audio. CreateAsset accepts only a publicly accessible URL, not embedded encodings or form file uploads.
CreateAsset uses AssetType, GroupId, Name, and URL.
Save the returned Id after creating an asset and validate it with GetAsset by Id. Do not depend on name-based asset lookup.
Video generation requests reference assets in content with asset://<Id>.
When generating video from assets, content must strictly follow the order text, image_url, video_url, audio_url. Do not reorder them, or the request may fail.

Create asset group

List asset groups

Upload asset by URL

Get asset by ID

Create video task from assets

Query reference-person video task

Kling video generation

The current Kling video API uses separate paths for text-to-video, image-to-video, Omni video edit, and motion control.

Text-to-videoPOST /v1/videos/text2video · GET /v1/videos/text2video/{task_id}

Result: data.task_result.videos[].url

Applicable models: kling-v2-6 and kling-v3.
Create calls return data.task_id. Query tasks with GET /v1/videos/text2video/{task_id}.
Use model_name, prompt, duration, mode, aspect_ratio, and sound. Current smoke checks use mode=std.
For subject consistency, avoid text-to-video and use element_list with image2video, omni-video, or motion-control.
Store request_id for troubleshooting. Successful responses may also include videos[].duration and final_unit_deduction.

Kling text-to-video

Query Kling task

Image-to-video and subject consistencyPOST /v1/videos/image2video · GET /v1/videos/image2video/{task_id}

Result: data.task_result.videos[].url

Applicable models: kling-v2-6 and kling-v3.
Use the top-level image field, not image_url and not legacy Image.Url.
image2video does not support aspect_ratio. Sending it returns UnknownParameter.
For subject consistency, pass element_list and use the subj_... returned by /v1/general/advanced-custom-elements as element_id.
Current video APIs must not use elem_... IDs returned by legacy /aigc/element; mixing them returns invalid_subject_id.
Image URLs must be public HTTPS addresses directly downloadable by the service.

Basic image-to-video

Image-to-video with subject element

Query image-to-video task

Omni video editPOST /v1/videos/omni-video · GET /v1/videos/omni-video/{task_id}

Result: data.task_result.videos[].url

Applicable model: kling-v3-omni.
Video edit uses video_list, and video_list[].video_url must be downloadable.
For subject consistency, pass element_list and use a subj_... element_id returned by the current subject API.
Current smoke checks cover kling-v3-omni + std + element_list.
Omni jobs usually take longer; do not recreate them merely because processing lasts longer.

Omni video edit

Omni video edit with subject

Query Omni task

Motion controlPOST /v1/videos/motion-control · GET /v1/videos/motion-control/{task_id}

Result: data.task_result.videos[].url

Basic motion control supports kling-v2-6 and kling-v3. Subject-consistency motion control supports kling-v3.
Pass both image_url and video_url. video_url is the motion reference video, and image_url is the subject image.
prompt and character_orientation are required. Use character_orientation=video for kling-v3 + element_list.
Do not pass duration or StaticMask; they may return UnknownParameter or fail the task.
kling-v2-6 + element_list is not supported and returns subject reference is not supported for model 'kling-v2-6'.

Motion control

Motion control with subject

Query motion-control task

Subject managementPOST /v1/general/advanced-custom-elements · GET /v1/general/advanced-custom-elements/{task_id}

Result: data.task_result.elements[].element_id

Subject creation is asynchronous. Save data.task_id and poll the single-task endpoint through submitted / processing / succeed / failed.
Use task_id to query the creation task. Use the returned element_id only in video element_list; never interchange the two IDs.
element_name and element_description are required and limited to 20 and 100 characters. reference_type is image_refer or video_refer.
Image-referenced subjects require one frontal image and 1-3 additional images. The current Console accepts accessible URLs only, subject to the official format, size, dimension, and aspect-ratio limits.
Video-referenced subjects use element_video_list with one MP4/MOV video, 3-8 seconds, 1080P, 16:9 or 9:16, up to 200 MB.
Use subj_... in video jobs only when data.task_status=succeed, the element status is succeed, and element_id is non-empty.
Cache subj_... by environment, subject media, and API version; do not recreate immediately after a transient query failure.
The elem_... returned by legacy /aigc/element is only for legacy /v1/video/generations.
Subject queries must check data.task_status, elements[].status, and a non-empty elements[].element_id together.

Create subject element

Query subject element

Legacy Kling API entryGET /doc/kling-legacy

Result: Legacy /v1/video/generations and X-TC-Action docs

The legacy page is only for existing integrations, migration, and historical troubleshooting.
New integrations should use the current /v1/videos/{endpoint} API in this module.

Open legacy Kling API

Task status, polling, and callbacks

Video jobs are asynchronous. Use callback_url only when the specific API documents support; otherwise poll the matching query endpoint.

Async task lifecyclesubmitted / queued / NOT_START → running / IN_PROGRESS → succeeded / SUCCESS / DONE / failed / FAILURE / FAIL

Result: Seedance: result_url; current Kling API: data.task_result.videos[].url

Poll every 5 to 10 seconds generally; for the current Kling API, query every 10 to 30 seconds and stop after a terminal state.
Handle current Kling states as submitted / processing / succeed / failed, and read video URLs only after task_status=succeed.
Generated result URLs may expire; download or persist them promptly after success.
Store request_id and task_id for gateway and upstream troubleshooting.
Use callback_url only when that video API explicitly supports it. The current Kling API does not publicly provide or recommend relying on callback_url, watermark_info, or external_task_id.
Customer callbacks should return HTTP 2xx and be idempotent by task ID.

submitted→processing→succeed / failed

After creating a task, store id, task_id, or Kling Response.JobId and poll the query API. Customer callbacks should be idempotent by task ID.

Third-party Agent Tool Configs

Different agent tools use different protocols and Base URL rules.

Claude Code

Claude Code environment variables

export ANTHROPIC_API_KEY="${API_KEY}"
export ANTHROPIC_BASE_URL="https://api.tokenstar.io"
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
export ANTHROPIC_MODEL="claude-sonnet-4-6-thinking"
claude

Do not set ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN at the same time.

Codex

~/.codex/config.toml

model = "gpt-5.4"
model_provider = "tokenstar"

[model_providers.tokenstar]
name = "TokenStar Gateway"
base_url = "https://api.tokenstar.io/v1"
wire_api = "responses"
env_key = "TOKENSTAR_API_KEY"

Start Codex

OpenClaw

~/.openclaw/openclaw.json

{
  env: { TOKENSTAR_API_KEY: "${API_KEY}" },
  models: {
    mode: "merge",
    providers: {
      tokenstar: {
        baseUrl: "https://api.tokenstar.io/v1",
        apiKey: "${TOKENSTAR_API_KEY}",
        api: "openai-completions",
        authHeader: true,
        models: [{
          id: "qwen3.7-plus",
          name: "Qwen 3.7 Plus",
          reasoning: true,
          input: ["text", "image"],
          contextWindow: 200000,
          maxTokens: 32768
        }]
      }
    }
  }
}

Anthropic providers use the gateway root as the Base URL.

Hand the docs to an AI agent

Download the same-source SKILL.md so agents can read TokenStar API rules, Base URLs, models, media tasks, and troubleshooting without asking users to scan the docs.