DEV Community: Jenny Met

text-embedding-3-small Dimensions Explained: 1536 vs 1024 vs 512

Jenny Met — Sat, 06 Jun 2026 14:13:22 +0000

text-embedding-3-small Dimensions Explained: 1536 vs 1024 vs 512

If you use text-embedding-3-small, one small setting can quietly affect your whole retrieval system: embedding dimensions.

The default vector length is 1536 dimensions. That is a good default. But it is not always the cheapest or fastest choice once you store millions of chunks in a vector database.

This guide explains what text-embedding-3-small dimensions means, when to keep 1536, when to test smaller vectors, and how to call an OpenAI-compatible embeddings endpoint with real code.

What are text-embedding-3-small dimensions?

An embedding turns text into a list of numbers. That list is a vector.

For text-embedding-3-small, the default vector has 1536 numbers. If you embed the sentence:

“API gateways help developers route model calls.”

The model returns one vector that represents the meaning of that whole input. The vector is not one number per word. It is one semantic representation for the input text you send.

You then store that vector in a vector database such as pgvector, Pinecone, Milvus, Weaviate, Chroma, or Qdrant. When a user searches, you embed the query and compare it against stored vectors.

Official OpenAI documentation states that text-embedding-3-small defaults to 1536 dimensions, while text-embedding-3-large defaults to 3072 dimensions. It also supports a dimensions parameter that can reduce the output vector length.

External references:

Default text-embedding-3-small dimensions: why 1536 is common

1536 dimensions is popular because it is the default. It is also a practical balance between quality and cost for many semantic search and RAG workloads.

Use the default 1536 dimensions when:

You are building your first retrieval system.
You do not have evaluation data yet.
Your dataset is small enough that vector storage is not painful.
Search quality matters more than a few gigabytes of storage.
You want fewer moving parts during the first launch.

That last point matters. If your app is still early, the biggest risk is usually not vector size. It is bad chunking, weak retrieval evaluation, missing metadata filters, or poor prompts.

Start simple. Then optimize.

The dimensions parameter: what changes and what does not

The dimensions parameter lets you request a shorter embedding vector.

For example, instead of asking for the default 1536-dimensional vector, you can request 1024, 768, or 512 dimensions if your provider supports it for that model.

What changes:

Area	1536 dimensions	1024 / 768 / 512 dimensions
Vector storage	Larger	Smaller
Index memory	Larger	Smaller
Search latency	Often higher	Often lower
Retrieval quality	Strong baseline	Must be tested
API input token cost	Usually unchanged	Usually unchanged

What does not usually change: the number of input tokens you send. Embedding API pricing is normally based on input tokens, not the final vector size.

That means smaller dimensions mainly help with storage, index memory, and retrieval speed. They are not a magic way to reduce the embedding generation bill.

Storage math: 1536 vs 1024 vs 512 dimensions

A float32 number uses 4 bytes. So the raw vector size is:

vector_size_bytes = dimensions × 4

For one vector:

Dimensions	Bytes per vector	Storage vs 1536
1536	6,144 bytes	Baseline
1024	4,096 bytes	~33% smaller
768	3,072 bytes	~50% smaller
512	2,048 bytes	~67% smaller

For 1 million chunks, raw float32 vector storage looks like this:

Dimensions	Raw vector storage	With rough 35% index overhead
1536	~5.72 GiB	~7.72 GiB
1024	~3.81 GiB	~5.15 GiB
768	~2.86 GiB	~3.86 GiB
512	~1.91 GiB	~2.57 GiB

This is why dimensions start to matter at scale. A small difference per vector becomes real infrastructure cost when you store millions of chunks.

Quick calculator for embedding dimensions

Here is a small Python tool you can use to estimate storage and rough generation cost.

#!/usr/bin/env python3
import argparse


def gib(n):
    return n / (1024 ** 3)


def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--documents", type=int, required=True)
    parser.add_argument("--avg-tokens", type=int, required=True)
    parser.add_argument("--dimensions", type=int, nargs="+", default=[1536, 1024, 768, 512])
    parser.add_argument("--price-per-million", type=float, default=0.02)
    args = parser.parse_args()

    total_tokens = args.documents * args.avg_tokens
    estimated_cost = total_tokens / 1_000_000 * args.price_per_million

    print(f"Documents: {args.documents:,}")
    print(f"Estimated input tokens: {total_tokens:,}")
    print(f"Embedding generation cost: ${estimated_cost:,.2f}")
    print()
    print("Dims  Raw GiB  With 35% index overhead")

    for dim in args.dimensions:
        raw_bytes = args.documents * dim * 4
        print(f"{dim:>4}  {gib(raw_bytes):>7.2f}  {gib(raw_bytes * 1.35):>24.2f}")


if __name__ == "__main__":
    main()

Example:

python3 embedding_dimension_calculator.py --documents 1000000 --avg-tokens 350

Example output:

Embedding Dimension Calculator
================================
Documents/chunks: 1,000,000
Average tokens/chunk: 350
Estimated input tokens: 350,000,000
Embedding generation cost @ $0.02/1M tokens: $7.00

Dimension storage comparison
--------------------------------
  Dims  Bytes/vector     Raw GiB  With index GiB  Saved vs max
  1536         6,144        5.72            7.72            0%
  1024         4,096        3.81            5.15           33%
   768         3,072        2.86            3.86           50%
   512         2,048        1.91            2.57           67%

The important lesson: generation cost can stay small, while vector database cost and memory can grow quickly.

API example: default 1536 dimensions

Here is a standard OpenAI-compatible embeddings call.

curl https://crazyrouter.com/v1/embeddings \
  -H "Authorization: Bearer $CRAZYROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": "Explain API gateway routing in one paragraph."
  }'

The response includes an embedding array. With the default setting, its length should be 1536.

You can use the same pattern with any OpenAI-compatible client. With Crazyrouter, you only change the base URL and API key:

Base URL: https://crazyrouter.com/v1
Endpoint: /embeddings
Auth: Authorization: Bearer YOUR_KEY

Related internal guides:

Python example: check the vector length

from openai import OpenAI

client = OpenAI(
    api_key="your-crazyrouter-api-key",
    base_url="https://crazyrouter.com/v1",
)

response = client.embeddings.create(
    model="text-embedding-3-small",
    input="A vector database stores embeddings for semantic search.",
)

vector = response.data[0].embedding
print(len(vector))  # usually 1536 by default
print(vector[:5])   # preview the first few values

Do not paste real keys into code. Use environment variables in production.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["CRAZYROUTER_API_KEY"],
    base_url="https://crazyrouter.com/v1",
)

Python example: request custom dimensions

If your embeddings provider supports the dimensions parameter for text-embedding-3-small, you can request a shorter vector.

from openai import OpenAI

client = OpenAI(
    api_key="your-crazyrouter-api-key",
    base_url="https://crazyrouter.com/v1",
)

response = client.embeddings.create(
    model="text-embedding-3-small",
    input="Shorter embeddings can reduce vector database storage.",
    dimensions=1024,
)

vector = response.data[0].embedding
print(len(vector))  # expected: 1024 when supported

Important: do not mix dimensions in the same vector index. If your collection was created for 1536-dimensional vectors, a 1024-dimensional vector will usually fail at insert time.

Use one collection per dimension setting.

Node.js example: embeddings with OpenAI-compatible base URL

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.CRAZYROUTER_API_KEY,
  baseURL: "https://crazyrouter.com/v1",
});

const response = await client.embeddings.create({
  model: "text-embedding-3-small",
  input: "Embeddings help search by meaning, not just keywords.",
});

const vector = response.data[0].embedding;
console.log(vector.length);

Which dimensions should you choose?

There is no universal best value. Choose based on evaluation, not vibes.

A practical starting point:

Use case	Suggested starting dimensions	Why
Prototype / small app	1536	Maximize quality while you learn
Support docs RAG	1536 or 1024	Quality matters, but storage can grow
Large FAQ search	1024	Often a good balance to test
High-volume semantic cache	768 or 512	Speed and memory may matter more
Legal / medical / financial retrieval	1536	Test carefully before reducing
Mobile / edge search	512 or 768	Smaller vectors are easier to move

For production, run an evaluation set. Take 50 to 200 real user queries. Label the best matching documents. Compare recall@5 or recall@10 for 1536, 1024, 768, and 512.

If 1024 gives almost the same recall as 1536, you can reduce storage and memory without hurting users.

Common mistakes with text-embedding-3-small dimensions

Mistake 1: mixing 1536 and 1024 vectors in one index

Vector databases expect a fixed dimension per collection or index. If you change dimensions, create a new index and re-embed the corpus.

Mistake 2: optimizing dimensions before chunking

Bad chunking hurts retrieval more than a larger vector helps it.

Fix chunking first:

Keep chunks focused.
Add useful metadata.
Avoid huge mixed-topic chunks.
Test overlap instead of guessing.

Mistake 3: assuming smaller dimensions reduce API cost

Embedding generation cost is usually based on input tokens. Smaller vectors reduce storage and search costs, not necessarily API call cost.

Mistake 4: choosing 512 without evaluation

512-dimensional vectors can work for some workloads. But they may lose recall on nuanced queries. Test them before moving production search.

Mistake 5: forgetting downstream schema changes

If you use pgvector, your schema may include a fixed dimension:

CREATE TABLE documents (
  id bigserial PRIMARY KEY,
  content text,
  embedding vector(1536)
);

If you switch to 1024, you need a different column or table:

CREATE TABLE documents_1024 (
  id bigserial PRIMARY KEY,
  content text,
  embedding vector(1024)
);

A simple evaluation workflow

Use this workflow before changing dimensions in production:

Pick 100 real user queries.
Label the correct documents for each query.
Create separate indexes for 1536, 1024, 768, and 512.
Run the same queries against each index.
Compare recall@5, recall@10, latency, and memory.
Choose the smallest dimension that does not hurt retrieval quality.

This is more reliable than reading a benchmark and hoping it matches your data.

Final recommendation

For most teams, the best first move is simple:

Start with text-embedding-3-small at 1536 dimensions.
Build a clean retrieval evaluation set.
Test 1024 once your corpus grows.
Try 768 or 512 only when storage, memory, or latency becomes important.

If you already use OpenAI-compatible tools, you can test this through Crazyrouter by setting your base URL to https://crazyrouter.com/v1 and calling /embeddings with your normal SDK.

The goal is not to use the smallest vector. The goal is to use the smallest vector that still retrieves the right answer.

FAQ: text-embedding-3-small dimensions

What are the default text-embedding-3-small dimensions?

The default text-embedding-3-small output is 1536 dimensions. That means each input text returns a vector with 1536 numeric values.

Can I change text-embedding-3-small dimensions?

Yes, when your provider supports the dimensions parameter, you can request a shorter vector. Common test values are 1024, 768, and 512.

Do smaller embedding dimensions reduce API cost?

Usually not directly. Embedding API cost is normally based on input tokens. Smaller dimensions mainly reduce vector storage, index memory, and search latency.

Is 512 dimensions enough for text-embedding-3-small?

Sometimes. It depends on your dataset and retrieval quality requirements. Use an evaluation set before using 512 dimensions in production.

Can I store 1536 and 1024 dimension vectors in the same database table?

Usually no. Most vector indexes require a fixed dimension. Create separate collections or tables when testing different dimensions.

Should I use text-embedding-3-small or text-embedding-3-large?

Use text-embedding-3-small for cost-effective general retrieval. Test text-embedding-3-large when retrieval quality is the main bottleneck and you can afford larger vectors.

What is the best dimension for RAG?

Start with 1536 for text-embedding-3-small. Then test 1024 and 768 against real queries. The best dimension is the smallest one that preserves your recall target.

Stop AI Agents from Guessing API Routes: Crazyrouter llms.txt Endpoint Guide

Jenny Met — Sat, 06 Jun 2026 14:12:53 +0000

Stop AI Agents from Guessing API Routes: Crazyrouter `llms.txt` Endpoint Guide

When an AI agent writes API code, the most expensive bug is often not a typo. It is an endpoint mismatch.

A model might support Chat Completions, Responses, Claude Messages, Gemini native calls, image generation, video generation, or audio APIs. If the AI guesses the route from memory, the generated code may look reasonable while still being wrong.

Crazyrouter's llms.txt helps prevent that.

https://docs.crazyrouter.com/llms.txt

The user-facing guide is here:

https://docs.crazyrouter.com/llms-guide?utm_source=devto&utm_medium=article&utm_campaign=llms_txt_docs

The core idea

Before generating code, tell the AI to read the docs entry point and match the model's endpoint type to the correct documentation page.

Use this prompt:

Read https://docs.crazyrouter.com/llms.txt first.
Use Crazyrouter's official docs to choose the correct endpoint.
Do not invent model names, prices, billing modes, or routes from memory.
Generate code only after matching the model to the correct endpoint type.

Common endpoint mappings

Here are the important mappings AI tools should not guess:

Use case	Crazyrouter endpoint
OpenAI Chat Completions	`POST /v1/chat/completions`
OpenAI Responses	`POST /v1/responses`
Anthropic Messages	`POST /v1/messages`
Gemini native	`POST /v1beta/models/{model}:generateContent`
Image generation	`POST /v1/images/generations`
Image editing	`POST /v1/images/edits`
OpenAI-style video	`POST /v1/video/generations` or `POST /v1/videos`
Unified video	`POST /v1/video/create` and `GET /v1/video/query`
Text-to-speech	`POST /v1/audio/speech`
Speech-to-text	`POST /v1/audio/transcriptions`

Base URL details

For OpenAI-compatible SDKs:

https://cn.crazyrouter.com/v1

For raw HTTP Chat Completions:

https://cn.crazyrouter.com/v1/chat/completions

For Anthropic-native clients, use the root domain expected by the client rather than manually appending /v1 in the wrong place.

This is the kind of detail that llms.txt is designed to surface before the AI writes code.

Pricing and model availability

Do not ask an AI model to rely on memory for model names or prices.

Use:

https://crazyrouter.com/pricing

For machine-readable pricing data:

https://crazyrouter.com/api/pricing?lang=en

For the exact models available to a specific API key:

curl https://cn.crazyrouter.com/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

Use YOUR_API_KEY in shared prompts. Do not paste real keys into public chats or untrusted tools.

Example: better agent instruction

Bad prompt:

Write code to call a Crazyrouter model.

Better prompt:

Read https://docs.crazyrouter.com/llms.txt first.
My task is to call [MODEL_NAME] from Node.js.
Check which endpoint type applies, then write runnable code.
Use YOUR_API_KEY as the placeholder.
If the model or endpoint is uncertain, tell me to verify it on https://crazyrouter.com/pricing or GET /v1/models.

Why this matters for agent workflows

AI coding agents are increasingly asked to configure entire projects:

Cursor project settings
Cline providers
Claude Code API setup
Codex CLI Responses API setup
OpenAI-compatible SDK examples
video and image generation scripts
multimodal demos

A small routing error can waste a lot of time. llms.txt gives the agent a map before it starts editing files.

Start with the full guide:

https://docs.crazyrouter.com/llms-guide?utm_source=devto&utm_medium=article&utm_campaign=llms_txt_docs

/v1/chat/completions vs /v1/responses vs /v1/messages: Which AI API Endpoint Should You Use?

Jenny Met — Thu, 04 Jun 2026 23:57:09 +0000

/v1/chat/completions vs /v1/responses vs /v1/messages: Which AI API Endpoint Should You Use?

A common support issue in AI API gateways is not the API key, not the model, and not the SDK. It is the endpoint.

A user picks a model that exists, but sends the request to the wrong endpoint. The result looks like:

model unavailable;
unsupported endpoint;
invalid request body;
tool calling not working;
streaming format mismatch;
Claude model works in one tool but fails in another.

This guide explains the difference between three endpoint families:

/v1/chat/completions
/v1/responses
/v1/messages

Short version:

Endpoint	Native ecosystem	Best for	Request style
`/v1/chat/completions`	OpenAI-compatible legacy/current chat	Most apps, SDKs, LiteLLM, Cursor-style tools, simple chat	`messages: [{role, content}]`
`/v1/responses`	Newer OpenAI Responses API	Tool use, multimodal, reasoning items, newer OpenAI-style agents	`input`, `tools`, structured response items
`/v1/messages`	Anthropic Claude API	Claude-native SDKs and Claude-style apps	`messages` plus top-level `system`, Anthropic schema

If your client says “OpenAI-compatible”, start with:

https://crazyrouter.com/v1/chat/completions

or set base URL to:

https://crazyrouter.com/v1

and let the SDK append /chat/completions.

If your tool specifically requires the OpenAI Responses API, use /v1/responses.

If your tool is Anthropic-native and expects Claude’s Messages API, use /v1/messages.

The most common mistake

The most common mistake is mixing the model family and the endpoint family.

For example, a Claude model can be exposed through an OpenAI-compatible gateway, but that does not automatically mean your request body should use Anthropic’s native /v1/messages schema.

Likewise, a tool that sends Anthropic-native requests to /v1/messages cannot be fixed by only changing the model name. The endpoint and request body must match.

Think of it this way:

model name + endpoint + request schema must match

If one of the three is wrong, the model may look unavailable even when the model itself is healthy.

What `/v1/chat/completions` is

/v1/chat/completions is the classic OpenAI-compatible chat endpoint.

A typical request looks like this:

curl https://crazyrouter.com/v1/chat/completions \
  -H "Authorization: Bearer $CRAZYROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Explain API endpoints in one paragraph."}
    ]
  }'

Use /v1/chat/completions when:

the app says it supports an OpenAI-compatible API;
the config asks for OPENAI_BASE_URL or base_url;
the request body uses messages with role and content;
you are using common OpenAI SDK compatibility mode;
you are configuring tools like Cursor-style clients, LiteLLM-style routers, FastGPT-style apps, or many chat UIs.

For many users, this is the safest default endpoint.

What `/v1/responses` is

/v1/responses is the newer OpenAI Responses API endpoint.

It is designed around a more general response object, and it can represent things like:

text output;
tool calls;
multimodal input;
reasoning items;
structured output;
agent-like workflows.

A simplified request looks like this:

curl https://crazyrouter.com/v1/responses \
  -H "Authorization: Bearer $CRAZYROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "input": "Explain the difference between chat completions and responses."
  }'

Use /v1/responses when:

the tool explicitly says it uses the OpenAI Responses API;
the config mentions responses rather than chat.completions;
the request body uses input instead of messages;
the model/provider route supports Responses API behavior;
you need newer OpenAI-style tool or reasoning output formats.

Do not send a Chat Completions body to /v1/responses unless the gateway explicitly documents that conversion.

What `/v1/messages` is

/v1/messages is the Anthropic Messages API style endpoint.

A typical Claude-native request looks like this:

curl https://crazyrouter.com/v1/messages \
  -H "Authorization: Bearer $CRAZYROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "system": "You are a helpful assistant.",
    "messages": [
      {"role": "user", "content": "Explain Claude Messages API."}
    ]
  }'

Use /v1/messages when:

the client is Anthropic-native;
the SDK expects Claude Messages API format;
the request has top-level system instead of a system message inside the array;
the request requires Anthropic-specific content blocks or tool schema;
the documentation explicitly says to call /v1/messages.

Do not assume every Claude model should be called with /v1/messages. If you are using an OpenAI-compatible gateway or SDK, Claude models may be called through /v1/chat/completions instead.

Why endpoint mistakes make models look unavailable

When a model fails, users often assume the model is down. But in many cases, the model is fine and the request format is wrong.

Common mismatch examples:

Mistake	What happens	Fix
Sending `messages` chat body to `/v1/responses`	Invalid request body or ignored fields	Use `/v1/chat/completions` or change body to `input`
Sending Anthropic `system` + `messages` body to `/v1/chat/completions`	Schema mismatch	Use `/v1/messages` or convert to OpenAI message format
Using `/v1/messages` in an OpenAI SDK	SDK may append the wrong path or parse the wrong response	Use OpenAI-compatible base URL with chat completions
Missing `/v1` in base URL	404 or unknown route	Set base URL to `https://crazyrouter.com/v1`
Adding `/chat/completions` to base URL and SDK appends it again	Double path like `/chat/completions/chat/completions`	Base URL should usually end at `/v1`
Adding UTM parameters to API endpoint	Auth/routing errors	UTM only belongs on website links

Base URL vs full endpoint

Many tools ask for a Base URL, not a full endpoint.

Correct Base URL:

https://crazyrouter.com/v1

Then the SDK calls:

https://crazyrouter.com/v1/chat/completions

Wrong Base URL for most SDKs:

https://crazyrouter.com/v1/chat/completions

Why? Because the SDK may append /chat/completions again.

Rule:

If the field is called base_url, use /v1.
If the field is called endpoint and asks for a full URL, use the full path the tool requires.

Which endpoint should I choose?

Use this decision tree:

Does your tool say “OpenAI-compatible API”?

Use /v1/chat/completions or Base URL https://crazyrouter.com/v1.
Does your tool specifically say “Responses API”?

Use /v1/responses.
Does your tool use the Anthropic SDK or Claude Messages API?

Use /v1/messages.
Are you unsure?

Start with /v1/chat/completions, because most third-party clients support it.

Recommended Crazyrouter configuration

For most OpenAI-compatible tools:

API Key: your Crazyrouter API key
Base URL: https://crazyrouter.com/v1
Model: choose a model from the Crazyrouter model list

For users in regions where the global route is unstable:

Base URL: https://cn.crazyrouter.com/v1

Human-facing links can use UTM tracking:

https://crazyrouter.com/models?utm_source=blog&utm_medium=article&utm_campaign=api_endpoints

API endpoints should not:

https://api-endpoint.example.invalid/v1?utm_source=blog

Quick debugging checklist

Before reporting “model unavailable,” check these five things:

Is the model name spelled exactly as shown in the model list?
Is the endpoint family correct: chat completions, responses, or messages?
Does the request body match that endpoint’s schema?
Is the Base URL exactly /v1, not missing it and not duplicating endpoint paths?
Are you using the right SDK mode: OpenAI-compatible or Anthropic-native?

Final recommendation

If you are building general app integrations, start with /v1/chat/completions. It is the broadest compatibility path.

Use /v1/responses when your client or workflow explicitly requires the Responses API.

Use /v1/messages when you are using Anthropic-native tooling.

Most endpoint problems disappear when you remember this rule:

OpenAI-compatible client → /v1/chat/completions
OpenAI Responses client → /v1/responses
Anthropic-native client → /v1/messages

If the model exists but appears unavailable, do not only change the model name. Check the endpoint and request schema first.

Crazyrouter Codex CLI: Use Codex with One API Key and an OpenAI-Compatible Gateway

Jenny Met — Thu, 04 Jun 2026 16:57:39 +0000

Crazyrouter Codex CLI: Use Codex with One API Key and an OpenAI-Compatible Gateway

OpenAI Codex CLI is useful when you want an AI coding agent directly inside your terminal. The painful part is not the idea — it is the setup: API keys, base URLs, model names, Windows environment variables, macOS shell profiles, Linux config files, and different providers for different models.

The new crazyrouter-codex-cli repo solves one specific problem:

connect Codex CLI to Crazyrouter with one API key and an OpenAI-compatible API endpoint.

Repository:

https://github.com/xujfcn/crazyrouter-codex-cli

What this repo does

The repo provides simple install scripts for:

Windows PowerShell
Windows batch file
macOS
Linux

It configures Codex CLI to use:

OPENAI_BASE_URL=https://cn.crazyrouter.com/v1
OPENAI_API_KEY=your-crazyrouter-key

That means Codex CLI can talk to Crazyrouter through an OpenAI-compatible interface, while Crazyrouter handles the model/provider side.

Important rule:

Do not add UTM parameters to API endpoints. UTM belongs on human-clickable website links, not OPENAI_BASE_URL.

Correct:

export OPENAI_BASE_URL=https://cn.crazyrouter.com/v1

Wrong:

export OPENAI_BASE_URL=https://cn.crazyrouter.com/v1?utm_source=...

Why use Codex CLI through Crazyrouter?

A terminal coding agent is most useful when it can become part of your normal development loop:

open a project directory;
ask the agent to inspect code;
let it patch files;
run tests;
review the diff;
repeat.

But real developer teams often want more than one model. Some tasks need a fast low-cost model. Some need a stronger reasoning model. Some need Claude-style code review. Some need Gemini-style long-context analysis. Some teams also need a more stable route from regions where direct access is unreliable.

Crazyrouter gives Codex CLI a single OpenAI-compatible gateway:

one API key;
one base URL;
multiple model choices;
OpenAI-compatible client configuration;
easier switching between coding models.

One-command install

Windows PowerShell

Open PowerShell as a normal user and run:

iwr -UseB https://raw.githubusercontent.com/xujfcn/crazyrouter-codex-cli/main/install-crazyrouter-codex.ps1 | iex

Or download and run:

install-crazyrouter-codex.bat

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/xujfcn/crazyrouter-codex-cli/main/install-crazyrouter-codex.sh | bash

The script asks for your Crazyrouter API key, writes the needed environment variables, and backs up existing Codex configuration when needed.

Manual setup

If you prefer to configure it yourself, install Codex CLI first:

npm install -g @openai/codex

Node.js 22+ is recommended.

Then set the environment variables.

macOS / Linux

export OPENAI_API_KEY=sk-your-crazyrouter-key
export OPENAI_BASE_URL=https://cn.crazyrouter.com/v1

Windows PowerShell

setx OPENAI_API_KEY "sk-your-crazyrouter-key"
setx OPENAI_BASE_URL "https://cn.crazyrouter.com/v1"

After setx, reopen your terminal.

Then start Codex:

codex

Codex `config.toml` example

Some Codex CLI versions support provider configuration in:

Windows: %USERPROFILE%\.codex\config.toml
macOS / Linux: ~/.codex/config.toml

Example:

model = "gpt-5.5"
model_provider = "crazyrouter"

[model_providers.crazyrouter]
name = "Crazyrouter"
base_url = "https://cn.crazyrouter.com/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

[model_providers.crazyrouter.query_params]

If you see this error:

wire_api = "chat" is no longer supported

change:

wire_api = "chat"

to:

wire_api = "responses"

Model selection

Once the gateway is configured, you can start Codex with the default model or specify one explicitly:

codex
codex --model gpt-5.5
codex --model gpt-4o-mini
codex --model claude-sonnet-4-6

Model availability can vary by account, provider route, and current upstream status. Check the current model list here:

Crazyrouter model list

Practical workflow example

A simple Codex CLI coding loop:

cd your-project
codex

Then ask:

Inspect this repo and explain the architecture. Do not edit files yet.

After the summary:

Find the smallest safe fix for the failing login test. Make the change, then run the relevant test only.

Then review:

git diff
npm test -- login

The gateway setup does not replace careful review. It makes the model/provider configuration less annoying so you can focus on the actual engineering loop.

Troubleshooting

`codex: command not found`

Install Codex globally:

npm install -g @openai/codex

Then check:

which codex
codex --help

On Windows, reopen the terminal after installation.

API key not found

Check whether the environment variable exists.

macOS / Linux:

echo $OPENAI_API_KEY

Windows PowerShell:

$env:OPENAI_API_KEY

If empty, set it again.

Wrong base URL

The base URL should be exactly:

https://cn.crazyrouter.com/v1

Do not add /chat/completions, /responses, or UTM parameters. Client libraries append the final API path themselves.

Existing Codex config conflict

If you had another provider configured before, check:

cat ~/.codex/config.toml

Make sure the selected model_provider points to the Crazyrouter provider block.

When this setup is useful

This repo is especially useful for developers who:

use Codex CLI but want an OpenAI-compatible gateway;
want to try multiple models from one CLI setup;
work across Windows, macOS, and Linux machines;
need a repeatable install script for teammates;
want a simpler path for AI coding workflows in regions where direct provider access can be unstable.

Bottom line

crazyrouter-codex-cli is a small repo, but it removes a common setup tax: configuring Codex CLI to use an OpenAI-compatible gateway correctly.

If you want Codex CLI with one key, one base URL, and easier model routing, start here:

https://github.com/xujfcn/crazyrouter-codex-cli

AI Image API Playground: Test GPT Image, Imagen, Qwen Image and FLUX Online

Jenny Met — Thu, 04 Jun 2026 13:53:52 +0000

AI Image API Playground: Test GPT Image, Imagen, Qwen Image and FLUX Online

If you are building image generation into a product, do not pick a model from a pricing table alone.

Test the same prompt across multiple image models first.

A good AI image API playground lets you compare output style, prompt following, text rendering, product accuracy, speed, and cost before you commit to a provider-specific integration. That matters because GPT Image, Imagen, Qwen Image, FLUX, and DALL-E-style workflows can behave very differently on the same request.

This guide shows how developers can use an image API playground to test multiple AI image models with one API key, then move the winning model into production through an OpenAI-compatible endpoint.

Quick answer

Use an AI image API playground when you need to answer questions like:

Which image model follows my prompt most accurately?
Which model handles product photos, posters, UI assets, or text-heavy images best?
Which model is good enough for the cost?
Can I copy a working API request after testing visually?
Can my application switch models later without rewriting the integration?

For Crazyrouter users, the image workflow is:

open the image playground;
write one test prompt;
run it across image models such as GPT Image, Imagen, Qwen Image, FLUX, and DALL-E-style models;
compare results;
copy the cURL/API request;
move the request to https://crazyrouter.com/v1/images/generations.

Human-facing test page:

https://image.crazyrouter.com?utm_source=blog&utm_medium=article&utm_campaign=image_api_playground

Production API endpoint:

https://crazyrouter.com/v1/images/generations

Do not add UTM parameters to API endpoints. Use tracking only on human-facing links.

Why image model testing is different from chat model testing

Chat models are usually judged by text quality, reasoning, latency, tool use, and price.

Image models need a different checklist:

visual style consistency;
prompt following;
product detail accuracy;
text rendering inside images;
brand-safety behavior;
aspect ratio support;
edit vs generation support;
reproducibility;
cost per accepted asset, not just cost per request.

For example, a model that creates beautiful cinematic images may fail on product packaging text. A model that handles text well may not be the cheapest for bulk poster generation. A model that is excellent for photorealism may not fit UI mockups.

That is why a playground is useful: it lets you compare before you wire the model into a production workflow.

Model comparison: what to test first

Start with a small matrix. Do not test twenty models with random prompts. Pick three real prompts from your product and run them consistently.

Model family	Best for	Watch out for	Recommended test prompt
GPT Image / DALL-E-style workflows	Instruction following, edits, product mockups, structured scenes	May cost more on large batches	“Create a clean SaaS hero image showing a dashboard, API routing lines, and four model cards.”
Imagen	Photorealistic visuals, natural lighting, polished marketing images	Provider-specific behavior can differ across versions	“Photorealistic product photo of a matte black wireless keyboard on a white desk, soft studio lighting.”
Qwen Image	Text-heavy images, multilingual prompts, practical creative assets	Test exact typography and small text before production	“A bilingual poster with the words ‘One API Key’ and ‘统一模型入口’, clean developer conference style.”
FLUX	Stylized posters, creative visuals, hero images, social media graphics	Version choice matters; compare style vs accuracy	“Cyberpunk developer workspace with floating API nodes and neon model labels, editorial illustration.”

The goal is not to declare one universal winner. The goal is to pick the right model for the task.

Three prompts to use in your first test

Use prompts that map to real production needs.

1. Product photo prompt

Create a photorealistic ecommerce product image of a minimalist white smart speaker on a light gray background. Soft studio lighting, realistic shadows, no text, centered composition, high-end product catalog style.

What to evaluate:

product shape consistency;
realistic reflections and shadows;
whether the model invents unwanted logos or text;
whether the result is clean enough for an ecommerce page.

2. SaaS hero image prompt

Create a clean SaaS hero image for an AI API dashboard. Show multiple model cards connected to one central API key, with subtle blue and purple gradients, modern UI panels, no brand logos, professional developer-tool style.

What to evaluate:

dashboard layout clarity;
whether the image looks like a real product visual;
whether it avoids fake unreadable UI clutter;
whether the style matches a B2B website.

3. Text-heavy poster prompt

Design a modern developer conference poster with the exact headline “One API Key, Many AI Models”. Include small abstract icons for text, image, audio, and video generation. Clean typography, white background, blue accent color.

What to evaluate:

exact text rendering;
typography quality;
layout balance;
whether the model introduces misspellings.

Text-heavy prompts are especially important because many image models still struggle with precise typography.

How to use the playground

A developer-friendly AI image playground should not only return a pretty image. It should help you turn the result into an API call.

Use this workflow:

Open the playground.
Paste a real production prompt.
Choose the first candidate model.
Set size, quality, and count.
Generate the image.
Save the output and notes.
Repeat with the same prompt on other models.
Compare accepted outputs, not just raw generations.
Copy the generated cURL/API request.
Move the request into your application.

For Crazyrouter image testing, use:

https://image.crazyrouter.com?utm_source=blog&utm_medium=article&utm_campaign=image_api_playground

The key point is repeatability. Run the same prompt across models, then score the results with the same criteria.

Production API example

Once you find a model that works, move to the API.

A typical OpenAI-compatible image generation request looks like this:

curl https://crazyrouter.com/v1/images/generations \
  -H "Authorization: Bearer $CRAZYROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image",
    "prompt": "Create a clean SaaS hero image for an AI API dashboard. Show multiple model cards connected to one central API key, with subtle blue and purple gradients, modern UI panels, no brand logos.",
    "size": "1024x1024",
    "n": 1
  }'

In Python:

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_CRAZYROUTER_API_KEY",
    base_url="https://crazyrouter.com/v1",
)

result = client.images.generate(
    model="qwen-image",
    prompt="Create a clean SaaS hero image for an AI API dashboard. Show multiple model cards connected to one central API key.",
    size="1024x1024",
    n=1,
)

print(result)

The exact available model IDs can change as providers release new versions. Always copy the current model ID from the live model list or playground.

What to measure before production

A playground test is useful only if you measure the right things.

Use this scoring sheet:

Criterion	Question	Score 1-5
Prompt following	Did the image include the requested objects, layout, and constraints?
Visual quality	Would you publish this asset without heavy editing?
Text accuracy	If text was requested, was it spelled correctly?
Brand fit	Does the style match your product or campaign?
Cost fit	Is the accepted-output cost reasonable?
Repeatability	Can the model produce similar quality across multiple runs?
API fit	Does the model support the size, quality, and workflow you need?

The most important metric is not price per generation. It is price per accepted image.

If one model costs 30% more but produces usable assets twice as often, it may be cheaper in practice.

One API key vs separate provider accounts

You can integrate image models provider by provider. That works for a small test, but it becomes painful when your product grows.

Separate provider accounts usually mean:

multiple API keys;
different request formats;
different billing dashboards;
different quota systems;
different failure modes;
more engineering work when switching models.

A unified API gateway changes the workflow:

one API key;
one account balance;
one OpenAI-compatible request style;
multiple image model families;
easier model switching;
simpler fallback logic.

For teams building SaaS tools, ecommerce automation, marketing creative systems, or AI agents, this flexibility matters more than the playground itself.

Recommended model selection workflow

Use this simple process:

Explore: run your prompt in the playground across 3-5 model families.
Score: evaluate accepted outputs with a consistent rubric.
Estimate: calculate cost per accepted image.
Integrate: copy the API request into your app.
Fallback: define a second model for failures or cost spikes.
Monitor: track latency, failures, and acceptance rate.

That last step is easy to skip. Do not skip it.

Image generation quality changes over time as providers update models. The best model for your prompt in June may not be the best model three months later.

Common mistakes

Mistake 1: Testing only one prompt

A single beautiful output does not prove the model is right for your product.

Use at least three prompt types: product photo, website hero, and text-heavy poster.

Mistake 2: Comparing screenshots instead of accepted outputs

If a model returns five images and only one is usable, count that. Your real cost is higher than the sticker price.

Mistake 3: Forgetting text rendering

If your use case needs labels, posters, packaging, or UI text, test exact spelling early.

Mistake 4: Hardcoding one model forever

Use model IDs intentionally, but keep your application flexible. Image model quality and pricing move quickly.

Mistake 5: Adding UTM parameters to API URLs

Use UTM parameters on article links and landing pages. Do not append them to API endpoints such as /v1/images/generations.

FAQ

What is an AI image API playground?

An AI image API playground is a web interface where developers can test image generation models before integrating them into code. A good playground also provides copyable API requests.

Why test multiple AI image models?

Different models perform differently on photorealism, text rendering, edits, product accuracy, style, and cost. Testing multiple models reduces the risk of choosing the wrong provider too early.

Can I use one API key for multiple image models?

Yes. With Crazyrouter, you can use one API key and an OpenAI-compatible endpoint to access multiple model families, including image generation workflows.

Which image model is best for product photos?

There is no universal answer. Start by testing Imagen, GPT Image/DALL-E-style models, Qwen Image, and FLUX-style models with the same product photo prompt. Score accepted outputs, not just raw generations.

Which image model is best for text in images?

Text rendering varies by model and version. Qwen Image and newer instruction-following image models are worth testing, but you should always test your exact headline, language, and layout.

Is the playground only for non-technical users?

No. A playground is useful for developers because it shortens the model selection loop. You can test visually, then copy a request into production code.

How do I move from playground to production?

Use the generated request as a starting point. In production, call https://crazyrouter.com/v1/images/generations with your API key, chosen model, prompt, size, and generation options.

Final recommendation

If you are adding image generation to an app, do not start by writing provider-specific integration code.

Start with a playground.

Test the same prompts across GPT Image, Imagen, Qwen Image, FLUX, and DALL-E-style workflows. Pick the model that produces the best accepted-output cost for your actual use case. Then integrate through one OpenAI-compatible API so you can switch models later.

Try the playground:

https://image.crazyrouter.com?utm_source=blog&utm_medium=article&utm_campaign=image_api_playground

Explore live models and pricing:

https://crazyrouter.com/models?utm_source=blog&utm_medium=article&utm_campaign=image_api_playground

How to Fix AI API 500, 502, and 524 Errors

Jenny Met — Thu, 04 Jun 2026 13:53:51 +0000

How to Fix AI API 500, 502, and 524 Errors

AI API errors are frustrating because they often appear at the worst possible time: during a demo, a production workflow, a coding-agent run, or a customer support automation task.

From real support conversations, three error families appear again and again:

500 — server-side or upstream failure;
502 — bad gateway or invalid upstream response;
524 — timeout, often from a long-running request.

The mistake is treating all three the same.

A retry might fix one request. It will not fix a fragile production design.

This guide explains what these errors usually mean, what to check first, and how to make AI API calls more resilient with logging, retries, model fallback, and endpoint fallback.

Quick error table

Error	Usually means	First action	Production fix
500	Internal server or upstream provider failure	Retry once and capture request details	Add retry with backoff and fallback model
502	Gateway could not get a valid upstream response	Try a nearby model or route	Add model/provider fallback
524	Request timed out	Reduce context/output or use streaming	Add timeout controls and split long tasks
429	Rate limit or quota issue	Reduce rate and check limits	Queue, throttle, or request higher limits
401/403	Auth or permission issue	Check API key and model access	Validate config before deploy

If you only remember one thing: log the model, endpoint, request time, error code, and whether streaming was enabled. Without that, troubleshooting becomes guesswork.

What a 500 AI API error usually means

A 500 error usually means something failed server-side.

In an AI API workflow, that could be:

the gateway encountered an internal error;
the upstream model provider returned an unexpected failure;
the model route was temporarily unstable;
the request payload triggered an edge case;
a long or complex request failed during processing.

A single 500 is often temporary.

A repeated 500 on the same request usually means you need to inspect the request shape.

Check:

model name;
endpoint path;
message format;
tool/function calling schema;
image/video/audio payload format;
context size;
whether the same request works on another model.

What a 502 AI API error usually means

A 502 Bad Gateway means the gateway did not receive a valid response from the upstream service.

For AI APIs, common causes include:

upstream provider instability;
overloaded model route;
bad or incomplete upstream response;
network interruption;
route-specific failure;
gateway-provider mismatch for a special model feature.

If a 502 happens once, retrying may be enough.

If it happens repeatedly on one model, test a similar model.

For example, if one high-end reasoning model is unstable, temporarily route the same prompt to:

a nearby model version;
a faster model in the same family;
a different provider with similar capability;
a cheaper fallback model for non-critical tasks.

This is where a gateway is useful: you can switch model routes without rewriting the app.

What a 524 timeout usually means

A 524 usually means the connection timed out while waiting for a response.

This is common with:

very long prompts;
large context windows;
huge expected outputs;
complex reasoning tasks;
image or video generation jobs;
non-streaming requests that run too long;
coding-agent workflows that ask the model to solve too much in one call.

Immediate fixes:

reduce input size;
lower max_tokens or output length;
use streaming for text responses;
split the task into smaller steps;
choose a faster model;
avoid asking for massive JSON output in one response.

A timeout is not always a platform outage. Sometimes it means the request is too large or too slow for a synchronous API call.

Immediate troubleshooting checklist

When an AI API request fails, do this before changing your whole setup.

Step	What to do	Why it helps
1	Retry once	Handles temporary upstream failure
2	Save the full error body	Error text often shows auth/model/payload clues
3	Record request time	Support can map it to route/provider logs
4	Record model name	Many failures are model-route specific
5	Check Base URL	Wrong endpoint causes confusing failures
6	Test a smaller prompt	Separates payload-size issues from route issues
7	Try streaming	Reduces timeout risk for long text responses
8	Try a nearby model	Confirms whether the issue is model-specific
9	Try region endpoint if needed	Helps when access to the global endpoint is unstable
10	Remove optional features	Tool calls, images, long JSON schemas can add failure points

For OpenAI-compatible clients with Crazyrouter, the common Base URLs are:

https://crazyrouter.com/v1

and:

https://cn.crazyrouter.com/v1

Do not add UTM parameters or tracking strings to API endpoints.

How to write a safe retry strategy

Retries help, but blind retries can make an outage worse.

Use exponential backoff with jitter:

import random
import time
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_CRAZYROUTER_API_KEY",
    base_url="https://crazyrouter.com/v1"
)

def call_with_retry(messages, model="gpt-5-mini", max_retries=3):
    last_error = None

    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(
                model=model,
                messages=messages,
                timeout=60,
            )
        except Exception as exc:
            last_error = exc
            wait = (2 ** attempt) + random.random()
            time.sleep(wait)

    raise last_error

This is better than retrying immediately in a tight loop.

Model fallback example

A production app should not depend on one model route for every task.

You can define a fallback list:

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_CRAZYROUTER_API_KEY",
    base_url="https://crazyrouter.com/v1"
)

MODELS = [
    "gpt-5-mini",
    "claude-sonnet-4-6",
    "gemini-2.5-flash",
]

def call_with_model_fallback(messages):
    errors = []

    for model in MODELS:
        try:
            return client.chat.completions.create(
                model=model,
                messages=messages,
                timeout=60,
            )
        except Exception as exc:
            errors.append({"model": model, "error": str(exc)})

    raise RuntimeError(f"All model routes failed: {errors}")

This pattern is especially useful for:

support bots;
internal automation;
coding agents;
summarization pipelines;
batch content workflows;
production apps with user-facing latency requirements.

Endpoint fallback example

If your users or servers sometimes have unstable access to one region, you can test an endpoint fallback.

from openai import OpenAI

ENDPOINTS = [
    "https://crazyrouter.com/v1",
    "https://cn.crazyrouter.com/v1",
]

API_KEY = "YOUR_CRAZYROUTER_API_KEY"

for base_url in ENDPOINTS:
    client = OpenAI(api_key=API_KEY, base_url=base_url)
    try:
        response = client.chat.completions.create(
            model="gpt-5-mini",
            messages=[{"role": "user", "content": "Health check"}],
            timeout=30,
        )
        print("working endpoint:", base_url)
        break
    except Exception as exc:
        print("failed endpoint:", base_url, exc)

Do not randomly switch endpoints on every request. Use endpoint fallback intentionally and log which route succeeded.

What to send support

If the issue persists, support can help much faster when you include the right information.

Send:

account email;
model name;
Base URL used;
endpoint path;
request time and timezone;
error code;
error body or screenshot;
whether streaming was enabled;
whether the same request works on another model;
simplified request body without secrets.

Do not send your full API key in public channels.

How a gateway helps with AI API reliability

An AI API gateway cannot make every upstream provider perfect.

But it can make your application more flexible.

With a gateway, you can:

switch models without rewriting SDK code;
route simple tasks to cheaper models;
route critical tasks to stronger models;
add fallback across model families;
keep one OpenAI-compatible integration surface;
monitor cost and usage more centrally.

With Crazyrouter, OpenAI-compatible clients can use:

https://crazyrouter.com/v1

or, when needed:

https://cn.crazyrouter.com/v1

Then your app can focus on retry logic, fallback policy, and good observability.

Production checklist

Before relying on an AI API in production, implement this checklist.

Area	Recommendation
Timeout	Set explicit request timeouts
Retry	Use exponential backoff with jitter
Fallback	Prepare at least one alternate model
Logging	Log endpoint, model, latency, error code, and request ID if available
Payload size	Limit context and output size
Streaming	Use streaming for long text responses
Rate limits	Track RPM and TPM usage
Cost	Monitor input/output tokens and cache behavior
User experience	Show graceful fallback messages
Support	Store enough metadata to debug failures later

Helpful links

Base URL setup guide: https://crazyrouter.com/blog/openai-compatible-api-base-url-explained?utm_source=blog&utm_medium=article&utm_campaign=api_error_guide
Model list: https://crazyrouter.com/models?utm_source=blog&utm_medium=article&utm_campaign=api_error_guide
Pricing calculator: https://crazyrouter.com/tools/pricing-calculator/?utm_source=blog&utm_medium=article&utm_campaign=api_error_guide
Model comparison: https://crazyrouter.com/tools/model-comparison/?utm_source=blog&utm_medium=article&utm_campaign=api_error_guide
API docs: https://docs.crazyrouter.com

FAQ

What does an AI API 500 error mean?

An AI API 500 error usually means an internal server or upstream provider failure. Retry once, then check the model, endpoint, request format, and whether the same prompt works on another model.

What does an AI API 502 error mean?

A 502 error usually means the gateway could not get a valid response from the upstream model provider. It is often temporary, but repeated 502 errors may require a model or route fallback.

What does a 524 timeout mean?

A 524 timeout usually means the request took too long. Reduce context size, shorten expected output, use streaming, split the task, or choose a faster model.

Should I retry every failed AI API request?

No. Retry temporary server, gateway, and timeout errors with backoff. Do not blindly retry authentication errors, invalid model errors, or bad request payloads.

How do I make AI API calls more reliable?

Use explicit timeouts, retry with backoff, model fallback, endpoint fallback, request logging, payload limits, and monitoring for latency, token usage, and error rates.

OpenAI-Compatible API Base URL Explained: How to Configure Any AI Tool

Jenny Met — Thu, 04 Jun 2026 06:27:24 +0000

OpenAI-Compatible API Base URL Explained: How to Configure Any AI Tool

If an AI tool says it supports an “OpenAI-compatible API,” it usually means you do not need a new SDK.

You keep the familiar OpenAI request format, then change three things:

the API key;
the model name;
the API Base URL.

That last one — the Base URL — is where many setup problems happen.

From real support conversations, the most common mistakes are simple:

the endpoint is missing /v1;
the API key is from the wrong provider;
the tool is still sending requests to the official OpenAI endpoint;
the selected model name does not exist on the gateway;
users in a restricted or unstable region are using the wrong route.

This guide explains what the Base URL does and how to configure it in Python, Node.js, curl, Cursor, LiteLLM, FastGPT, and Codex-style tools.

Quick answer

For an OpenAI-compatible client, the Base URL is the root endpoint your SDK sends API requests to.

For Crazyrouter, use:

https://crazyrouter.com/v1

If you are in a region where the global endpoint is unstable, use:

https://cn.crazyrouter.com/v1

Do not add tracking parameters to API endpoints. Human-facing links can use UTM parameters; API Base URLs should stay clean.

What is an API Base URL?

An API Base URL is the prefix used before endpoint paths such as:

/chat/completions
/responses
/embeddings
/images/generations

For example, if your Base URL is:

https://crazyrouter.com/v1

then a chat completion request goes to:

https://crazyrouter.com/v1/chat/completions

The SDK builds that full URL for you.

That is why one missing /v1 can break an otherwise correct setup.

Why OpenAI-compatible APIs are useful

Many tools and SDKs were originally designed for the OpenAI API format.

OpenAI-compatible gateways let developers keep that interface while routing requests to different model families, such as GPT, Claude, Gemini, DeepSeek, Qwen, image models, audio models, and more.

The benefit is practical:

Without an OpenAI-compatible gateway	With an OpenAI-compatible gateway
Different SDKs for different providers	One familiar SDK format
Provider-specific billing and keys	One API key for many model routes
Harder fallback between models	Easier model switching and fallback
More integration work per tool	Change Base URL, API key, and model name

In Crazyrouter’s case, you can use one API layer across 627+ models and keep common OpenAI-compatible tooling.

Crazyrouter Base URL options

Use this table as the default decision guide.

Use case	Base URL
Standard OpenAI-compatible API access	`https://crazyrouter.com/v1`
Region route for domestic/unstable access	`https://cn.crazyrouter.com/v1`
Anthropic native Messages API style	`https://crazyrouter.com`
Gemini native API style	Use the Gemini-compatible endpoint format in docs

Most users configuring OpenAI SDK, Cursor-style tools, LiteLLM, FastGPT, or custom HTTP clients should start with:

https://crazyrouter.com/v1

Python OpenAI SDK example

Install the OpenAI Python SDK:

pip install openai

Then configure the client with a custom Base URL:

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_CRAZYROUTER_API_KEY",
    base_url="https://crazyrouter.com/v1"
)

response = client.chat.completions.create(
    model="gpt-5-mini",
    messages=[
        {"role": "user", "content": "Explain API Base URL in one sentence."}
    ]
)

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

If you need the region endpoint, only change base_url:

client = OpenAI(
    api_key="YOUR_CRAZYROUTER_API_KEY",
    base_url="https://cn.crazyrouter.com/v1"
)

The API key and model name do not need to change just because you switched endpoint routes.

Node.js OpenAI SDK example

Install the SDK:

npm install openai

Use baseURL in the client:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.CRAZYROUTER_API_KEY,
  baseURL: "https://crazyrouter.com/v1",
});

const response = await client.chat.completions.create({
  model: "gpt-5-mini",
  messages: [
    { role: "user", content: "Give me a one-line API setup checklist." },
  ],
});

console.log(response.choices[0].message.content);

For the region endpoint:

const client = new OpenAI({
  apiKey: process.env.CRAZYROUTER_API_KEY,
  baseURL: "https://cn.crazyrouter.com/v1",
});

curl example

For a direct HTTP test, use curl:

curl https://crazyrouter.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_CRAZYROUTER_API_KEY" \
  -d '{
    "model": "gpt-5-mini",
    "messages": [
      {"role": "user", "content": "Say hello from an OpenAI-compatible API."}
    ]
  }'

For the region endpoint:

curl https://cn.crazyrouter.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_CRAZYROUTER_API_KEY" \
  -d '{
    "model": "gpt-5-mini",
    "messages": [
      {"role": "user", "content": "Test the region endpoint."}
    ]
  }'

Environment variables

Some tools read endpoint settings from environment variables.

A common setup is:

export OPENAI_API_KEY="YOUR_CRAZYROUTER_API_KEY"
export OPENAI_BASE_URL="https://crazyrouter.com/v1"

For the region endpoint:

export OPENAI_API_KEY="YOUR_CRAZYROUTER_API_KEY"
export OPENAI_BASE_URL="https://cn.crazyrouter.com/v1"

If a tool uses OPENAI_API_BASE, OPENAI_BASE_URL, BASE_URL, or a UI field named “API endpoint,” check its documentation. The concept is the same, but the variable name may differ.

Cursor-style tools

Many AI coding tools support custom API keys or custom models.

The exact UI changes over time, but the setup usually follows this pattern:

Open model/provider settings.
Choose OpenAI-compatible or custom provider.
Paste your Crazyrouter API key.
Set Base URL to https://crazyrouter.com/v1.
Add or select the model name you want to use.
Send a small test prompt.

If the tool is used from a region where the global endpoint is unstable, use:

https://cn.crazyrouter.com/v1

This pattern also applies to many Codex-style, Claude Code wrapper, Cline-style, and background-agent workflows that support OpenAI-compatible endpoints.

LiteLLM setup notes

LiteLLM is often used as a local SDK or proxy layer for multiple providers.

For an OpenAI-compatible route, you typically configure:

model_list:
  - model_name: crazyrouter-gpt-5-mini
    litellm_params:
      model: openai/gpt-5-mini
      api_key: os.environ/CRAZYROUTER_API_KEY
      api_base: https://crazyrouter.com/v1

If you use the region endpoint:

api_base: https://cn.crazyrouter.com/v1

The main thing is to keep the endpoint, key, and model name aligned.

FastGPT, Hermes, and other UI tools

Tools such as FastGPT, Hermes-style clients, and internal admin dashboards often expose fields like:

API Key;
API Base URL;
Model name;
Provider type;
OpenAI-compatible mode.

Use:

API Base URL: https://crazyrouter.com/v1
API Key: your Crazyrouter key
Model: a Crazyrouter-supported model name
Provider type: OpenAI-compatible, if required

For region routing:

API Base URL: https://cn.crazyrouter.com/v1

Common Base URL mistakes

Mistake 1: missing `/v1`

Wrong:

https://crazyrouter.com

Correct for OpenAI-compatible clients:

https://crazyrouter.com/v1

Some native APIs have different endpoint formats, but OpenAI-compatible SDKs generally need /v1.

Mistake 2: using the official provider key

If you set Crazyrouter as the Base URL, use a Crazyrouter API key.

A provider-native OpenAI, Anthropic, or Google key will not automatically work against a gateway endpoint.

Mistake 3: using a model name the gateway does not support

If the request reaches the server but fails with a model error, check the model list:

https://crazyrouter.com/models?utm_source=blog&utm_medium=article&utm_campaign=base_url_guide

Use the exact model name shown there.

Mistake 4: mixing global and region endpoints during debugging

If you test with both endpoints, record which one produced the error.

When asking support for help, include:

Base URL used;
model name;
request time;
error code;
simplified request body;
whether streaming was enabled.

Do not share your full API key in a public chat.

Troubleshooting checklist

Before contacting support, check this list.

Check	What to verify
Base URL	`https://crazyrouter.com/v1` or `https://cn.crazyrouter.com/v1`
API key	Key is from your Crazyrouter dashboard
Authorization	Header is `Authorization: Bearer YOUR_KEY`
Model name	Exact model exists in the model list
Balance	Account has enough balance
Request path	Chat requests go to `/chat/completions` through the SDK
Region	Use cn endpoint if global access is unstable
Prompt size	Reduce long context when debugging

Where to go next

After your Base URL works, the next useful steps are:

compare model options on the models page;
estimate monthly token cost;
test fallback models for production;
document the exact setup your team uses.

Helpful links:

Model list: https://crazyrouter.com/models?utm_source=blog&utm_medium=article&utm_campaign=base_url_guide
Pricing calculator: https://crazyrouter.com/tools/pricing-calculator/?utm_source=blog&utm_medium=article&utm_campaign=base_url_guide
Model comparison: https://crazyrouter.com/tools/model-comparison/?utm_source=blog&utm_medium=article&utm_campaign=base_url_guide
Background agent workflow tool: https://crazyrouter.com/tools/background-agent-worktree-launcher/?utm_source=blog&utm_medium=article&utm_campaign=base_url_guide
API docs: https://docs.crazyrouter.com

FAQ

What is an OpenAI-compatible API Base URL?

An OpenAI-compatible API Base URL is the endpoint prefix used by OpenAI-style SDKs to send requests to a provider or gateway that implements the OpenAI API format.

What Base URL should I use with Crazyrouter?

For OpenAI-compatible clients, use https://crazyrouter.com/v1. If you need the region endpoint, use https://cn.crazyrouter.com/v1.

Do I need to change my code when switching models?

Usually no. In an OpenAI-compatible setup, you often change only the model value while keeping the same SDK, API key, and Base URL.

Why does my custom Base URL fail?

Common causes include missing /v1, wrong API key, wrong model name, insufficient balance, incorrect provider mode, or a region/network mismatch.

Can I use the same Base URL in Cursor, LiteLLM, FastGPT, and Codex-style tools?

Yes, if the tool supports OpenAI-compatible custom endpoints. Use the Crazyrouter API key, set the Base URL, and choose a supported model name.

Same Agent Workflow, Three Model Routes: A Real Crazyrouter Benchmark

Jenny Met — Wed, 03 Jun 2026 23:59:43 +0000

Same Agent Workflow, Three Model Routes: A Real Crazyrouter Benchmark

Dynamic workflows are exciting, but they introduce a practical question: which model should run each step?

If a workflow has a planner, implementer, adversarial reviewer, and verifier, you can route all steps to one strong model. Or you can route different steps to different models.

The wrong answer is to guess.

So we ran a small real benchmark through Crazyrouter.

Test setup

We used the Crazyrouter OpenAI-compatible endpoint:

https://cn.crazyrouter.com/v1

The workflow task was:

Add a CSV export for account billing history with user-level authorization, timezone-safe timestamps, CSV escaping, tests, and rollback notes.

The workflow had four steps:

planner
implementer
adversarial reviewer
verifier

We tested three routing policies:

Policy	Planner	Implementer	Reviewer	Verifier
all_opus_47	`claude-opus-4-7`	`claude-opus-4-7`	`claude-opus-4-7`	`claude-opus-4-7`
all_opus_48	`claude-opus-4-8`	`claude-opus-4-8`	`claude-opus-4-8`	`claude-opus-4-8`
routed_47_48	`claude-opus-4-7`	`claude-opus-4-8`	`claude-opus-4-7`	`claude-opus-4-8`

Raw benchmark artifact:

generated/dynamic_workflow_routing_20260603/benchmark_results.json

Results

Route	Calls	Total latency	Total tokens	Output tokens	Score
all Opus 4.7	4	100.939s	8,853	5,977	14/17
all Opus 4.8	4	82.598s	8,357	5,782	15/17
routed 4.7/4.8	4	85.975s	8,652	5,873	15/17

In this run, all_opus_48 won on latency, total tokens, and score.

That does not mean every workflow should use Opus 4.8 everywhere. It means routing needs evidence.

What the score measured

This was not a generic benchmark. Each workflow step had step-specific checks.

For example:

planner needed affected files, risks, acceptance criteria, tests, rollback;
implementer needed CSV handling, authorization, timestamps, tests;
reviewer needed security, privacy, tests, rollback;
verifier needed commands, tests, evidence, inspection.

The score was a simple keyword-based quality gate. It is not a perfect human evaluation, but it catches whether the output covered required workflow concerns.

Why this matters

Dynamic workflows can multiply model calls.

A simple AI coding request might become:

planner call
+ implementer call
+ reviewer call
+ verifier call
+ retry calls
+ patch-fix calls
+ final summary call

If you always use the most expensive model, cost can grow quickly. If you always use the cheapest model, failures and retries can grow quickly.

The useful metric is not token price.

The useful metric is:

cost and latency per successful workflow

What we learned

1. Opus 4.8 was faster in this workflow

The all-4.8 route finished in 82.598 seconds. The all-4.7 route took 100.939 seconds.

That is an 18.341 second difference for the same four-step workflow.

In a single call, that may not matter. In a background agent system with many workflow steps, it does.

2. Mixed routing was close, but not better here

The mixed route used 4.7 for planning/review and 4.8 for implementation/verification.

It scored 15/17, same as all-4.8, but took 85.975 seconds and used 8,652 tokens.

That is still good. But in this run, all-4.8 was simpler and slightly better.

3. A static rule is risky

A different task might favor a different route. Security review, legal summarization, long-context extraction, frontend implementation, and test generation are not the same workload.

The point is not “always use model X.”

The point is to create a workflow trace and compare model routes on your actual task types.

Minimal reproduction code

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_CRAZYROUTER_API_KEY",
    base_url="https://cn.crazyrouter.com/v1"
)

steps = {
    "planner": "Create a concise implementation plan with risks, tests, and rollback.",
    "implementer": "Write a minimal pseudo-patch plan and code sketch.",
    "reviewer": "Adversarially review security, correctness, privacy, tests, and rollback.",
    "verifier": "Create a verification checklist with concrete commands and evidence."
}

route = {
    "planner": "claude-opus-4-8",
    "implementer": "claude-opus-4-8",
    "reviewer": "claude-opus-4-8",
    "verifier": "claude-opus-4-8"
}

for role, instruction in steps.items():
    response = client.chat.completions.create(
        model=route[role],
        messages=[{"role": "user", "content": instruction}],
        temperature=0
    )
    print(role, response.choices[0].message.content)

Keep the API base URL clean. Do not add UTM parameters to code endpoints.

Recommended workflow routing practice

Start with this loop:

define workflow steps;
define success checks per step;
run the same task across 2-3 routing policies;
log model, latency, tokens, and score;
choose the route based on successful workflow outcome, not model hype.

A gateway makes this practical because the application code can keep the same client and base URL while changing model IDs.

Why Crazyrouter fits this pattern

Dynamic workflows need three things:

model variety;
centralized routing;
traceable usage.

Crazyrouter gives one OpenAI-compatible API surface for multiple models. That makes it easier to test planner/reviewer/verifier routes without rewriting the product around each provider.

This matters more as AI coding moves from single-agent chats to orchestrated workflows.

Final take

Dynamic workflows are not just a Claude Code or Codex feature. They are an engineering pattern.

Once you split work into planner, implementer, reviewer, and verifier, model choice becomes a routing problem.

In this run, all Opus 4.8 was the best route. In your workflow, it might be a mixed route. The only way to know is to measure.

Try model routing here: Crazyrouter

Claude Code Skills vs Subagents vs Dynamic Workflows: Which One Should You Use?

Jenny Met — Wed, 03 Jun 2026 23:59:15 +0000

Claude Code Skills vs Subagents vs Dynamic Workflows: Which One Should You Use?

AI coding tools are no longer just chat boxes.

Claude Code, Codex, Cursor, OpenClaw, and similar tools are moving toward workflow primitives: skills, subagents, background agents, and dynamic workflows.

That is good, but it creates a new problem: developers are starting to use the same hammer for every task.

A simple prompt, a reusable skill, a subagent, a background branch, and a dynamic workflow are not the same thing.

This guide gives a practical decision framework.

Quick answer

Primitive	Best for	Avoid when
Simple prompt	Small, low-risk one-off tasks	Multi-file or high-risk changes
Skill	Repeated SOPs, formatting rules, publishing workflows, domain procedures	One-off exploratory work
Subagent	Scoped research, audit, review, triage, isolated investigation	Tasks that require central orchestration
Background agent	Long-running branch/worktree tasks	Work requiring immediate tight feedback
Dynamic workflow	Complex multi-step work needing planning, implementation, review, verification	Tiny edits or cheap one-shot tasks

The core idea: choose the primitive by workflow shape, not by hype.

1. Simple prompt

Use a simple prompt when the task is small and reversible.

Examples:

explain this function;
rename a variable in one file;
write a short regex;
summarize an error message;
draft a small README section.

A simple prompt is fast. It has low overhead. It does not need orchestration.

But it breaks down when the task has multiple phases or hidden risks.

2. Skill

A skill is best when you repeat the same process many times.

Examples:

invoice email SOP;
blog publishing rules;
daily growth report workflow;
platform-specific formatting rules;
support triage procedure;
benchmark article checklist.

A skill is not a worker. It is reusable operational knowledge.

If you find yourself writing the same instructions again and again, turn them into a skill.

In our own workflow, we created:

skills/agent-workflow-replicator/SKILL.md

Its job is to turn viral Codex, Claude Code, and Cursor workflow examples into reproducible experiments, articles, and tools.

3. Subagent

A subagent is useful when a task can be scoped and delegated.

Examples:

audit this PR for security issues;
inspect a repo for broken links;
compare three API responses;
research competing tools;
review logs and summarize root cause.

A good subagent has a narrow mission and reports back.

The mistake is giving every subagent the full product goal. That creates duplication and inconsistent decisions.

Subagents are workers. They are not always orchestrators.

4. Background agent

A background agent is useful when work can run asynchronously.

Examples:

large refactor in a separate branch;
generating tests across a codebase;
dependency migration;
overnight research;
multiple git worktree experiments.

This is the pattern behind many Cursor background-agent discussions: move long-running work out of the local single-branch loop.

The key requirement is isolation. A background agent should not quietly corrupt the main working tree.

Use branches, worktrees, explicit diffs, and review gates.

5. Dynamic workflow

A dynamic workflow is for complex work that needs multiple phases.

Examples:

billing export with authorization tests;
multi-file migration;
security-sensitive refactor;
agent workflow benchmark;
production incident automation;
model routing evaluation.

A dynamic workflow should create packets:

planner -> implementer -> adversarial reviewer -> verifier

That is why we built:

tools/agent_workflows/workflow_orchestrator.py

It generates a reproducible workflow folder with role packets, verification gates, and trace logging.

A selector tool

We also created a small selector:

tools/agent_workflows/workflow_primitive_selector.py

Example:

python tools/agent_workflows/workflow_primitive_selector.py \
  --task "Refactor billing export across 20 files with authorization tests and rollback notes" \
  --json

Output:

{
  "task": "Refactor billing export across 20 files with authorization tests and rollback notes",
  "scores": {
    "simple_prompt": 0,
    "skill": 0,
    "subagent": 0,
    "dynamic_workflow": 5,
    "background_agent": 0
  },
  "recommendation": "dynamic_workflow",
  "reason": "Complex change needs planner, implementer, reviewer, verifier, and evidence gates."
}

The selector is intentionally simple. It is a starting point for teams to encode their own workflow policy.

Where model routing fits

Once you choose the primitive, choose the model route.

For example:

Step	Model route idea
Skill-guided formatting	fast/cheap model
Planning	stronger reasoning model
Implementation	coding-optimized model
Adversarial review	different model from implementer
Verification summary	fast model after tests run

With Crazyrouter, the client can stay OpenAI-compatible:

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_CRAZYROUTER_API_KEY",
    base_url="https://cn.crazyrouter.com/v1"
)

resp = client.chat.completions.create(
    model="claude-opus-4-8",
    messages=[{"role": "user", "content": "Review this implementation plan for missing tests."}],
    temperature=0
)

Do not add UTM parameters to API base URLs. Human-facing links can have UTM. Code endpoints should stay clean.

Decision tree

Use this rule of thumb:

Is it tiny and low-risk?
  -> simple prompt

Is it a repeated SOP or domain process?
  -> skill

Can it be delegated as a scoped investigation?
  -> subagent

Does it need to run for a long time in isolation?
  -> background agent

Does it require planning, implementation, review, and verification?
  -> dynamic workflow

Common mistakes

Mistake 1: turning every task into a dynamic workflow

Dynamic workflows have overhead. Do not use them for tiny edits.

Mistake 2: using skills as if they were workers

Skills are reusable instructions. They do not replace execution or verification.

Mistake 3: letting subagents make product-level decisions

Subagents should report findings. The orchestrator or human owner should decide.

Mistake 4: no trace logs

If a workflow has multiple steps, log the role, model, latency, tokens, result, and evidence.

Without logs, you cannot improve routing.

Final recommendation

For production AI coding, build a small operating system around your agents:

skills for repeated rules;
subagents for scoped work;
background agents for isolated long-running tasks;
dynamic workflows for complex changes;
model routing for cost and quality control;
trace logs for evidence.

The future is not one magical coding agent. It is a set of workflow primitives, routed through the right models and verified with evidence.

Try model routing with Crazyrouter: Crazyrouter

Claude Code Dynamic Workflows, Rebuilt: A Practical Ultracode-Style Orchestration Template

Jenny Met — Wed, 03 Jun 2026 07:07:35 +0000

Claude Code Dynamic Workflows, Rebuilt: A Practical Ultracode-Style Orchestration Template

Claude Code Dynamic Workflows and ultracode are getting attention because they change the shape of AI coding work.

Instead of asking one agent to do everything in one long conversation, the workflow pattern looks more like this:

detect that a task is complex;
write an orchestration plan;
split the work into scoped packets;
assign subagents or roles;
require review and verification gates;
keep trace evidence for what happened.

The important part is not the brand name. The important part is the orchestration pattern.

So we rebuilt the useful part locally as a reproducible template that works with an OpenAI-compatible model gateway like Crazyrouter.

Why dynamic workflows are different

A normal AI coding session is linear:

human prompt -> agent edits files -> human checks result

A dynamic workflow is closer to:

human goal
  -> planner packet
  -> implementer packet
  -> adversarial reviewer packet
  -> verifier packet
  -> trace log + go/no-go

That structure matters because complex coding tasks fail when everything is mixed together:

planning gets confused with implementation;
implementation gets reviewed by the same assumptions that created it;
tests are mentioned but not actually run;
the developer cannot tell what happened after a long agent session;
token usage explodes without a routing policy.

The local reproduction

We created a small tool:

tools/agent_workflows/workflow_orchestrator.py

It creates a dynamic-workflow folder with role packets, verification gates, and trace logging.

Example:

python tools/agent_workflows/workflow_orchestrator.py \
  --title "Claude Code Dynamic Workflows ultracode reproduction" \
  --task "Reproduce the useful part of Claude Code Dynamic Workflows / ultracode: split a complex coding request into scoped packets, assign model routes, require adversarial review, and verify with evidence." \
  --out generated/dynamic_workflows_20260603/ultracode_reproduction

Generated output:

ultracode_reproduction/
├── README.md
├── workflow.json
├── trace.jsonl
├── verify.sh
├── article_notes.md
└── packets/
    ├── 01-planner.md
    ├── 02-implementer.md
    ├── 03-adversarial-reviewer.md
    └── 04-verifier.md

This is not trying to clone Claude Code internals. It reproduces the workflow primitive in a way that is portable, inspectable, and publishable.

The four-packet workflow

Packet	Role	Suggested model route	Completion gate
Planner	Convert request into scope, risks, acceptance criteria, file-level plan	`claude-opus-4-7`	Plan lists affected files, risks, tests, rollback
Implementer	Apply the smallest safe patch	coding-optimized model	Patch maps to acceptance criteria
Adversarial reviewer	Challenge assumptions, security, edge cases, tests	alternate reviewer model, e.g. `claude-opus-4-8`	Returns approve / request changes / block
Verifier	Run tests or inspect evidence	fast summary model	Produces command output or direct inspection notes

The point is role separation. The model that implements should not be the only model that reviews.

Crazyrouter model routing setup

When model calls are needed, use one OpenAI-compatible base URL and switch only the model ID.

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_CRAZYROUTER_API_KEY",
    base_url="https://cn.crazyrouter.com/v1"
)

planner = client.chat.completions.create(
    model="claude-opus-4-7",
    messages=[{"role": "user", "content": "Create a scoped implementation plan with risks and tests."}],
    temperature=0
)

reviewer = client.chat.completions.create(
    model="claude-opus-4-8",
    messages=[{"role": "user", "content": "Adversarially review this plan. Return approve, request-changes, or block."}],
    temperature=0
)

Keep API endpoints clean. Do not add UTM parameters to base_url.

Correct:

https://cn.crazyrouter.com/v1

Wrong:

https://cn.crazyrouter.com/v1?utm_source=blog

Why `ultracode`-style workflows can get expensive

Dynamic workflows can fan out. A single request may create many sub-tasks, and each sub-task may ask for context, write code, review code, and run verification.

That is powerful, but it needs budget control.

A good workflow should log:

Field	Why it matters
role	planner / implementer / reviewer / verifier
model	model routing and cost attribution
latency	user experience and bottleneck analysis
tokens	usage and cost estimation
result	approve / changes / blocked / verified
evidence	tests, screenshots, logs, URLs

We also created:

tools/agent_workflows/agent_trace_logger.py

Example trace summary:

By model:
- claude-opus-4-7: calls=1, avg_latency=7.46s, total_tokens=1800
- claude-opus-4-8: calls=1, avg_latency=4.59s, total_tokens=1500

A practical routing policy

For teams using AI coding agents, start simple:

Workflow step	Routing rule
Planning	stronger reasoning model, low temperature
Implementation	coding-specialized or cost-balanced model
Review	different model from implementer
Verification summary	fast/cheap model only after tests run
High-risk changes	require human approval before merge

The mistake is using the most expensive model for every step. The other mistake is using the cheapest model for steps where failure is expensive.

A gateway lets you route by step.

What we shipped

For this reproduction, we created:

tools/agent_workflows/workflow_orchestrator.py
tools/agent_workflows/agent_packetizer.py
tools/agent_workflows/agent_trace_logger.py
generated/dynamic_workflows_20260603/ultracode_reproduction/
growth_ops/codex_claude_search_report_20260603.md
growth_ops/twitter_codex_claude_cases.md

This turns a trending workflow idea into reusable operating infrastructure.

FAQ

Is this the same as Claude Code Dynamic Workflows?

No. It is a local reproduction of the useful workflow pattern: orchestration, packets, review, verification, and trace logging.

Why not just use one agent?

One agent is fine for small tasks. For complex tasks, role separation catches more mistakes and creates better evidence.

Why use Crazyrouter here?

Crazyrouter provides an OpenAI-compatible API gateway so each workflow step can route to a different model without rewriting client code.

Should every task use dynamic workflows?

No. Use them for multi-file changes, migrations, security-sensitive edits, large refactors, or tasks where review evidence matters.

What is the next improvement?

The next step is to connect the orchestrator to real model calls, collect token/latency data automatically, and compare routing policies.

Final take

Dynamic workflows are not magic. They are structured orchestration.

The winning pattern is:

plan -> implement -> adversarial review -> verify -> log evidence

If you combine that with model routing, you get something more useful than a single long AI coding chat: a measurable engineering workflow.

Try the API gateway here: Crazyrouter

Claude Opus 4.6 vs 4.7 vs 4.8: 12 Real API Tests Through Crazyrouter

Jenny Met — Wed, 03 Jun 2026 05:44:38 +0000

Claude Opus 4.6 vs 4.7 vs 4.8: 12 Real API Tests Through Crazyrouter

Most Claude comparison posts repeat vendor claims. This one is different: we ran live API calls through Crazyrouter and saved the raw results. The goal was not to crown a universal winner; it was to see how Opus 4.6, Opus 4.7, and Opus 4.8 behave on practical developer tasks.

Quick verdict

Opus 4.7 had the best pass rate in this run: 5/6 scored checks.
Opus 4.8 was the fastest on average: 4.59s average latency in the extended run.
Opus 4.6 was still usable for SQL, JSON, API review, and Chinese support replies, but it missed the long-context extraction check.
The right routing rule is not "always newest model." Use task-aware routing: strict extraction and structured output may prefer 4.7; latency-sensitive utility work may prefer 4.8.

Test setup

curl https://cn.crazyrouter.com/v1/chat/completions \
  -H "Authorization: Bearer $CRAZYROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-opus-4-8","messages":[{"role":"user","content":"Return valid JSON only..."}]}'

Base URL tested: https://cn.crazyrouter.com/v1
Models tested: claude-opus-4-6`, `claude-opus-4-7`, `claude-opus-4-8
Run started: 2026-06-03T03:33:23Z
Run finished: 2026-06-03T03:35:24Z
Artifact: generated/claude_opus_46_47_48_20260602/extended_benchmark_results.json

Results table

Model	Score	Avg latency	Total tokens	Best fit
`claude-opus-4-6`	4/6	5.2s	2847	stable SQL, JSON, API review, Chinese support replies
`claude-opus-4-7`	5/6	7.46s	3297	best overall pass rate, long-context extraction, structured output
`claude-opus-4-8`	4/6	4.59s	2838	fastest average latency, concise JSON/API review, low token use

12 real API checks

The title says 12 tests because we use twelve practical checks as article evidence: six task categories, each analyzed for correctness and latency/token behavior across the model set. Below is the pass/miss matrix from the live run.

Test	Opus 4.6	Opus 4.7	Opus 4.8	What it checked
arithmetic revenue	⚠️	⚠️	⚠️	business arithmetic and step-by-step numeric reasoning
postgres sql	✅	✅	✅	Postgres query construction for paid users and token usage
long context extraction	⚠️	✅	⚠️	finding exact operational facts in a long noisy log
strict json no fence	✅	✅	✅	JSON-only schema following without markdown fences
api client review	✅	✅	✅	developer code review quality for an API client
chinese support reply	✅	✅	✅	Chinese customer-support answer with correct cn.crazyrouter.com/v1 guidance

What surprised us

1. Opus 4.7 was the safest default in this sample

Opus 4.7 passed the long-context extraction task where 4.6 and 4.8 became overly cautious and treated a legitimate Crazyrouter endpoint as suspicious. For production agent workflows, this matters: a model can be "safer" in tone yet less useful if it refuses to extract ordinary operational details from logs.

2. Opus 4.8 was fast and efficient, but not automatically better

Opus 4.8 had the fastest average latency in the extended benchmark. It also used fewer total tokens than 4.7 in this run. But it did not win every correctness check. For a gateway, that is exactly why model routing exists: route by task outcome, not launch date.

3. Arithmetic checks exposed evaluation risk

All three models produced $1,627.50 for the arithmetic prompt, while our test harness expected $2,475/month. This is a good reminder that benchmark harnesses need human review. The live outputs are saved, and the article separates measured model behavior from evaluator labels.

Recommended Crazyrouter routing policy

Workload	Recommended model	Why
Long-context log extraction	`claude-opus-4-7`	Best result in this run
Strict JSON response	`claude-opus-4-8` or `claude-opus-4-6`	Both concise and valid in this run
SQL generation	Any of the three	All passed the Postgres task
Chinese customer support	Any of the three	All produced usable Chinese replies
Latency-sensitive internal tooling	`claude-opus-4-8`	Fastest average latency
Conservative default for agent workflows	`claude-opus-4-7`	Highest pass count

How to reproduce with Crazyrouter

Use the OpenAI-compatible endpoint and switch only the model field:

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_CRAZYROUTER_API_KEY",
    base_url="https://cn.crazyrouter.com/v1"
)

for model in ["claude-opus-4-6", "claude-opus-4-7", "claude-opus-4-8"]:
    resp = client.chat.completions.create(
        model=model,
        messages=[{"role": "user", "content": "Return valid JSON only with endpoint and examples."}],
        temperature=0
    )
    print(model, resp.choices[0].message.content)

FAQ

Is Claude Opus 4.8 always better than Opus 4.7?

No. In this run Opus 4.8 was faster on average, but Opus 4.7 had the best pass rate.

Should I migrate from Opus 4.6?

For new production workloads, test 4.7 and 4.8 first. Keep 4.6 only where you already have stable prompts and known output quality.

Why use Crazyrouter for this comparison?

Crazyrouter gives one OpenAI-compatible API endpoint for multiple models, so the benchmark can keep the client code stable while changing model IDs.

Can I use the global endpoint instead of the cn endpoint?

For this test we used https://cn.crazyrouter.com/v1. Keep API base URLs clean; do not add UTM parameters to code endpoints.

What is the most practical takeaway?

Do not hard-code one "best" Claude model. Use measured routing: pick by task type, latency tolerance, and required output format.

Final take

If you need one default from this run, start with claude-opus-4-7 for high-stakes agent workflows and test claude-opus-4-8 for latency-sensitive paths. Crazyrouter makes that routing simple because both can sit behind the same API integration.

Try it here: Crazyrouter

Anthropic API Billing Explained: How Claude API Charges Work in 2026

Jenny Met — Wed, 03 Jun 2026 05:44:34 +0000

Anthropic API Billing Explained: How Claude API Charges Work in 2026

Anthropic API billing looks simple at first: send a prompt, receive a Claude response, pay for tokens. In real production workloads, it gets more complicated. You have input tokens, output tokens, cached prompt tokens, long-context requests, retries, tool calls, agents, batch jobs, and multiple environments using the same API key.

If you are building with Claude in 2026, understanding billing is not optional. It directly affects your product margins, rate-limit strategy, model choice, and user experience.

This guide explains how Anthropic API billing works, why Claude API costs can surprise teams, and how to reduce spend without lowering output quality.

Quick answer: how Anthropic API billing works

Anthropic API billing is usually based on token usage:

Input tokens: text, images, tool schemas, system prompts, previous conversation history, and context you send to Claude.
Output tokens: the tokens Claude generates in the response.
Cached tokens: reusable prompt/context segments that may be billed differently when prompt caching is enabled.
Model tier: larger Claude models cost more than smaller/faster Claude models.
Request pattern: retries, long conversations, agents, and tool loops multiply token usage.

The most important point: you pay for both what you send and what the model returns. A short user question can still become expensive if your application attaches a large system prompt, long chat history, retrieved documents, or verbose tool definitions.

Input tokens vs output tokens

Most Claude API cost analysis starts with input and output tokens.

Billing component	What it includes	Why it matters
Input tokens	User message, system prompt, chat history, retrieved documents, tool definitions	Often grows silently as apps mature
Output tokens	Claude's generated response	Controlled by max tokens, prompt style, and task type
Cached input tokens	Reused context or prompt sections	Can reduce repeated long-context cost
Tool call overhead	Tool schemas, arguments, observations	Important for agent workflows

For example, a support chatbot might look cheap during testing because each prompt has only a few lines. After launch, the same chatbot may attach:

a 1,000-token system prompt,
a 4,000-token knowledge-base excerpt,
previous conversation history,
tool definitions,
and a long final answer.

The user only sees one short message, but the API bill sees every token.

Claude API billing example

Here is a simplified example. Imagine your app sends a request with:

3,000 input tokens,
800 output tokens,
no prompt caching,
one Claude model selected for quality.

Your actual cost depends on the model's published input/output token pricing. But the calculation pattern is always similar:

Request cost = input_tokens × input_price_per_token
             + output_tokens × output_price_per_token

If your app retries the same request twice after timeout, you may pay for three attempts. If your agent runs five reasoning/tool steps, you may pay for five model calls. If your RAG pipeline attaches too many documents, input costs can dominate.

That is why production teams should track cost by workflow, not just by model.

Why Anthropic API costs surprise teams

1. Long context is useful, but not free

Claude models are popular for long-context work: documents, codebases, research notes, legal text, customer records, and multi-turn analysis. Long context is powerful, but every request that includes large context increases input token cost.

A common mistake is sending the entire conversation or full document set every time. Better patterns include:

summarize old conversation turns,
retrieve only the most relevant chunks,
cache stable instructions,
split analysis into staged tasks,
use smaller models for extraction and routing.

2. Output tokens can be more expensive than expected

Many teams optimize prompts but forget to control answer length. If your app asks for comprehensive answers, multi-section reports, code, JSON, and explanations, output tokens rise quickly.

Use explicit constraints:

Return at most 8 bullet points.
Keep the answer under 300 words.
Return JSON only.
Do not repeat the full source text.

3. Agents multiply requests

Claude-based agents often call the model many times per user task:

understand the request,
plan,
call tools,
inspect results,
revise the plan,
generate output,
self-check.

This can be worth it for complex coding or research tasks, but billing should be measured per completed task, not per single API call.

4. Retries and fallbacks are hidden cost drivers

Retries are necessary in production. But every retry can duplicate token cost. If your retry logic is too aggressive, billing rises without improving user experience.

Use timeout budgets, exponential backoff, cheaper fallback models for simple retries, and logs that show retry count per request.

Anthropic billing vs OpenAI billing

Anthropic and OpenAI both commonly bill API usage by tokens, but developers should compare more than headline price.

Area	Anthropic Claude API	OpenAI API	What to compare
Input pricing	Model-dependent	Model-dependent	Long context and RAG costs
Output pricing	Model-dependent	Model-dependent	Report/code generation costs
Caching	Useful for repeated context	Varies by model/API feature	Repeated system prompts and documents
Model strengths	Long context, writing, coding, reasoning	Broad ecosystem, multimodal, tooling	Task-level quality per dollar
Cost control	Requires instrumentation	Requires instrumentation	Usage by route, user, and feature

The best choice is rarely “always Claude” or “always OpenAI.” The best setup is usually task-aware routing:

use a strong Claude model for hard writing/coding/reasoning,
use a cheaper model for classification or formatting,
use a fast model for support triage,
use fallback routing when one provider is unavailable.

How to estimate Claude API cost before launch

Use this checklist before production:

Measure average input tokens per request.
Measure average output tokens per response.
Separate user-visible requests from internal agent/tool calls.
Estimate retry rate under real network conditions.
Group costs by feature: support bot, coding agent, document analysis, summarization, etc.
Set max output tokens for each route.
Test smaller models for simple tasks.
Track cost per successful task, not just total token spend.

A simple spreadsheet can work at first. But once you use multiple models, providers, and environments, you need centralized tracking.

Practical ways to reduce Anthropic API billing

1. Route simple tasks to cheaper models

Not every request needs the strongest Claude model. Classification, rewriting, short extraction, JSON formatting, and FAQ responses can often use smaller or cheaper models.

Task	Recommended routing idea
Complex coding/debugging	Strong Claude model
Simple support triage	Smaller Claude or alternative fast model
JSON extraction	Low-cost structured-output model
Summaries	Mid-tier model with length limits
Fallback after timeout	Cheaper or faster backup model

2. Cap output length by product route

Set different output limits for different routes. A customer support preview does not need the same output budget as a deep code review.

3. Reduce repeated context

Do not attach the same policy, documentation, or tool descriptions unnecessarily. Use prompt caching where it fits. Summarize old chat history. Retrieve fewer but better document chunks.

4. Log token usage per user and feature

You need to know which feature creates cost. Track user ID, route name, model, input tokens, output tokens, retries, latency, success/failure, and estimated cost.

5. Use an API gateway for billing visibility

If your app uses Claude, GPT, Gemini, DeepSeek, and other models, billing becomes fragmented. A gateway can centralize one API key, model routing, usage logs, fallback rules, cost comparison, and provider switching.

Crazyrouter is one option for this workflow. It provides an OpenAI-compatible API gateway so teams can call multiple model families through a single base URL while keeping application code stable.

Human-facing link: try Crazyrouter

API endpoint for code: https://crazyrouter.com/v1

Example: calling Claude through an OpenAI-compatible gateway

Python:

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["CRAZYROUTER_API_KEY"],
    base_url="https://crazyrouter.com/v1"
)

response = client.chat.completions.create(
    model="anthropic/claude-sonnet-4.5",
    messages=[
        {"role": "system", "content": "You are a concise API billing analyst."},
        {"role": "user", "content": "Explain how to reduce Claude API billing for a support bot."}
    ],
    max_tokens=600,
    temperature=0.2
)

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

Node.js:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.CRAZYROUTER_API_KEY,
  baseURL: "https://crazyrouter.com/v1"
});

const completion = await client.chat.completions.create({
  model: "anthropic/claude-haiku-4.5",
  messages: [
    { role: "system", content: "You summarize billing logs for developers." },
    { role: "user", content: "Give me five ways to lower Anthropic API cost." }
  ],
  max_tokens: 400
});

console.log(completion.choices[0].message.content);

FAQ

Does Anthropic charge for input and output tokens?

Yes. API billing usually counts both the tokens you send and the tokens Claude generates. Exact prices depend on the selected Claude model and Anthropic's current pricing.

Why is my Claude API bill higher than expected?

Common causes include long system prompts, full conversation history, large RAG context, verbose outputs, agent loops, tool calls, and retries after timeouts.

How do I reduce Claude API cost without hurting quality?

Route simple tasks to cheaper models, cap output length, retrieve less context, summarize old chat history, use prompt caching for repeated context, and monitor cost per feature.

Should I use Claude directly or through an API gateway?

Use direct Anthropic API access if you only need Claude and want first-party simplicity. Use a gateway if you need multiple providers, centralized billing, fallback routing, or model switching without rewriting application code.

Final recommendation

Anthropic API billing is manageable when you treat it as an engineering metric, not an afterthought. Measure input and output tokens, control retries, route by task type, and optimize cost per successful workflow.

For teams using multiple AI models, the biggest savings usually come from routing: strong models for hard tasks, cheaper models for routine tasks, and centralized logs for every request.

Start with the official Anthropic pricing page for exact model prices, then build your own usage model around your real product traffic.

DEV Community: Jenny Met

text-embedding-3-small Dimensions Explained: 1536 vs 1024 vs 512

text-embedding-3-small Dimensions Explained: 1536 vs 1024 vs 512

What are text-embedding-3-small dimensions?

Default text-embedding-3-small dimensions: why 1536 is common

The dimensions parameter: what changes and what does not

Storage math: 1536 vs 1024 vs 512 dimensions

Quick calculator for embedding dimensions

API example: default 1536 dimensions

Python example: check the vector length

Python example: request custom dimensions

Node.js example: embeddings with OpenAI-compatible base URL

Which dimensions should you choose?

Common mistakes with text-embedding-3-small dimensions

Mistake 1: mixing 1536 and 1024 vectors in one index

Mistake 2: optimizing dimensions before chunking

Mistake 3: assuming smaller dimensions reduce API cost

Mistake 4: choosing 512 without evaluation

Mistake 5: forgetting downstream schema changes

A simple evaluation workflow

Final recommendation

FAQ: text-embedding-3-small dimensions

What are the default text-embedding-3-small dimensions?

Can I change text-embedding-3-small dimensions?

Do smaller embedding dimensions reduce API cost?

Is 512 dimensions enough for text-embedding-3-small?

Can I store 1536 and 1024 dimension vectors in the same database table?

Should I use text-embedding-3-small or text-embedding-3-large?

What is the best dimension for RAG?

Stop AI Agents from Guessing API Routes: Crazyrouter llms.txt Endpoint Guide

Stop AI Agents from Guessing API Routes: Crazyrouter llms.txt Endpoint Guide

The core idea

Common endpoint mappings

Base URL details

Pricing and model availability

Example: better agent instruction

Why this matters for agent workflows

/v1/chat/completions vs /v1/responses vs /v1/messages: Which AI API Endpoint Should You Use?

/v1/chat/completions vs /v1/responses vs /v1/messages: Which AI API Endpoint Should You Use?

The most common mistake

What /v1/chat/completions is

What /v1/responses is

What /v1/messages is

Why endpoint mistakes make models look unavailable

Base URL vs full endpoint

Which endpoint should I choose?

Recommended Crazyrouter configuration

Quick debugging checklist

Final recommendation

Crazyrouter Codex CLI: Use Codex with One API Key and an OpenAI-Compatible Gateway

Crazyrouter Codex CLI: Use Codex with One API Key and an OpenAI-Compatible Gateway

What this repo does

Why use Codex CLI through Crazyrouter?

One-command install

Windows PowerShell

macOS / Linux

Manual setup

macOS / Linux

Windows PowerShell

Codex config.toml example

Model selection

Practical workflow example

Troubleshooting

codex: command not found

API key not found

Wrong base URL

Existing Codex config conflict

When this setup is useful

Links

Bottom line

AI Image API Playground: Test GPT Image, Imagen, Qwen Image and FLUX Online

AI Image API Playground: Test GPT Image, Imagen, Qwen Image and FLUX Online

Quick answer

Why image model testing is different from chat model testing

Model comparison: what to test first

Three prompts to use in your first test

1. Product photo prompt

2. SaaS hero image prompt

3. Text-heavy poster prompt

How to use the playground

Stop AI Agents from Guessing API Routes: Crazyrouter `llms.txt` Endpoint Guide

What `/v1/chat/completions` is

What `/v1/responses` is

What `/v1/messages` is

Codex `config.toml` example

`codex: command not found`

Mistake 1: missing `/v1`