DEVELOPER API

API 接入文档

通过 OpenAI 兼容接口接入对话、图片和视频模型。本文档中的模型列表与平台配置同步，生产调用请使用客户控制台创建的 API Key。

模型定价说明：Token、长上下文、缓存与分时价格 →

Base URL https://YOUR_PLATFORM_DOMAIN

快速开始

三步完成第一次对话请求。

1. 创建 API Key

登录客户控制台，在 API Keys 中创建并妥善保存密钥。

2. 设置客户端

Base URL 使用 https://YOUR_PLATFORM_DOMAIN/v1。

3. 发起请求

模型代码从本页实时模型列表或模型定价定价说明页获取。

Python · OpenAI SDK

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://YOUR_PLATFORM_DOMAIN/v1",
)

response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "你好"}],
)
print(response.choices[0].message.content)

客户端兼容

优先选择 OpenAI Chat Completions 协议。工具调用、多轮对话和流式输出均通过该端点工作。

客户端	配置方式	兼容状态
OpenAI SDK / 通用会话软件	Base URL: `https://YOUR_PLATFORM_DOMAIN/v1`	直接兼容
OpenClaw	Provider API 选择 `openai-completions`，Base URL 同上	直接兼容
WorkBuddy	使用自定义 OpenAI 兼容服务，Base URL 填 `https://YOUR_PLATFORM_DOMAIN/v1`；推荐优先配置 DeepSeek 系列模型，代码场景性价比较高	直接兼容
Claude / Anthropic SDK	Base URL: `https://YOUR_PLATFORM_DOMAIN`，使用 Messages API	兼容
Gemini SDK	使用 `/v1beta/models/{model}:generateContent`	文本生成兼容
Qoder	当前 Custom Models/BYOK 主要使用官方维护的服务商目录，未确认支持任意自定义 Base URL	暂不推荐

OpenClaw 配置片段

{
  "models": {
    "providers": {
      "lemonpie": {
        "baseUrl": "https://YOUR_PLATFORM_DOMAIN/v1",
        "apiKey": "YOUR_API_KEY",
        "api": "openai-completions",
        "models": [{"id": "gpt-5.5", "name": "gpt-5.5"}]
      }
    }
  }
}

认证方式

API Key 仅在创建时显示一次。不要把密钥放入网页前端、公开仓库或日志。

Authorization: Bearer YOUR_API_KEY

x-api-key: YOUR_API_KEY
anthropic-version: 2023-06-01

x-goog-api-key: YOUR_API_KEY

接口与示例

所有请求和响应均为 JSON；流式对话使用 Server-Sent Events。

POST/v1/chat/completionsOpenAI 兼容对话，支持 stream、tools 与 tool_choice

curl https://YOUR_PLATFORM_DOMAIN/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": true
  }'

POST/v1/messagesAnthropic Messages 兼容，支持多轮工具调用

tool_choice 支持 auto（自动）、any（必须调用工具）、tool（指定 name）和 none（禁止工具）。auto/any/tool 可设置布尔值 disable_parallel_tool_use，原样保留单工具约束；非法或未知选择字段返回 400。具体模型是否支持强制工具选择仍受上游能力限制；协议转换不会把 any、tool 或 none 自动降级为 auto。

当前是 Messages 兼容子集：尚不支持原生 thinking、output_config、context_management，以及历史 thinking/redacted_thinking 内容块。显式传入时，在调用和扣费前返回 400 invalid_request_error，不会丢弃配置后按普通对话执行。需要这些能力请使用支持完整原生语义的 Messages 服务；只有不需要该能力时才移除相关参数。普通文本、用户消息中已支持的图片输入和自定义函数工具多轮转换保持。top_k 原值转交支持的 Chat 通道；方舟当前 SDK 无此字段，显式传入会返回参数错误，不会静默丢弃。工具结果当前支持字符串或文本块数组（含空结果）；图片、文档和搜索结果等结构化工具结果会在调用前明确拒绝，不会转成占位文字。带版本类型的原生工具（如网页搜索、代码执行、计算机操作）不能当成普通函数，当前返回 400；需要这些能力请使用完整原生通路。

curl https://YOUR_PLATFORM_DOMAIN/v1/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-4.6-sonnet",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "你好"}]
  }'

POST/v1beta/models/{model}:generateContentGemini 文本生成；流式请求使用 streamGenerateContent

此入口当前支持文本 contents、systemInstruction，以及 temperature、topP、maxOutputTokens、stopSequences。原生工具调用、图片/文件输入、thinkingConfig、结构化输出等尚未支持；传入会明确返回 400，不会忽略参数后按普通文本调用。需要工具或多模态能力时，请使用支持该能力的模型与 OpenAI Chat Completions 接口。

curl https://YOUR_PLATFORM_DOMAIN/v1beta/models/gemini-3.1-pro:generateContent \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"role":"user","parts":[{"text":"你好"}]}]}'

POST/v1/images/generationsOpenAI 兼容图片生成；请求保持连接直至返回结果

适合 OpenAI SDK 和服务端调用。传 image_url 时按参考图生成，支持公网 URL 或 data:image/*;base64,...，请求仍为 JSON。

{
  "model": "gpt-image-2",
  "prompt": "现代产品摄影，柔和自然光",
  "n": 1,
  "size": "1024x1024",
  "response_format": "url"
}

{
  "model": "jimeng-t2i-3.0",
  "prompt": "转身，保持主体形象一致",
  "n": 1,
  "size": "1024x1024",
  "image_url": "data:image/png;base64,...."
}

GET/v1/models返回当前可用模型；建议应用启动时读取并缓存

异步图片与视频

生成时间较长时，先保存 task_uid，再轮询任务状态。用户关闭页面后仍可继续查询，状态为 DONE 时读取结果链接。

# 1. 提交
POST /v1/images/tasks
{"model":"jimeng-t2i-3.0","prompt":"转身","image_url":"data:image/png;base64,...."}

# 2. 查询
GET /v1/images/tasks/{task_uid}

# 完成响应
{"task_uid":"lc-task-...","status":"DONE","progress":100,
 "result_url":"https://...","response":{"data":[{"url":"https://..."}]}}

# 1. 提交
POST /v1/videos/generations
{"model":"veo-3.1-fast","prompt":"海边日落","duration":8}

# 2. 查询
GET /v1/videos/{task_uid}

# 完成响应
{"task_uid":"lc-task-...","status":"DONE","progress":100,
 "result_url":"https://..."}

时长不是任意值：Veo 3.1/fast 文生视频只支持 4、6、8 秒，图生视频单段固定 8 秒；即梦视频 3.0 的文生/图生/Pro 路由支持 3–12 秒整数；Seedance 2.0 支持 4–15 秒整数。Veo 图生 10 秒需要生成两个原生 8 秒片段再裁切，因此按 16 秒计费。图生视频建议直接传公网 image_url，不要下载后转 Base64；网关会在扣费前完成私有 OSS URL 与格式预检。

媒体健康不靠昂贵定时生成：平台只用真实图片/视频任务的终态更新被动健康，拿到非空结果链接才算成功；参考图格式、文件传输或内容策略错误不会把整条模型路由误判为宕机。GET /v1/models 表示当前已有启用路由，不代表一次新的付费端到端验收。

建议每 3 至 5 秒轮询一次；遇到 PENDING 或 PROCESSING 继续等待，遇到 FAILED 或 TIMEOUT 停止轮询并向用户显示错误信息。

可用模型

正在读取模型列表...

Prompt Cache

缓存是否命中由模型提供方根据重复前缀和请求条件决定。账单按实际 usage 记录计费。

什么时候需要设置缓存？

OpenAI、DeepSeek 和 Gemini 模型无需额外开关。Claude 仅在会重复使用较长且稳定的系统提示词、工具定义或文档前缀时，才建议按 Anthropic 请求格式添加 cache_control。普通短对话无需设置。

错误处理

根据 HTTP 状态码决定是否重试。响应中的 error.type 或对应协议错误字段可用于程序判断。

HTTP	含义	处理建议
`400`	请求参数无效	检查模型代码、必填字段和 JSON 格式
`401 / 403`	认证失败或无权限	检查 API Key、IP 白名单和模型权限
`402`	余额或额度不足	充值或调整消费额度
`429`	请求过快或并发已满	指数退避后重试，并降低并发
`500 / 502 / 503 / 504`	服务暂时不可用	指数退避，最多重试 2 至 3 次

在线调试

请求只发送到当前平台域名。已登录客户可直接选择数据库中的有效 Key，无需在浏览器保存明文。

Base URL

API Key

接口

Request Body

Response

等待发送请求