API documentation / Quickstart

One API key. One endpoint. Your existing code.

TokenRoc exposes an OpenAI-compatible API. Keep the SDK and request format you already use, then replace the API key and base URL.

Base URLhttps://api.tokenroc.com/v1

01 / Setup

Send your first request

Create an account, generate an API key, and choose a model in Model Square. Never expose an API key in browser or mobile client code.

STEP 02

Generate an API key

Open API Keys, create an API key, and store it in a server-side secret.

STEP 03

Find a model ID

Use the exact identifier shown in the Model Square.

Find a model ID

Copy an exact model ID from Model Square, or list the models available to your API key:

curl / available models
curl https://api.tokenroc.com/v1/models \
  -H "Authorization: Bearer $TOKENROC_API_KEY"

02 / cURL

Chat completions request

Set your API key as an environment variable and send the same JSON shape used by OpenAI-compatible clients.

curl / POST /v1/chat/completions
curl https://api.tokenroc.com/v1/chat/completions \
  -H "Authorization: Bearer $TOKENROC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      {"role": "user", "content": "Say hello in one sentence."}
    ]
  }'
Model availability changes over time. Copy the model identifier from Model Square instead of hard-coding a display name.

03 / Python

The same request in Python

Only the credentials and base URL are TokenRoc-specific. The client call remains OpenAI-compatible.

Python / app.py
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TOKENROC_API_KEY"],
    base_url="https://api.tokenroc.com/v1",
)

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
)

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

JavaScript / fetch

The same request in JavaScript

Run this on your server with Node.js 18 or later.

JavaScript (fetch)
const response = await fetch("https://api.tokenroc.com/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.TOKENROC_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "deepseek-v4-flash",
    messages: [{ role: "user", content: "Say hello in one sentence." }],
  }),
});
if (!response.ok) throw new Error("HTTP " + response.status);
const result = await response.json();
console.log(result.choices[0].message.content);

04 / Reference

Core endpoints

Support varies by model. Start with Model Square, then use the endpoint supported by that model.

MethodEndpointPurpose
GET/v1/modelsList models available to the current API key.
POST/v1/chat/completionsCreate a standard or streaming chat completion.
POST/v1/responsesUse the Responses-compatible request format where supported.
POST/v1/images/generationsGenerate images with an image model. See the image generation guide.
POST/v1/videosSubmit a video generation task. See the video generation guide.
GET/v1/videos/{id}Check a video task and get its status.
GET/v1/videos/{id}/contentDownload a completed Seedance video with your API key.

05 / Guides

Images and video

Image and video models use their own routes, request fields, and billing units. Each guide goes from an API key to a finished file.

Generate an image

One request to a Kling image model returns the image link in the same response. Billed per image.

IMAGE GUIDE ->

Generate a video

Submit a task, check it until it completes, then download the file. Compare per-video, per-second, and video-token billing.

VIDEO GUIDE ->

Common HTTP responses

HTTP statusError code or messageMeaningRetry or notWhat to do
400invalid_request or missing_modelA required field is missing or outside its limit.Do not retry.Fix the named field. Check the selected model's parameter limits in Model Square. For Kling v3 image models only (kling/kling-v3-image-generation and kling/kling-v3-omni-image-generation), n must be 1 to 9. For wan3.0-video and wan3.0-video-prime only, duration is 2 to 30 whole seconds or -1. Wan duration=-1 lets the model choose the length; TokenRoc reserves 30 seconds and settles to the length actually generated. See the image and video guides for each model's other limits.
401Invalid or missing API keyAuthentication failed.Do not retry.Send Authorization: Bearer with an active API key. Check the API Keys page and remove extra spaces.
403insufficient_user_quotaYour balance cannot cover the request or video reservation.Do not retry until fixed.Add credit on the Wallet page, or reduce the request cost.
403pre_consume_token_quota_failed or access_deniedThe API key limit, model permissions, or IP rules reject the request.Do not retry until fixed.Check the API key spending limit, allowed models and IP rules.
429Rate limit messageToo many requests or a temporary capacity limit.Retry with backoff.Reduce concurrency. Wait 2, 4, then 8 seconds between attempts.
503model_not_foundThe model ID is wrong or unavailable to your API key.Do not retry.Check the exact model ID in Model Square and the API key model permissions.
Other 5xxTemporary server errorA temporary gateway or model service failure.Retry with backoff, max 3 times.Wait 2, 4, then 8 seconds. For video submission, check Task Logs before resubmitting so you do not create a second task.
400task_not_existNo task with this ID belongs to your account.Do not retry.Check the saved task ID and use an API key from the account that created it.
400 or 5xxinvalid_request or convert_request_failed with a parameter errorThe request cannot be converted for this model.Do not retry unchanged.Fix the field named in the message, even if the status is 5xx.
200error.type: ali_errorImage generation failed despite an HTTP 200 response.Do not retry unchanged.Check error.code and error.message before reading data. Change the prompt or inputs if the message requires it.
5xxbad_response with aliAsyncTaskWait timeoutImage generation did not finish within the wait period.Retry later with backoff, max 3 times.Check Usage Logs before retrying. Contact support if it keeps failing.
Variesali_api_error or fail_to_fetch_taskVideo submission or task lookup failed.Follow the status and message.Fix parameter or content errors. For 429 or other temporary 5xx errors, use backoff. Keep the same task ID when checking an existing task.

Read the Errors page for retry rules and what to send support.

07 / Next

Continue in the console

Model pricing

Compare the current input and output rates before choosing a model.

OPEN PRICING ->

API keys

Create separate API keys for each environment and revoke them independently.

MANAGE KEYS ->

Service status

Confirm that the status page loaded and check whether the API gateway responds.

VIEW STATUS ->

See also