API Documentation · V1

AI API 接入文档

先选择你要接入的功能：文本与对话可继续使用 OpenAI、Claude 或 Gemini SDK；图片和视频使用异步任务 API。Quick Start 会为当前可用模型准备 Key 和对应请求。

Base URL: https://newrouters.com
API Key: 仅保存在服务端

更新 2026-08-27 · 模型和参数可能变化，请以实时模型接口为准。

复制后粘贴给编程助手；它会根据你的用途选择接口，并核对当前可用模型和参数。

先选用途

你想调用哪一类 API？

选择与你现有项目或生成目标一致的一项；不需要同时学习四种接口。

文本与对话我正在使用 OpenAI SDK继续使用 Chat Completions 或 Responses。POST /v1/chat/completions文本与对话我正在使用 Claude SDK继续使用 Messages API。POST /v1/messages文本与对话我正在使用 Gemini SDK继续使用 GenerateContent。POST ...:generateContent图片与视频我要生成图片或视频创建异步任务，再查询生成结果。POST /v1/tasks

三步快速开始

快速开始

选择模型，打开 Quick Start 获取 Key，再运行对应示例。你不需要读完整页才能发出第一条请求。

KEY

1. 获取 API Key

注册后会自动创建首个 Key。打开 Quick Start 即可复制 Key 和请求代码。将 MODEL_API_KEY 保存为服务端环境变量，避免写入客户端代码或公开仓库。获取 API Key →

API_BASE=https://newrouters.com
MODEL_API_KEY=sk_••••••••

GET

2. 选择当前可用模型

文本与对话模型从 GET /v1/models 选择；图片与视频模型从 GET /v1/media-models 选择。复制接口返回的 model 字段，不要凭记忆填写模型 ID。

GET /v1/models

文本与对话模型 ID 及兼容协议

GET /v1/media-models

图片与视频模型 ID、输入参数和价格

cURL

curl --fail-with-body "https://newrouters.com/v1/models"
curl --fail-with-body "https://newrouters.com/v1/media-models"

JavaScript

const [llmResponse, mediaResponse] = await Promise.all([
  fetch('https://newrouters.com/v1/models'),
  fetch('https://newrouters.com/v1/media-models')
]);

if (!llmResponse.ok) throw new Error(await llmResponse.text());
if (!mediaResponse.ok) throw new Error(await mediaResponse.text());
const llmModels = await llmResponse.json();
const mediaModels = await mediaResponse.json();
console.log({ llmModels, mediaModels });

Python

import requests

llm_response = requests.get("https://newrouters.com/v1/models", timeout=30)
media_response = requests.get("https://newrouters.com/v1/media-models", timeout=30)
llm_response.raise_for_status()
media_response.raise_for_status()
llm_models = llm_response.json()
media_models = media_response.json()
print({"llm_models": llm_models, "media_models": media_models})

使用可视化模型目录选择 →

3. 运行与你用途对应的示例

文本与对话选择一个兼容协议；图片与视频创建任务并查询结果。

文本与对话选择 OpenAI、Claude 或 Gemini 图片与视频创建异步任务并获取结果

文本与对话 API

继续使用你熟悉的 SDK 和请求格式

在 OpenAI、Claude 或 Gemini 接入中配置本站 Base URL 和 API Key，再选择该协议下当前可用的模型。请求体、流式响应、Usage 和错误结构保持对应协议格式。

OpenAIPOST /v1/chat/completions↓ClaudePOST /v1/messages↓GeminiPOST /v1beta/models/{model}:generateContent↓

选择现有项目使用的协议，设置对应的模型环境变量，再复制一条完整的非流式请求。

OpenAI · JSON / SSE

OpenAI Chat Completions

使用 Bearer 鉴权。下面以 Chat Completions 作为第一条请求；Responses 使用同一 Key 与 Base URL，并保留原生请求体。

鉴权: Authorization: Bearer $MODEL_API_KEY
模型环境变量: OPENAI_MODEL_ID

已支持端点

POST /v1/chat/completions
POST /v1/responses
GET /v1/models

cURL

# Bash
curl --request POST "https://newrouters.com/v1/chat/completions" \
  --header "Authorization: Bearer $MODEL_API_KEY" \
  --header "Content-Type: application/json" \
  --data @- <<JSON
{
  "model": "$OPENAI_MODEL_ID",
  "messages": [{"role": "user", "content": "Explain idempotent Webhook handling in three steps."}],
  "max_tokens": 512
}
JSON

JavaScript

const response = await fetch('https://newrouters.com/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MODEL_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: process.env.OPENAI_MODEL_ID,
    messages: [{ role: 'user', content: 'Explain idempotent Webhook handling in three steps.' }],
    max_tokens: 512
  })
});

if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

Python

import os
import requests

response = requests.post(
    "https://newrouters.com/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['MODEL_API_KEY']}"},
    json={
        "model": os.environ["OPENAI_MODEL_ID"],
        "messages": [{"role": "user", "content": "Explain idempotent Webhook handling in three steps."}],
        "max_tokens": 512,
    },
    timeout=60,
)
response.raise_for_status()
print(response.json())

Claude · JSON / SSE

Claude Messages

使用 x-api-key 和 anthropic-version。Token 计数和带鉴权的模型发现使用同一个账号 Key。

鉴权: x-api-key: $MODEL_API_KEY
模型环境变量: CLAUDE_MODEL_ID

已支持端点

GET /v1/models
POST /v1/messages
POST /v1/messages/count_tokens

cURL

# Bash
curl --request POST "https://newrouters.com/v1/messages" \
  --header "x-api-key: $MODEL_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "Content-Type: application/json" \
  --data @- <<JSON
{
  "model": "$CLAUDE_MODEL_ID",
  "max_tokens": 512,
  "messages": [{"role": "user", "content": "Explain idempotent Webhook handling in three steps."}]
}
JSON

JavaScript

const response = await fetch('https://newrouters.com/v1/messages', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.MODEL_API_KEY,
    'anthropic-version': '2023-06-01',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: process.env.CLAUDE_MODEL_ID,
    max_tokens: 512,
    messages: [{ role: 'user', content: 'Explain idempotent Webhook handling in three steps.' }]
  })
});

if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

Python

import os
import requests

response = requests.post(
    "https://newrouters.com/v1/messages",
    headers={
        "x-api-key": os.environ["MODEL_API_KEY"],
        "anthropic-version": "2023-06-01",
    },
    json={
        "model": os.environ["CLAUDE_MODEL_ID"],
        "max_tokens": 512,
        "messages": [{"role": "user", "content": "Explain idempotent Webhook handling in three steps."}],
    },
    timeout=60,
)
response.raise_for_status()
print(response.json())

Gemini · JSON / SSE

Gemini GenerateContent

使用 x-goog-api-key，并把所选 Gemini 模型 ID 放入原生请求路径。Interactions 使用独立的原生端点。

鉴权: x-goog-api-key: $MODEL_API_KEY
模型环境变量: GEMINI_MODEL_ID

已支持端点

POST /v1beta/models/{model}:generateContent
POST /v1beta/models/{model}:streamGenerateContent?alt=sse
POST /v1/interactions
POST /v1beta/interactions

cURL

curl --request POST "https://newrouters.com/v1beta/models/${GEMINI_MODEL_ID}:generateContent" \
  --header "x-goog-api-key: $MODEL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"contents":[{"role":"user","parts":[{"text":"Explain idempotent Webhook handling in three steps."}]}]}'

JavaScript

const path = '/v1beta/models/' + process.env.GEMINI_MODEL_ID + ':generateContent';
const response = await fetch('https://newrouters.com' + path, {
  method: 'POST',
  headers: {
    'x-goog-api-key': process.env.MODEL_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    contents: [{ role: 'user', parts: [{ text: 'Explain idempotent Webhook handling in three steps.' }] }]
  })
});

if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

Python

import os
import requests

model = os.environ["GEMINI_MODEL_ID"]
response = requests.post(
    f"https://newrouters.com/v1beta/models/{model}:generateContent",
    headers={"x-goog-api-key": os.environ["MODEL_API_KEY"]},
    json={
        "contents": [{
            "role": "user",
            "parts": [{"text": "Explain idempotent Webhook handling in three steps."}],
        }]
    },
    timeout=60,
)
response.raise_for_status()
print(response.json())

SSE

流式响应保持协议原生

OpenAI 与 Claude 在 JSON 请求体中传 stream: true；Gemini 使用带 alt=sse 的 streamGenerateContent，Interactions 则传 stream: true。

OpenAI · cURL

# Bash
curl "https://newrouters.com/v1/chat/completions" \
  -H "Authorization: Bearer $MODEL_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<JSON
{"model":"$OPENAI_MODEL_ID","messages":[{"role":"user","content":"Stream a short answer."}],"stream":true}
JSON

Claude · cURL

# Bash
curl "https://newrouters.com/v1/messages" \
  -H "x-api-key: $MODEL_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  --data @- <<JSON
{"model":"$CLAUDE_MODEL_ID","max_tokens":256,"messages":[{"role":"user","content":"Stream a short answer."}],"stream":true}
JSON

Gemini · cURL

# Bash
curl "https://newrouters.com/v1beta/models/${GEMINI_MODEL_ID}:streamGenerateContent?alt=sse" \
  --header "x-goog-api-key: $MODEL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"contents":[{"role":"user","parts":[{"text":"Stream a short answer."}]}]}'

读取原生 Usage 与错误

成功响应保留协议原生 Usage；失败请求返回 OpenAI、Claude 或 Gemini 原生错误结构，现有客户端可以继续按协议处理。

图片与视频 API

创建任务，然后查询生成结果

图片和视频请求不会立即返回最终文件。POST /v1/tasks 先返回任务 ID；持续查询该任务，成功后再读取结果文件 URL。

POST/v1/tasksHTTP 202

创建任务

请求包含模型 ID 和对应的 input。只有需要接收成功或失败通知时才填写 callback_url。每次 POST 都会创建并扣费一个新任务，因此结果不确定时不要自动重试创建请求。

创建任务可能产生费用

先用 GET /v1/media-models 核对模型、输入参数和当前价格。只有 POST /v1/tasks 会开始生成任务。

cURL

# Bash
curl --request POST "https://newrouters.com/v1/tasks" \
  --header "Authorization: Bearer $MODEL_API_KEY" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "model": "gpt-image-2",
  "input": {
    "prompt": "A cobalt-blue mechanical bird on a white plinth, clean product photography",
    "aspect_ratio": "1:1",
    "resolution": "1k",
    "quality": "low",
    "output_format": "png"
  }
}
JSON

JavaScript

const response = await fetch('https://newrouters.com/v1/tasks', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MODEL_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "model": "gpt-image-2",
  "input": {
    "prompt": "A cobalt-blue mechanical bird on a white plinth, clean product photography",
    "aspect_ratio": "1:1",
    "resolution": "1k",
    "quality": "low",
    "output_format": "png"
  }
})
});

if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

Python

import os
import requests

response = requests.post(
    "https://newrouters.com/v1/tasks",
    headers={"Authorization": f"Bearer {os.environ['MODEL_API_KEY']}"},
    json={
  "model": "gpt-image-2",
  "input": {
    "prompt": "A cobalt-blue mechanical bird on a white plinth, clean product photography",
    "aspect_ratio": "1:1",
    "resolution": "1k",
    "quality": "low",
    "output_format": "png"
  }
},
    timeout=60,
)
response.raise_for_status()
print(response.json())

字段	必填	说明
`model`	是	来自已启用媒体目录的公开模型 ID。
`input`	是	模型专属输入对象；未知字段会被拒绝。
`callback_url`	否	可选的公网 HTTP(S) 地址；任务成功或失败后会收到通知。不得包含凭据，也不得使用 localhost、私网或保留地址。

创建请求不支持安全自动重试

每次调用 POST /v1/tasks 都可能创建并扣费一个新任务。GET 查询可以退避重试。

任务响应结构 · HTTP 202（数值仅为示意）

{
  "id": "task_01M19Q7KDPY0KSK6PQ3W2X9M7A",
  "status": "pending",
  "type": "image",
  "model": "gpt-image-2",
  "request": {
    "prompt": "A cobalt-blue mechanical bird on a white plinth, clean product photography",
    "aspect_ratio": "1:1",
    "resolution": "1k",
    "quality": "low",
    "output_format": "png"
  },
  "result": null,
  "error": null,
  "estimated_points": "2.00",
  "charged_points": "2.00",
  "refunded_points": "0.00",
  "created_at": "2026-08-26T08:00:00.000Z",
  "started_at": null,
  "updated_at": "2026-08-26T08:00:00.000Z",
  "completed_at": null
}

GET/v1/tasks/{task_id}HTTP 200

查询到最终状态为止

仅在 pending 或 processing 时继续轮询；进入 succeeded 或 failed 后立即停止，也可以使用 Webhook 代替持续轮询。

cURL

curl "https://newrouters.com/v1/tasks/$TASK_ID" \
  --header "Authorization: Bearer $MODEL_API_KEY"

JavaScript

const response = await fetch(
  'https://newrouters.com/v1/tasks/' + process.env.TASK_ID,
  { headers: { Authorization: `Bearer ${process.env.MODEL_API_KEY}` } }
);

if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

Python

import os
import requests

response = requests.get(
    f"https://newrouters.com/v1/tasks/{os.environ['TASK_ID']}",
    headers={"Authorization": f"Bearer {os.environ['MODEL_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
print(response.json())

pending

等待调度

processing

正在生成

succeeded

读取 result.assets

failed

读取 error.code 与 error.message

成功任务 · HTTP 200

{
  "id": "task_01M19Q7KDPY0KSK6PQ3W2X9M7A",
  "status": "succeeded",
  "type": "image",
  "model": "gpt-image-2",
  "request": {
    "prompt": "A cobalt-blue mechanical bird on a white plinth, clean product photography",
    "aspect_ratio": "1:1",
    "resolution": "1k",
    "quality": "low",
    "output_format": "png"
  },
  "result": {
    "assets": [
      "https://cdn.example.com/tasks/task_01M19Q7KDPY0KSK6PQ3W2X9M7A/outputs/0.png"
    ]
  },
  "error": null,
  "estimated_points": "2.00",
  "charged_points": "2.00",
  "refunded_points": "0.00",
  "created_at": "2026-08-26T08:00:00.000Z",
  "started_at": "2026-08-26T08:00:02.000Z",
  "updated_at": "2026-08-26T08:00:28.000Z",
  "completed_at": "2026-08-26T08:00:28.000Z"
}

失败任务 · HTTP 200

{
  "id": "task_01M19Q7KDPY0KSK6PQ3W2X9M7A",
  "status": "failed",
  "type": "image",
  "model": "gpt-image-2",
  "request": {
    "prompt": "A cobalt-blue mechanical bird on a white plinth, clean product photography",
    "aspect_ratio": "1:1",
    "resolution": "1k",
    "quality": "low",
    "output_format": "png"
  },
  "result": null,
  "error": {
    "code": "model_error",
    "message": "The model could not complete the task."
  },
  "estimated_points": "2.00",
  "charged_points": "0.00",
  "refunded_points": "2.00",
  "created_at": "2026-08-26T08:00:00.000Z",
  "started_at": "2026-08-26T08:00:02.000Z",
  "updated_at": "2026-08-26T08:00:16.000Z",
  "completed_at": "2026-08-26T08:00:16.000Z"
}

响应 request 与保留期

response.request 是应用默认值后的模型 input，不是完整创建外层。图片处理上限 5 分钟，视频 30 分钟；结果文件默认保留 7 天，过期后任务仍保留但 result.assets 可能为空。

GET /v1/tasks?status=failed&failure_reason=content_filtered&limit=20

查询和筛选任务列表

GET /v1/tasks 支持游标分页，以及 status、failure_reason、type、model、task_id 和时间范围筛选；limit 为 1–100，默认 20。

任务完成通知

通过 Webhook 接收成功或失败通知

任务成功或失败后，平台向公网 HTTP(S) callback_url 发送一次无签名 JSON POST；凭据、localhost、私网/保留地址和重定向会被拒绝，投递超时为 10 秒；任意 2xx 响应都视为投递成功。

1×

仅自动投递一次

使用 event_id 去重。投递失败时直接查询任务；平台当前不会自动重试。

成功 Webhook

{
  "event_id": "evt_01M19R2W5PDCXE3QP05FHYG9VM",
  "event_type": "task.succeeded",
  "created_at": "2026-08-26T08:00:28.000Z",
  "data": {
    "task_id": "task_01M19Q7KDPY0KSK6PQ3W2X9M7A",
    "status": "succeeded"
  },
  "error": null
}

可信状态由于 Webhook 不签名，需要可信确认时，应使用 API Key 调用 GET /v1/tasks/{task_id}。

失败处理

区分任务失败与请求失败。

媒体任务被接受后仍可能执行失败，此时查询仍返回 HTTP 200；未被接受的请求会立即返回非 2xx。LLM 请求保持对应协议的原生错误结构。

HTTP 200

已接受媒体任务失败

从任务资源读取 status、error.code、error.message 和安全过滤后的 error.details。

HTTP 4xx / 5xx

媒体 HTTP 请求失败

读取顶层 error 对象；创建请求返回非 2xx 后不要开始任务轮询。

已接受媒体任务失败

{
  "id": "task_01M19Q7KDPY0KSK6PQ3W2X9M7A",
  "status": "failed",
  "type": "image",
  "model": "gpt-image-2",
  "request": {
    "prompt": "A cobalt-blue mechanical bird on a white plinth, clean product photography",
    "aspect_ratio": "1:1",
    "resolution": "1k",
    "quality": "low",
    "output_format": "png"
  },
  "result": null,
  "error": {
    "code": "model_error",
    "message": "The model could not complete the task."
  },
  "estimated_points": "2.00",
  "charged_points": "0.00",
  "refunded_points": "2.00",
  "created_at": "2026-08-26T08:00:00.000Z",
  "started_at": "2026-08-26T08:00:02.000Z",
  "updated_at": "2026-08-26T08:00:16.000Z",
  "completed_at": "2026-08-26T08:00:16.000Z"
}

媒体 HTTP 请求失败

{
  "error": {
    "code": "invalid_request",
    "message": "The task input is invalid.",
    "request_id": "req_01M19R8KQKBE6VFSR4Z4P8RZK6",
    "details": {}
  }
}

JSON

LLM 原生请求错误

成功响应保留协议原生 Usage；失败请求返回 OpenAI、Claude 或 Gemini 原生错误结构，现有客户端可以继续按协议处理。

OpenAI

{
  "error": {
    "message": "A valid API key is required.",
    "type": "authentication_error",
    "param": null,
    "code": "authentication_error"
  }
}

Claude

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "A valid API key is required."
  },
  "request_id": "req_01M19R8KQKBE6VFSR4Z4P8RZK6"
}

Gemini

{
  "error": {
    "code": 401,
    "message": "A valid API key is required.",
    "status": "UNAUTHENTICATED",
    "details": []
  }
}

↻

重试建议

策略和参数错误需要修改输入。媒体任务创建不具备幂等性：每次 POST 都可能创建并扣费一个新任务，结果不确定时不要自动重试；只读媒体请求可以退避重试。LLM 请求按所选 SDK 的重试规则处理。

账号

查询平台积分。

GET /v1/balance 使用 Bearer 鉴权，返回 API Key 所属账号的当前积分。该十进制字符串不包含在途任务占用积分。

GET/v1/balanceBearer API Key

cURL

curl "https://newrouters.com/v1/balance" \
  --header "Authorization: Bearer $MODEL_API_KEY"

JavaScript

const response = await fetch('https://newrouters.com/v1/balance', {
  headers: { Authorization: `Bearer ${process.env.MODEL_API_KEY}` }
});

if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

Python

import os
import requests

response = requests.get(
    "https://newrouters.com/v1/balance",
    headers={"Authorization": f"Bearer {os.environ['MODEL_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
print(response.json())

积分响应 · HTTP 200

{
  "points": "123.456789"
}

下一步

选择模型，然后复制对应示例

模型页用于比较模型并查看输入说明；实时模型接口用于确认模型是否可调用，以及读取当前参数和价格。

查看全部模型 →查看 LLM API 查看图片 API 查看视频 API