Developer Documentation
Get from zero to generating images in under 5 minutes.
Quickstart
Get your API key
Sign up at ark-route.com/dashboard and copy your API key. You get 500 free credits (~50 images) on signup.
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 28 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);Authentication
All API requests require a Bearer token in the Authorization header:
header
Authorization: Bearer YOUR_API_KEYGet your API key from the Dashboard. You can create multiple keys for different projects.
Available Models
ArkRoute routes to 28 models from 5 providers. Here are the most popular:
| Model | Provider | Type | Credits | Best For |
|---|---|---|---|---|
nano-banana-2 | 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 |
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
ArkRoute is OpenAI-compatible, so you can use any OpenAI SDK:
install
# Python
pip install openai
# JavaScript/TypeScript
npm install openai
# Just change the base_url to https://api.ark-route.com/v1MCP 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).~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.).