API Documentation

Learn how to integrate JinAI API into your applications

Quick Start

Get started with JinAI API in minutes. Our API is fully compatible with OpenAI's interface.

1

1. Get Your API Key

Sign in and generate your API key from the settings page.

2

2. Install SDK

Install the OpenAI SDK or use our compatible endpoints.

bash
pip install openai
3

3. Make Your First Request

Start making requests with your preferred model.

Authentication

All API requests require authentication using your API key.

API Key Header

Include your API key in the Authorization header:

http
Authorization: Bearer YOUR_API_KEY

Keep your API keys secure and never expose them in client-side code.

Chat Completions

Generate conversational responses using various AI models.

Endpoint

http
POST https://api.jinwangai.com/v1/chat/completions

Request Parameters

modelID of the model to use
messagesArray of message objects
temperatureSampling temperature (0-2)
max_tokensMaximum tokens to generate
streamEnable streaming responses

Example Request

typescript
import OpenAI from 'openai';

// OpenAI 风格 Base URL
const client = new OpenAI({
  baseURL: 'https://api.jinwangai.com/v1',
  apiKey: process.env.OPENLLM_API_KEY,
});

// OpenRouter 风格也同样支持:
// baseURL: '/v1'

const response = await client.chat.completions.create({
  model: 'gpt-4',
  messages: [
    { role: 'user', content: 'Hello!' }
  ],
});

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

Python Example Request

python
from openai import OpenAI

# OpenAI 风格 Base URL
client = OpenAI(
    base_url="https://api.jinwangai.com/v1",
    api_key="YOUR_API_KEY"
)

# OpenRouter 风格也同样支持:
# base_url="/v1"

response = client.chat.completions.create(
    model="gpt-4",
    messages=[
        {"role": "user", "content": "Hello!"}
    ]
)

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

Image Generation

Generate and edit images through the OpenAI-compatible /v1/images/* endpoints. Supported parameters vary by model — see the Quickstart tab on each model's detail page.

Endpoint

http
POST https://api.jinwangai.com/v1/images/generations
POST https://api.jinwangai.com/v1/images/edits

Common Parameters

modelImage model ID, e.g. seedream-5.0-pro
promptText description of the image (required)
sizeOutput size. Accepts explicit pixels like 1024x1024; some models also accept 1K / 2K resolution tiers
response_formaturl (default, link valid for 24h) or b64_json (Base64 image data)
output_formatOutput file format, e.g. png / jpeg

Text-to-Image Example

bash
curl https://api.jinwangai.com/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "seedream-5.0-pro",
    "prompt": "A serene mountain landscape at sunset, cinematic lighting",
    "size": "2K",
    "response_format": "url"
  }'

Response Example

json
{
  "model": "doubao-seedream-5-0-pro-260628",
  "created": 1785461717,
  "data": [
    {
      "url": "https://...",
      "size": "2048x2048",
      "output_format": "jpeg"
    }
  ],
  "usage": {
    "generated_images": 1,
    "input_images": 0,
    "output_tokens": 16384,
    "total_tokens": 16384
  }
}

Image Edits / Image-to-Image

Upload a reference image to edit or restyle it. Compatible with the OpenAI SDK's images.edit(). Repeat the image field for multi-image blending.

bash
# multipart 上传参考图 (兼容 OpenAI SDK 的 images.edit())
curl https://api.jinwangai.com/v1/images/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=seedream-5.0-pro" \
  -F "prompt=Replace the background with a snowy mountain" \
  -F "size=2K" \
  -F "image=@./photo.png"

Seedream-specific Parameters

BytePlus Seedream models accept these additional fields in the /v1/images/generations JSON body:

imageReference image: a single URL string, a data URI, or an array of URLs for multi-image blending (up to 10)
watermarkWhether to add an "AI generated" watermark. Upstream defaults to true — pass false explicitly if you don't want one
bash
# 图生图: image 传单个 URL 或 data URI
curl https://api.jinwangai.com/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "seedream-5.0-pro",
    "prompt": "Turn this into a watercolor painting",
    "image": "https://example.com/photo.png",
    "size": "2K",
    "watermark": false
  }'

# 多图融合: image 传数组 (最多 10 张)
curl https://api.jinwangai.com/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "seedream-5.0-pro",
    "prompt": "Replace the clothing in image 1 with the outfit from image 2",
    "image": [
      "https://example.com/person.png",
      "https://example.com/outfit.png"
    ],
    "size": "2K",
    "watermark": false
  }'

Note: Seedream does not support gpt-image-only parameters such as quality, style or output_compression. output_format accepts png / jpeg only (no webp). seedream-5.0-pro cannot generate multiple images per request (n > 1 returns an error).

Billing

Image models are billed per image; some are tiered by output resolution (Seedream, for example, prices ≤ 2.36M pixels and > 2.36M pixels differently), and reference images may be billed separately. See the Pricing tab on the model detail page for exact rates.

Prompt Caching & Billing

Some models (Anthropic Claude family and others) support prompt caching: cache a long system prompt, document, or conversation history, and subsequent requests that hit the cache are billed at a steep discount.

Pricing Tiers

Cache writes are priced by lifetime; cache hits are billed at a fraction of the input price. Multipliers relative to the base input price:

  • •5-minute cache write = input price × 1.25
  • •1-hour cache write = input price × 2
  • •Cache hit (read) = input price × 0.1

Example (Claude Fable 5, input $10/M)

text
维度                    单价          说明
输入 (未缓存)           $10 / MTok    基准价
输出                    $50 / MTok
缓存写入 (5 分钟)       $12.50 / MTok  = 输入 x 1.25
缓存写入 (1 小时)       $20 / MTok     = 输入 x 2
缓存命中 (读取)         $1 / MTok      = 输入 x 0.1

Usage Notes

Caching is not automatic — add an explicit cache_control marker to the request. Fields pass through unchanged on /v1/messages (native Anthropic format). Cached content has a minimum length (typically 1024+ tokens). On a hit, input_tokens counts only the uncached portion; the cached portion is reported separately as cache_read.

bash
curl https://api.jinwangai.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-fable-5",
    "max_tokens": 1024,
    "messages": [{
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "<很长的文档或系统提示，至少 1024 tokens>",
          "cache_control": {"type": "ephemeral"}
        },
        {"type": "text", "text": "根据上文回答我的问题。"}
      ]
    }]
  }'

How much it saves

For an 8,914-token context: the first request costs about $0.113 to write the cache, then each subsequent hit costs about $0.011 — roughly 90% savings. Multi-turn long-context conversations benefit most.

Available Models

Access hundreds of AI models through a single API.

List Models Endpoint

http
GET https://api.jinwangai.com/v1/models
Flagship Models

Latest and most capable models from major providers

Coding Specialist

Optimized for code generation and technical tasks

Reasoning Models

Advanced reasoning and complex problem-solving

Multimodal

Support for images, audio, and video inputs

Streaming Responses

Stream responses in real-time for better user experience.

Benefits of streaming:

  • Reduced perceived latency
  • Real-time feedback
  • Better UX for long responses

Implementation Example

typescript
const stream = await client.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Tell me a story' }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || '');
}

Anthropic Native API

JinAI fully supports Anthropic's native /v1/messages API format. You can use the official Anthropic SDK directly, with support for streaming and Prompt Cache.

Base URL

Set the Anthropic SDK's base_url to the following address, using your JinAI API Key:

http
Base URL: https://api.jinwangai.com

Python SDK

python
import anthropic

client = anthropic.Anthropic(
    base_url="https://api.jinwangai.com",
    api_key="YOUR_API_KEY",
)

message = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude!"}
    ]
)

print(message.content[0].text)

TypeScript SDK

typescript
import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  baseURL: 'https://api.jinwangai.com',
  apiKey: 'YOUR_API_KEY',
});

const message = await client.messages.create({
  model: 'claude-opus-4-6',
  max_tokens: 1024,
  messages: [
    { role: 'user', content: 'Hello, Claude!' }
  ],
});

console.log(message.content[0].text);

Streaming

Use the Anthropic SDK's stream method for streaming output:

python
with client.messages.stream(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Tell me a story"}]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Prompt Cache

Enable prompt caching with the cache_control parameter to reduce repeated token costs:

python
message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=[{
        "type": "text",
        "text": "You are a helpful assistant...(long system prompt)...",
        "cache_control": {"type": "ephemeral"}
    }],
    messages=[
        {"role": "user", "content": "Hello!"}
    ]
)

# Check cache usage
print(f"Cache read: {message.usage.cache_read_input_tokens}")
print(f"Cache creation: {message.usage.cache_creation_input_tokens}")

cURL Example

Call the API directly using HTTP:

bash
curl https://api.jinwangai.com/v1/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

Supported Models

The following Claude models are currently available via the native API format:

Claude Opus 4
claude-opus-4-6
Claude Sonnet 4
claude-sonnet-4-6
Claude Haiku 3.5
claude-haiku-4-5

Error Handling

Understand and handle API errors effectively.

Common Error Codes

  • 401401 Unauthorized - Invalid API key
  • 429429 Too Many Requests - Rate limit exceeded
  • 500500 Internal Server Error - Service error
  • 503503 Service Unavailable - Temporary outage

Best Practices

  • Implement exponential backoff for retries
  • Handle rate limits gracefully
  • Log errors for debugging

Pricing & Billing

Transparent pricing based on actual usage.

ModelInput PriceOutput Price
GPT-4$5.00$15.00
GPT-3.5 Turbo$0.50$1.50
Claude 3 Opus$15.00$75.00

per 1M tokens

Pay-as-you-go pricing with no subscription required.

Track your usage and costs in real-time from the dashboard.

SDKs & Libraries

Official and community-maintained SDKs for popular languages.

Official SDKs

Python

Use the official OpenAI Python library

pip install openai
Node.js / TypeScript

Use the official OpenAI Node.js library

npm install openai

Popular Frameworks

•
LangChain: LangChain integration for building AI applications
•
Vercel AI SDK: Vercel AI SDK for React and Next.js applications

Rate Limits

API usage limits to ensure fair access and service stability.

TierRequestsTokens
Free100 req/day100K tokens/day
Pro10,000 req/day10M tokens/day

Rate limit information is included in response headers:

http
X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9999
X-RateLimit-Reset: 1640995200

Support & Resources

Community

Join our Discord community for help and discussions

Email Support

Contact our team at support@jinwangai.com

Status Page

Check real-time API status and uptime

Changelog

Stay updated with latest features and improvements