STEP 01
Create an account
Register at the TokenRoc console and sign in.
API documentation / Quickstart
TokenRoc exposes an OpenAI-compatible API. Keep the SDK and request format you already use, then replace the API key and base URL.
https://api.tokenroc.com/v101 / Setup
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 01
Register at the TokenRoc console and sign in.
STEP 02
Open API Keys, create an API key, and store it in a server-side secret.
STEP 03
Use the exact identifier shown in the Model Square.
Copy an exact model ID from Model Square, or list the models available to your API key:
curl https://api.tokenroc.com/v1/models \
-H "Authorization: Bearer $TOKENROC_API_KEY"02 / cURL
Set your API key as an environment variable and send the same JSON shape used by OpenAI-compatible clients.
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."}
]
}'03 / Python
Only the credentials and base URL are TokenRoc-specific. The client call remains OpenAI-compatible.
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
Run this on your server with Node.js 18 or later.
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
Support varies by model. Start with Model Square, then use the endpoint supported by that model.
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /v1/models | List models available to the current API key. |
| POST | /v1/chat/completions | Create a standard or streaming chat completion. |
| POST | /v1/responses | Use the Responses-compatible request format where supported. |
| POST | /v1/images/generations | Generate images with an image model. See the image generation guide. |
| POST | /v1/videos | Submit 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}/content | Download a completed Seedance video with your API key. |
05 / Guides
Image and video models use their own routes, request fields, and billing units. Each guide goes from an API key to a finished file.
| HTTP status | Error code or message | Meaning | Retry or not | What to do |
|---|---|---|---|---|
| 400 | invalid_request or missing_model | A 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. |
| 401 | Invalid or missing API key | Authentication failed. | Do not retry. | Send Authorization: Bearer with an active API key. Check the API Keys page and remove extra spaces. |
| 403 | insufficient_user_quota | Your balance cannot cover the request or video reservation. | Do not retry until fixed. | Add credit on the Wallet page, or reduce the request cost. |
| 403 | pre_consume_token_quota_failed or access_denied | The 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. |
| 429 | Rate limit message | Too many requests or a temporary capacity limit. | Retry with backoff. | Reduce concurrency. Wait 2, 4, then 8 seconds between attempts. |
| 503 | model_not_found | The 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 5xx | Temporary server error | A 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. |
| 400 | task_not_exist | No 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 5xx | invalid_request or convert_request_failed with a parameter error | The request cannot be converted for this model. | Do not retry unchanged. | Fix the field named in the message, even if the status is 5xx. |
| 200 | error.type: ali_error | Image 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. |
| 5xx | bad_response with aliAsyncTaskWait timeout | Image 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. |
| Varies | ali_api_error or fail_to_fetch_task | Video 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