Developer Documentation

Get from zero to generating images and chat completions in under 5 minutes.

Quickstart

Get your API key

Make your first request

ArkRoute uses the OpenAI-compatible format. If you've used OpenAI's image API, you already know how to use ArkRoute.

Choose from 35 models

Switch between models by changing one parameter. Same endpoint, same auth, different results. Browse all models →

curl

curl -X POST https://api.ark-route.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "a cat astronaut floating in space, photorealistic",
    "n": 1,
    "size": "1024x1024"
  }'

💡

OpenAI SDK compatible! Just change the base URL to https://api.ark-route.com and it works with the official OpenAI Python/JS SDKs.

Python (OpenAI SDK)

python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.ark-route.com/v1"
)

response = client.images.generate(
    model="seedream-4.5",
    prompt="a serene japanese garden at sunset",
    n=1,
    size="1024x1024"
)

print(response.data[0].url)

JavaScript (OpenAI SDK)

javascript

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.ark-route.com/v1'
});

const response = await client.images.generate({
  model: 'gpt-image-2',
  prompt: 'a minimalist logo for a coffee brand',
  n: 1,
  size: '1024x1024'
});

console.log(response.data[0].url);

Chat Completions NEW

ArkRoute now supports chat completions powered by GPT-5.5 and other OpenAI models via subscription proxy. Same OpenAI-compatible format.

curl

curl -X POST https://api.ark-route.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [{"role": "user", "content": "Hello!"}],
    "max_tokens": 100
  }'

Python Chat Example

python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.ark-route.com/v1"
)

response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Explain quantum computing in one sentence"}],
    max_tokens=100
)

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

🧠

Available chat models: gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5.3-codex, gpt-5.2, codex-auto-review. Credits: 1-5 per request.

Authentication

All API requests require a Bearer token in the Authorization header:

header

Authorization: Bearer YOUR_API_KEY

🔑

Get your API key from the Dashboard. You can create multiple keys for different projects.

Available Models

ArkRoute routes to 35 models from 5 providers. Here are the most popular:

Model	Provider	Type	Credits	Best For
`nano-banana-2`	Google	Image	2	General purpose, fast
`seedream-4.5`	ByteDance	Image	3	Best Chinese AI, realistic
`gpt-image-2`	OpenAI	Image	50	Highest quality, text rendering
`gpt-image-1-mini`	OpenAI	Image	3	Fast OpenAI quality
`kling-v2-master`	Kuaishou	Video	50	Best video generation
`seedance-1.0`	ByteDance	Video	25	Dance/motion videos

View all 35 models →

Image Generation

Method	Endpoint	Description
POST	`/v1/images/generations`	Generate images from text

Request Body

Parameter	Type	Required	Description
`model`	string	Yes	Model ID (e.g., "nano-banana-2")
`prompt`	string	Yes	Text description of the image
`n`	integer	No	Number of images (default: 1)
`size`	string	No	"1024x1024", "1024x1536", "1536x1024"
`image`	string	No	Base64 reference image (for image-to-image)
`response_format`	string	No	"url" (default) or "b64_json"

Response

{ "created": 1714000000, "data": [ { "url": "https://storage.googleapis.com/...", "revised_prompt": "a cat astronaut..." } ] }

Video Generation

Method	Endpoint	Description
POST	`/v1/video/generations`	Generate video from text/image

Request Body

Parameter	Type	Required	Description
`model`	string	Yes	"kling-v2-master", "seedance-1.0", etc.
`prompt`	string	Yes	Motion description
`image`	string	No	Base64 first frame (image-to-video)
`duration`	number	No	Video length in seconds (5 or 10)
`aspect_ratio`	string	No	"16:9", "9:16", "1:1"

⏱️

Video generation is async. The response returns a task_id. Poll /v1/video/status/{task_id} until status is "completed".

Response

{ "task_id": "abc123-def456", "status": "processing", "model": "kling-v2-master" }

Video Status

Method	Endpoint	Description
GET	`/v1/video/status/{task_id}`	Check video generation progress

Response (completed)

{ "task_id": "abc123-def456", "status": "completed", "video_url": "https://storage.googleapis.com/...", "duration": 5.0, "model": "kling-v2-master" }

List Models

Method	Endpoint	Description
GET	`/v1/models`	List all available models

No authentication required. Returns model IDs, providers, types, and pricing.

SDKs & Libraries

Two ways to use ArkRoute — pick whichever fits your stack:

Option 1 — Official ArkRoute SDK (Python)

Install our thin Python SDK for typed helpers around image, video, and chat endpoints:

install

pip install arkroute

python

from arkroute import ArkRoute

client = ArkRoute(api_key="ark-...")
result = client.images.generate(
    model="seedream-5.0-lite",
    prompt="A linen dress on a Moroccan rooftop, golden hour",
)
print(result["data"][0]["url"])

Live on PyPI: pypi.org/project/arkroute

Option 2 — OpenAI SDK drop-in (one-line change)

ArkRoute is OpenAI-compatible. If you already use the OpenAI SDK, just point base_url at us — no rewrite:

install

# Python
pip install openai

# JavaScript/TypeScript
npm install openai

# Just change the base_url to https://api.ark-route.com/v1

🔌

MCP Support: ArkRoute also supports the Model Context Protocol. Point your MCP client to https://api.ark-route.com/mcp for tool-based image generation. Learn more →

Error Handling

Code	Meaning	What to do
`401`	Invalid API key	Check your Authorization header
`402`	Insufficient credits	Buy more credits
`422`	Invalid parameters	Check request body format
`429`	Rate limited	Wait and retry with exponential backoff
`500`	Provider error	Retry or try a different model

Rate Limits

Current limits per API key:

Image generation: 60 requests/minute
Video generation: 10 requests/minute
List models: 120 requests/minute

Need higher limits? Contact us for enterprise plans.

MCP Integration

API Explorer ✨

Test the API right here. Enter your API key, pick a model, and generate — no setup required.

🔑

Your API key is stored locally in your browser and never sent to our servers (only to api.ark-route.com directly).

API Key

Model

Prompt

Size

Credits

~2 credits

ArkRoute supports the Model Context Protocol (MCP) for tool-based AI agents:

json

{
  "mcpServers": {
    "arkroute": {
      "url": "https://api.ark-route.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

This exposes generate_image and generate_video tools to any MCP-compatible AI agent (Claude, GPT, etc.).