Model Discovery

Use the Models page or the Models API to inspect available text models. Model metadata includes vendor, serving provider, modality, context length, supported API families, supported capabilities, availability, account-level limits, and credit pricing.

Endpoint: GET /v1/models Purpose: List models available to the current account.

curl --request GET \
  --url https://api.basicrouter.ai/api/v1/models \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

Capability matrix

API family compatibility matrix

Authentication

Every API request uses a bearer token. Store keys in server-side environment variables, rotate them when team access changes, and log request IDs for debugging.

Key security recommendations

1. Keep API keys on the server. Do not expose keys in browser or mobile client code.
2. Use separate keys for development, staging, production, and third-party integrations.
3. Scope keys by environment, service, customer, or tenant when available.
4. Rotate keys after employee departures, vendor access changes, or suspected leakage.
5. Store keys in secret managers or environment variables, not source code.

Coding Agents

BasicRouter works with coding agents and AI development tools that support OpenAI-compatible or Anthropic-compatible API endpoints. Use routing aliases such as mwf/coding-auto so BasicRouter can route to the best available coding model without requiring developers to change tool configuration.

Generic OpenAI-compatible setup

Use this setup for Cursor, Codex, Hermes, OpenClaw, Continue, Aider, Cline, LangChain-based agents, LlamaIndex-based agents, and custom OpenAI-compatible agent runtimes.

export OPENAI_BASE_URL="https://api.basicrouter.ai/api/v1"
export OPENAI_API_KEY="$BASICROUTER_API_KEY"
export OPENAI_MODEL="mwf/coding-auto"

Generic Anthropic-compatible setup

Use this setup for Claude-compatible clients and tools that expect Anthropic Messages format.

export ANTHROPIC_BASE_URL="https://api.basicrouter.ai/api/anthropic"
export ANTHROPIC_API_KEY="$BASICROUTER_API_KEY"
export ANTHROPIC_MODEL="mwf/coding-auto"

Recommended agent models

Cursor quick guide

Use the OpenAI-compatible endpoint.

Base URL: https://api.basicrouter.ai/api/v1
API Key:  BASICROUTER_API_KEY
Model:    mwf/coding-auto

Recommended steps:

1. Open Cursor settings.
2. Add or enable OpenAI-compatible API key configuration.
3. Set the OpenAI base URL override to https://api.basicrouter.ai/api/v1.
4. Add a custom model such as mwf/coding-auto, mwf/coding-fast, or mwf/coding-long.
5. Use a model that supports streaming and tool calling for best agent behavior.

Troubleshooting:

Claude Code quick guide

Use the Anthropic-compatible gateway endpoint.

export ANTHROPIC_BASE_URL="https://api.basicrouter.ai/api/anthropic"
export ANTHROPIC_API_KEY="$BASICROUTER_API_KEY"
export ANTHROPIC_MODEL="mwf/coding-auto"

BasicRouter supports this Anthropic-compatible path for Claude Code and Anthropic SDK compatibility:

POST /api/v1/messages

Recommended requirements:

Codex quick guide

Use BasicRouter as a custom OpenAI-compatible model provider.

Example provider configuration:

[model_providers.basicrouter]
name = "BasicRouter"
base_url = "https://api.basicrouter.ai/api/v1"
env_key = "BASICROUTER_API_KEY"
wire_api = "responses"

model_provider = "basicrouter"
model = "mwf/coding-auto"

Environment variable:

export BASICROUTER_API_KEY="br_xxx"

Recommended models:

Troubleshooting:

Hermes quick guide

Use the OpenAI-compatible endpoint unless your Hermes deployment is configured for another protocol.

export OPENAI_BASE_URL="https://api.basicrouter.ai/api/v1"
export OPENAI_API_KEY="$BASICROUTER_API_KEY"
export OPENAI_MODEL="mwf/coding-auto"

Recommended model policy:

OpenClaw quick guide

Use the OpenAI-compatible endpoint for OpenAI-style agent runtime configuration.

export OPENAI_BASE_URL="https://api.basicrouter.ai/api/v1"
export OPENAI_API_KEY="$BASICROUTER_API_KEY"
export OPENAI_MODEL="mwf/coding-auto"

If OpenClaw supports multiple providers, configure BasicRouter as an OpenAI-compatible provider and use BasicRouter routing aliases for model selection.

{
  "provider": "openai-compatible",
  "base_url": "https://api.basicrouter.ai/api/v1",
  "api_key_env": "BASICROUTER_API_KEY",
  "model": "mwf/coding-auto"
}

Agent compatibility checklist

Using the Console

The BasicRouter Console is the operational control plane for API access, model availability, routing policies, usage visibility, and billing administration. It gives account administrators a centralized view of keys, models, requests, credits, and account-level controls for production model traffic.

Managing API keys

Create, rotate, revoke, and label API keys from the console. Use separate keys for development, staging, production, and individual services so usage can be audited and isolated by environment or application.

Model list

Use the Models page to review models available to the account. Each model entry may include vendor, serving provider, modality, supported API families, context length, capability flags, availability status, and pricing information.

For production applications, verify model capabilities before enabling traffic. Some parameters and features are model-dependent and may not be supported across all API families.

Usage & logs

The Usage & Logs view provides operational visibility into API traffic. Teams can inspect request volume, selected models, resolved routing targets, credit consumption, latency, error codes, and request IDs.

• Troubleshoot failed requests.
• Identify high-cost workloads.
• Compare model usage across applications and environments.
• Validate routing and fallback behavior.
• Investigate latency or provider availability issues.
• Provide request IDs when contacting support.

Each API response includes or exposes a BasicRouter request ID. Store this ID in your application logs to make production debugging and support escalation more efficient.

Fallback

Fallback is BasicRouter's resilience mechanism. When the primary model or routing policy fails, the system automatically switches to a backup model to keep processing the request. This keeps your application responsive and minimizes the risk of service disruption.

Why fallback matters

In production, model services can run into a number of unpredictable issues:

• Model service failure: the upstream API becomes temporarily unavailable or times out.
• Performance fluctuation: high model load leads to slow or failed responses.
• Routing failure: all candidate models selected by smart routing become unavailable.

Fallback keeps your application available by providing a reliable backup path.

Core advantages

Global fallback model configuration

BasicRouter supports setting a global fallback model from the console backend. All requests automatically use this model as a backup when they fail.

How to configure it:

1. Go to the BasicRouter strategy settings page.
2. Find the Default Fallback Model setting.
3. Select your global fallback model from the dropdown list.
4. Save the setting to apply it immediately.

Advantages of global configuration:

• No code changes required: configure once and it applies globally, with no need to repeat the setting on every request.
• Centralized management: manage the fallback policy in one place for easier adjustment and monitoring.
• Simplified maintenance: reduces code complexity and the chance of configuration errors.
• Flexible override: request-level fallback configuration takes priority and can override the global setting for specific scenarios.

Request-level fallback configuration

For specific business scenarios, you can specify a fallback model on an individual request to override the global configuration.

Specify the fallback model with the router.fallBackModels parameter:

{
  "model": "claude-sonnet-4",
  "messages": [
    {
      "role": "user",
      "content": "Explain what quantum computing is"
    }
  ],
  "router": {
    "fallBackModels": ["glm-5.2"]
  }
}

Priority rules

When multiple fallback configurations are present, priority runs from highest to lowest:

1. Request-level router.fallBackModels: the fallback model specified on an individual request.
2. Global Default Fallback Model: the global fallback model configured in the console.
3. No fallback: if neither is configured, the request returns an error on failure.

Account administration

Depending on account type, the console may include account-level model enablement, reseller or distributor controls, billing configuration, and access settings. Administrators can use these controls to align model access, usage visibility, and billing responsibility with applications, customer accounts, or business units.

Production operations checklist

Billing & Credits

BasicRouter uses a credit-based billing model across text, image, video, and other supported model workloads. Credits provide a unified unit for multi-model and multi-provider usage so teams can manage consumption consistently across modalities and API families.

Detailed model pricing is available on the Models page or through model metadata APIs. Pricing may vary by model, provider, modality, resolution, token type, output length, task duration, account type, and commercial agreement.

Top up & wallet

Accounts may add pay-as-you-go wallet credits for flexible usage. Wallet credits are used after monthly plan credits and resource packs have been consumed, unless a custom billing rule applies to the account.

Wallet credits do not expire unless otherwise specified in applicable commercial terms. Service fee is charged when recharging the pay-as-you-go wallet.

Monthly plans and resource packs

Each user or account can select one active monthly plan. Monthly plans provide a defined amount of usage capacity, commercial terms, and account-level access configuration for the billing period.

Users can also buy multiple resource packs for additional usage capacity. Resource packs can separate committed usage from pay-as-you-go wallet balance and are useful for high-volume text, image, video, or dedicated workload usage.

Deduction order

Unless custom billing rules are configured, credits are deducted in the following order:

For accounts with custom commercial terms, deduction order, expiration rules, included usage, and pricing may differ. Account-specific rules are shown in the console or provided through the commercial agreement.

Custom pricing

Pricing can be customized for each user or account. Enterprise customers, reseller accounts, distributor accounts, and high-volume customers may be eligible for custom pricing. Contact sales for a quote.

Custom pricing can be configured by account, model, provider, modality, region, usage volume, or commercial agreement. When custom pricing is enabled, the console and billing APIs reflect account-specific pricing and deduction rules where available.

Pricing units

Different model modalities use different measurement units. BasicRouter converts these units into credits according to the model’s pricing rules.

Pricing units may vary by model. Always refer to the model detail page or pricing metadata before enabling a model in production.

Usage attribution

BasicRouter usage can be reviewed by account, API key, model, modality, or time range. This allows teams to attribute cost to applications, environments, customers, or internal business units.

Credit balance

Check how many credits are available across your account. The balance is split into three wallets that are deducted in order: the monthly plan allowance, purchased resource packs, and the pay-as-you-go wallet. A combined resource total (monthly plan + resource packs, excluding pay-as-you-go) is also available for tracking included usage separately from top-up spending.

To retrieve this programmatically, see GET /v1/billing/balance in the API Reference.

Usage details

Review a paginated, chronological list of individual usage records for reporting, monitoring, and internal cost allocation. Each record shows the model, model type (text, image, or video), the credits deducted, and a breakdown of which wallet each deduction was drawn from. Results can be filtered to a specific time range.

To retrieve this programmatically, see GET /v1/usage in the API Reference.

Transaction history

Use transaction history to review credit movements, including top-ups, plan allocations, resource pack grants, usage deductions, adjustments, and administrative corrections.

To retrieve this programmatically, see GET /v1/billing/transactions in the API Reference.

Failed requests and refunds

Validation errors, authentication errors, and permission errors are generally not billed because no model execution occurs. Requests that reach an upstream model or generate partial output may consume credits depending on the model, provider, and response state.

For async image and video tasks, billing behavior depends on whether the task was accepted, started, completed, failed, or cancelled. The task detail response includes usage information when credits have been consumed.

Top-ups, monthly plans, resource packs, and consumed credits are non-refundable unless otherwise specified in the applicable commercial agreement or required by law.

API Reference

Common conventions

Base URL

All endpoints are served under the /v1 prefix.

Authentication

Calls to /v1/* endpoints use API Key authentication (not JWT). The API Key is passed via the following header:

Missing or invalid keys return 401.

Balance pre-check

All model-calling endpoints run a balance pre-check before execution:

• Insufficient balance returns Insufficient credit, mapped to:
  • OpenAI protocol: HTTP 400, code = insufficient_quota
  • Anthropic protocol: HTTP 402, type = billing_error
• Some endpoints also estimate a minimum cost per model for a second pre-check.

POST https://api.basicrouter.ai/api/v1/chat/completions

OpenAI Chat Completions-compatible endpoint. Supports streaming and non-streaming, tool calls, JSON mode, and multimodal input.

Message fields:

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/chat/completions \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "glm-5.2",
    "messages": [{"role": "user", "content": "Describe Hangzhou in one sentence."}],
    "stream": false,
    "temperature": 0.7
  }'

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1721380000,
  "model": "glm-5.2",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "Hangzhou is ..."},
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 12, "completion_tokens": 18, "total_tokens": 30}
}

Response fields (non-streaming):

Streaming response example:

data: {"object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant","content":"..."}}]}

data: {"object":"chat.completion.chunk","choices":[{"delta":{"content":"..."}}]}

data: [DONE]

POST https://api.basicrouter.ai/api/v1/responses

OpenAI Responses-compatible endpoint. Uses input instead of messages, instructions instead of a system message, and a text block instead of response_format.

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/responses \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "glm-5.2",
    "input": "Describe Hangzhou in one sentence.",
    "instructions": "Be concise.",
    "stream": false
  }'

{
  "id": "resp_xxx",
  "object": "response",
  "model": "glm-5.2",
  "status": "completed",
  "created_at": 1721380000,
  "output": [
    {
      "id": "msg_xxx",
      "type": "message",
      "role": "assistant",
      "content": [{"type": "output_text", "text": "Hangzhou is ..."}],
      "status": "completed"
    }
  ],
  "usage": {"input_tokens": 12, "output_tokens": 18, "total_tokens": 30}
}

Response fields (non-streaming):

Streaming follows the Responses API events:

POST https://api.basicrouter.ai/api/v1/messages

Anthropic Messages-compatible endpoint. Accepts x-api-key and anthropic-version: 2023-06-01 headers. Content blocks support text, image, tool_use, tool_result, thinking, and redacted_thinking.

Image block examples:

{ "type": "image", "source": { "type": "base64", "media_type": "...", "data": "..." } }
{ "type": "image", "source": { "type": "url", "url": "..." } }

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/messages \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "claude-sonnet-4.6",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Describe Hangzhou in one sentence."}]
  }'

{
  "id": "msg_xxx",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-4.6",
  "content": [{"type": "text", "text": "Hangzhou is ..."}],
  "stop_reason": "end_turn",
  "usage": {"input_tokens": 12, "output_tokens": 18}
}

Response fields (non-streaming):

GET https://api.basicrouter.ai/api/v1/models

Returns all online, enabled API models.

curl --request GET \
  --url https://api.basicrouter.ai/api/v1/models \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "glm-5.2",
      "object": "model",
      "display_name": "glm-5.2",
      "created": 1721380000,
      "owned_by": "Zai",
      "input_modalities": ["text", "image"],
      "output_modalities": ["text"],
      "context_length": 128000
    }
  ]
}

Each model entry (data[]) fields:

GET https://api.basicrouter.ai/api/v1/models/{model}

Returns a single model with the same shape as a list entry. Returns HTTP 404 when the model does not exist.

curl --request GET \
  --url https://api.basicrouter.ai/api/v1/models/gpt-5.5 \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

Success response: a single model object with the same fields as a /v1/models list entry.

When the model does not exist, returns HTTP 404:

{"error": {"message": "The model 'xxx' does not exist", "type": "invalid_request_error", "code": "invalid_model_error"}}

GET https://api.basicrouter.ai/api/v1/image-models

Query the resolutions, ratios, and maximum counts supported by an image model before calling /v1/image-generations. No authentication required.

curl --request GET \
  --url https://api.basicrouter.ai/api/v1/image-models \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "gpt-image-2",
      "object": "image_model",
      "displayName": "GPT Image 1",
      "description": "...",
      "icon": "...",
      "created": 1721380000,
      "maxCount": 4,
      "fileMax": 10,
      "resolutions": ["720p", "1080p"],
      "ratios": ["1:1", "3:2"]
    }
  ]
}

GET https://api.basicrouter.ai/api/v1/video-models

Query the supported videoType values, duration range, resolutions, and ratios for a video model before calling /v1/video-generations. No authentication required.

VideoTypeOption fields:

curl --request GET \
  --url https://api.basicrouter.ai/api/v1/video-models \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "sora-2",
      "object": "video_model",
      "displayName": "Sora 2",
      "description": "...",
      "icon": "...",
      "created": 1721380000,
      "allowedVideoTypes": [
        {"code": 1, "name": "text-to-video"},
        {"code": 2, "name": "image-to-video"},
        {"code": 3, "name": "image-to-video (first/last frame)"}
      ],
      "videoDurationMin": 5,
      "videoDurationMax": 10,
      "videoDurationSuggest": [5, 8, 10],
      "resolutions": ["1080p", "720p"],
      "ratios": ["16:9", "9:16"],
      "fileMax": 5
    }
  ]
}

POST https://api.basicrouter.ai/api/v1/image-generations

Asynchronously submit an image generation task. Returns a taskId immediately; retrieve the result by polling GET /v1/image-generations/{taskId} or via a callbackUrl webhook.

The model, supported resolution / ratio values, count upper limit, and reference-image upload limit (fileMax) must be obtained from GET /v1/image-models first. Only values advertised by that model's spec are accepted.

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/image-generations \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "seedream-4.5",
    "text": "A cat drinking water by the river",
    "count": 1,
    "resolution": "2k",
    "ratio": "1:1",
    "imageUrls": []
  }'

{
  "code": 200,
  "message": "image task is commit",
  "data": {"taskId": "img_xxx"}
}

Error responses:

// Insufficient credit
{ "code": 500, "message": "Insufficient credit" }

// Model not found
{ "code": 404, "message": "Model not found: xxx" }

GET https://api.basicrouter.ai/api/v1/image-generations/{taskId}

Poll an image generation task. status is pending / success / failed. images is a JSON-stringified array of image URLs; text carries any model-attached text description (e.g. Gemini multimodal output), null otherwise.

curl --request GET \
  --url https://api.basicrouter.ai/api/v1/image-generations/img_xxx \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "img_xxx",
    "status": "success",
    "errorMessage": null,
    "images": "[\"https://.../1.png\"]",
    "text": null
  }
}

Response data fields:

Task not found:

{ "code": 500, "message": "task not found" }

If callbackUrl was supplied on submit, the server pushes the final success / failed result via webhook with the same data shape.

Complete example (submit + poll)

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class ImageGenerationExample {
  private static final String BASE = "https://api.basicrouter.ai/api/v1";
  private static final String API_KEY = System.getenv("BASICROUTER_API_KEY");

  public static void main(String[] args) throws Exception {
    HttpClient http = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(10)).build();

    // 1. Submit the task.
    String body = "{"
        + "\"model\":\"seedream-4.5\","
        + "\"text\":\"A cat drinking water by the river\","
        + "\"count\":1,"
        + "\"resolution\":\"2k\","
        + "\"ratio\":\"1:1\","
        + "\"imageUrls\":[]"
        + "}";
    HttpResponse<String> submit = http.send(
        HttpRequest.newBuilder(URI.create(BASE + "/image-generations"))
            .header("Authorization", "Bearer " + API_KEY)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body)).build(),
        HttpResponse.BodyHandlers.ofString());

    String taskId = extract(submit.body(), "taskId");
    System.out.println("taskId = " + taskId);

    // 2. Poll until terminal status.
    String status = "pending";
    while ("pending".equals(status)) {
      Thread.sleep(15_000L);
      HttpResponse<String> poll = http.send(
          HttpRequest.newBuilder(URI.create(BASE + "/image-generations/" + taskId))
              .header("Authorization", "Bearer " + API_KEY).GET().build(),
          HttpResponse.BodyHandlers.ofString());
      status = extract(poll.body(), "status");
      System.out.println("status = " + status);
    }

    if (!"success".equals(status)) {
      throw new RuntimeException("image generation failed: " + status);
    }
    // images is a JSON-stringified array of URLs.
    String images = extract(pollResult(http, taskId), "images");
    System.out.println("images = " + images);
  }

  // Minimal JSON field extractor — use Jackson/Gson in production.
  private static String extract(String json, String field) {
    int i = json.indexOf("\"" + field + "\":");
    if (i < 0) return null;
    i += field.length() + 3;
    if (json.charAt(i) == '\"') {
      int end = json.indexOf('\"', i + 1);
      return json.substring(i + 1, end);
    }
    int end = i;
    while (end < json.length() && "0123456789.".indexOf(json.charAt(end)) >= 0) end++;
    return json.substring(i, end);
  }

  private static String pollResult(HttpClient http, String taskId) throws Exception {
    return http.send(HttpRequest.newBuilder(URI.create(BASE + "/image-generations/" + taskId))
        .header("Authorization", "Bearer " + API_KEY).GET().build(),
        HttpResponse.BodyHandlers.ofString()).body();
  }
}

import os
import time
import requests

BASE = "https://api.basicrouter.ai/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['BASICROUTER_API_KEY']}"}

# 1. Submit the task.
resp = requests.post(
    f"{BASE}/image-generations",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={
        "model": "seedream-4.5",
        "text": "A cat drinking water by the river",
        "count": 1,
        "resolution": "2k",
        "ratio": "1:1",
        "imageUrls": [],
    },
)
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print(f"taskId = {task_id}")

# 2. Poll until terminal status.
while True:
    time.sleep(15)
    poll = requests.get(f"{BASE}/image-generations/{task_id}", headers=HEADERS)
    poll.raise_for_status()
    data = poll.json()["data"]
    status = data["status"]
    print(f"status = {status}")
    if status != "pending":
        break

if status != "success":
    raise RuntimeError(f"image generation failed: {data.get('errorMessage')}")

# images is a JSON-stringified array of URLs.
import json
images = json.loads(data["images"])
print(f"images = {images}")

POST https://api.basicrouter.ai/api/v1/video-generations

Asynchronously submit a video generation task. Returns a taskId immediately; retrieve the result by polling GET /v1/video-generations/{taskId} or via a callbackUrl webhook.

The model, allowed videoType values, duration range (videoDurationMin/Max), supported resolution / ratio, and reference-asset upload limit (fileMax) must be obtained from GET /v1/video-models first. Only videoType codes listed in that model's allowedVideoTypes are accepted.

Examples for each videoType:

1. Text to video (videoType=1)

Generate a video from a text prompt only; no reference assets needed.

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/video-generations \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "videoType": 1,
    "text": "A cat jumping on a bed",
    "resolution": "480p",
    "ratio": "16:9",
    "duration": 4,
    "model": "seedance-2.0"
  }'

2. Image to video - first frame (videoType=2)

Provide a single starting frame in imageUrls; the model generates a video starting from that frame.

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/video-generations \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "videoType": 2,
    "text": "Happily shaking head",
    "resolution": "480p",
    "ratio": "16:9",
    "duration": 4,
    "model": "seedance-2.0",
    "imageUrls": ["https://basicrouter-flie.oss-accelerate.aliyuncs.com/test/first-frame.png"]
  }'

3. Image to video - first and last frame (videoType=3)

Provide both the first and last frame in imageUrls (order: [first, last]); the model generates a transition video between the two frames.

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/video-generations \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "videoType": 3,
    "text": "Put on the hat",
    "resolution": "480p",
    "ratio": "16:9",
    "duration": 4,
    "model": "seedance-2.0",
    "imageUrls": [
      "https://basicrouter-flie.oss-accelerate.aliyuncs.com/test/first-frame.png",
      "https://basicrouter-flie.oss-accelerate.aliyuncs.com/test/last-frame.png"
    ]
  }'

4. Image to video - reference (videoType=4)

Provide one or more reference images in imageUrls; the model uses their style/content as reference (not as a forced first/last frame) to generate the video.

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/video-generations \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "videoType": 4,
    "text": "Two cats playing together",
    "resolution": "480p",
    "ratio": "16:9",
    "duration": 4,
    "model": "kling-v3-omni-video",
    "imageUrls": [
      "https://basicrouter-flie.oss-accelerate.aliyuncs.com/test/ref-1.png",
      "https://basicrouter-flie.oss-accelerate.aliyuncs.com/test/ref-2.png"
    ]
  }'

5. All reference (videoType=5)

Mixed image / video / audio references. Reference assets by position in the prompt: the 1st entry in imageUrls is @图片 1, the 1st in videoUrls is @视频 1, the 1st in audioUrls is @音频 1. videoUrls also accepts plain URL strings.

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/video-generations \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "videoType": 5,
    "text": "Use the first-person framing of @视频 1 and @音频 1 as background music. First-person tea ad; start frame is @图片 1 ... end frame is @图片 2.",
    "model": "seedance-2.0",
    "imageUrls": [
      "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic1.jpg",
      "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic2.jpg"
    ],
    "videoUrls": ["https://ark-project.tos-cn-beijing.volces.com/doc_video/r2v_tea_video1.mp4"],
    "audioUrls": ["https://ark-project.tos-cn-beijing.volces.com/doc_audio/r2v_tea_audio1.mp3"],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 11
  }'

Submit response (all five types):

{
  "code": 200,
  "message": "success",
  "data": {"taskId": "vid_xxx"}
}

GET https://api.basicrouter.ai/api/v1/video-generations/{taskId}

Poll a video generation task. status is pending / success / failed; videoUrl is the generated video URL and lastFrameUrl is the last-frame URL (image-to-video scenarios).

curl --request GET \
  --url https://api.basicrouter.ai/api/v1/video-generations/vid_xxx \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

{
  "code": 200,
  "message": "success",
  "data": {
    "status": "success",
    "videoUrl": "https://.../out.mp4",
    "lastFrameUrl": null,
    "message": null
  }
}

Response data fields:

If callbackUrl was supplied on submit, the server pushes the final result via webhook with the same data shape.

Complete example (submit + poll)

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class VideoGenerationExample {
  private static final String BASE = "https://api.basicrouter.ai/api/v1";
  private static final String API_KEY = System.getenv("BASICROUTER_API_KEY");

  public static void main(String[] args) throws Exception {
    HttpClient http = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(10)).build();

    // 1. Submit the task (videoType=1: text-to-video).
    String body = "{"
        + "\"videoType\":1,"
        + "\"text\":\"A cat jumping on a bed\","
        + "\"resolution\":\"480p\","
        + "\"ratio\":\"16:9\","
        + "\"duration\":4,"
        + "\"model\":\"seedance-2.0\""
        + "}";
    HttpResponse<String> submit = http.send(
        HttpRequest.newBuilder(URI.create(BASE + "/video-generations"))
            .header("Authorization", "Bearer " + API_KEY)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body)).build(),
        HttpResponse.BodyHandlers.ofString());

    String taskId = extract(submit.body(), "taskId");
    System.out.println("taskId = " + taskId);

    // 2. Poll until terminal status. Video tasks take longer — poll every 20s.
    String status = "pending";
    String lastBody = null;
    while ("pending".equals(status)) {
      Thread.sleep(20_000L);
      HttpResponse<String> poll = http.send(
          HttpRequest.newBuilder(URI.create(BASE + "/video-generations/" + taskId))
              .header("Authorization", "Bearer " + API_KEY).GET().build(),
          HttpResponse.BodyHandlers.ofString());
      lastBody = poll.body();
      status = extract(lastBody, "status");
      System.out.println("status = " + status);
    }

    if (!"success".equals(status)) {
      throw new RuntimeException("video generation failed: " + status);
    }
    String videoUrl = extract(lastBody, "videoUrl");
    System.out.println("videoUrl = " + videoUrl);
  }

  // Minimal JSON field extractor — use Jackson/Gson in production.
  private static String extract(String json, String field) {
    int i = json.indexOf("\"" + field + "\":");
    if (i < 0) return null;
    i += field.length() + 3;
    if (json.charAt(i) == '\"') {
      int end = json.indexOf('\"', i + 1);
      return json.substring(i + 1, end);
    }
    int end = i;
    while (end < json.length() && "0123456789.".indexOf(json.charAt(end)) >= 0) end++;
    return json.substring(i, end);
  }
}

import os
import time
import requests

BASE = "https://api.basicrouter.ai/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['BASICROUTER_API_KEY']}"}

# 1. Submit the task (videoType=1: text-to-video).
resp = requests.post(
    f"{BASE}/video-generations",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={
        "videoType": 1,
        "text": "A cat jumping on a bed",
        "resolution": "480p",
        "ratio": "16:9",
        "duration": 4,
        "model": "seedance-2.0",
    },
)
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print(f"taskId = {task_id}")

# 2. Poll until terminal status. Video tasks take longer — poll every 20s.
while True:
    time.sleep(20)
    poll = requests.get(f"{BASE}/video-generations/{task_id}", headers=HEADERS)
    poll.raise_for_status()
    data = poll.json()["data"]
    status = data["status"]
    print(f"status = {status}")
    if status != "pending":
        break

if status != "success":
    raise RuntimeError(f"video generation failed: {data.get('message')}")

print(f"videoUrl = {data['videoUrl']}")
if data.get("lastFrameUrl"):
    print(f"lastFrameUrl = {data['lastFrameUrl']}")

GET https://api.basicrouter.ai/api/v1/billing/balance

Returns the account balance split into three wallets: monthly plan, resource packs, and pay-as-you-go credit.

curl --request GET \
  --url https://api.basicrouter.ai/api/v1/billing/balance \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

{
  "totalCredit": 128.50,
  "totalResourceCredit": 30.00,
  "wallets": {
    "monthlyPlan": {"id": "pkg_xxx", "credit": 50.00, "name": "Monthly plan"},
    "resourcePacks": [
      {"id": "rp_xxx", "credit": 30.00, "name": "Video resource pack"}
    ],
    "payAsYouGo": 48.50
  }
}

Response fields:

WalletDetailVO fields::

GET https://api.basicrouter.ai/api/v1/usage

Paginated model-call billing details, snapshoted by price (priceSnapshotId), ordered by order creation time descending. Only normal charge records (reason = model usage) are returned.

Query parameters:

curl --request GET \
  --url "https://api.basicrouter.ai/api/v1/usage?page=1&size=20&startTime=2026-07-01T00:00:00&endTime=2026-07-31T23:59:59" \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

Response wrapper:

{
  "code": 0,
  "message": "success",
  "data": { ... }
}

UsageDetailVO fields:

CreditDetailItem fields:

Null-value convention: only the fields relevant to each modelType are populated; the rest are null. text populates the token fields; image populates imageCount/imageResolution/imageRatio; video populates videoResolution/videoRatio/videoDurationSec.

Response example:

{
  "code": 200,
  "message": "success",
  "data": {
    "records": [
      {
        "priceSnapshotId": "snap_9f3c1a2b",
        "taskId": "task_5e8a1c33",
        "credit": 0.0342,
        "model": "glm-5.2",
        "modelType": "text",
        "inputTokens": 1280,
        "outputTokens": 642,
        "totalTokens": 1922,
        "cacheReadTokens": 0,
        "cacheWriteTokens": 0,
        "imageCount": null,
        "imageResolution": null,
        "imageRatio": null,
        "videoResolution": null,
        "videoRatio": null,
        "videoDurationSec": null,
        "orderCreatedAt": "2026-07-18T14:23:11",
        "creditDetails": [
          {
            "credit": 0.0342,
            "deductionSource": "balance",
            "packageName": ""
          }
        ]
      },
      {
        "priceSnapshotId": "snap_a12f77c0",
        "taskId": "task_c71e44a2",
        "credit": 1.8000,
        "model": "seedance-2.0",
        "modelType": "video",
        "inputTokens": null,
        "outputTokens": null,
        "totalTokens": null,
        "cacheReadTokens": null,
        "cacheWriteTokens": null,
        "imageCount": null,
        "imageResolution": null,
        "imageRatio": null,
        "videoResolution": "1080p",
        "videoRatio": "16:9",
        "videoDurationSec": 8,
        "orderCreatedAt": "2026-07-17T22:41:09",
        "creditDetails": [
          {
            "credit": 1.5000,
            "deductionSource": "Monthly Package",
            "packageName": "基础月度套餐"
          },
          {
            "credit": 0.3000,
            "deductionSource": "Resource Package",
            "packageName": "byteplus视频资源包"
          }
        ]
      }
    ],
    "total": 128,
    "current": 1,
    "size": 20,
    "pages": 7
  }
}

GET https://api.basicrouter.ai/api/v1/billing/transactions

Paginated list of the current user's paid (status=2) recharge transactions, ordered by created_at descending.

curl --request GET \
  --url "https://api.basicrouter.ai/api/v1/billing/transactions?page=1&size=20&startTime=2026-07-01%2000:00:00&endTime=2026-07-31%2023:59:59" \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

Response wrapper:

{
  "code": 0,
  "message": "success",
  "data": { ... }
}

TransactionVO fields:

TransactionVO fields:

{
  "code": 200,
  "message": "success",
  "data": {
    "records": [
      {
        "orderNo": "R20260718abc123",
        "thirdPartyOrderNo": "wx_pay_xxx",
        "amount": 50.00,
        "actualAmount": 48.50,
        "discount": 1.50,
        "paymentMethod": "wechat",
        "serviceFeeAmount": 0.00,
        "paymentChannel": "wechat",
        "source": "recharge",
        "packageName": null,
        "createdAt": "2026-07-18T14:23:11"
      }
    ],
    "total": 28,
    "current": 1,
    "size": 20,
    "pages": 2
  }
}

Operational

Errors

BasicRouter returns stable error codes so applications can handle retries, fallbacks, billing issues, and debugging consistently.

Provider-compatible endpoints try to preserve the original API family's error shape where possible. BasicRouter-native endpoints use the BasicRouter error object.

HTTP status and error code mapping

Common error codes