OCI AI对接文档

Base URL：https://ocitoken.com

1. 概述

本文档面向 API 调用方，说明如何通过本平台网关调用已接入的大模型服务。

本平台提供 OpenAI 兼容 的 HTTP API，统一鉴权、计费与路由。客户端可使用：

官方 OpenAI SDK（改 base_url 即可）
任意支持 OpenAI API 的框架（LangChain、Cursor、Continue 等）
直接 curl / fetch 调用

兼容性说明：接口格式与 OpenAI / Anthropic / Gemini 官方高度兼容，但并非 100% 等同官方；部分高级能力以上游渠道实际支持为准。

2. 快速开始

2.1 获取 API Key

登录控制台
进入 API Keys（令牌管理）
新建令牌，复制以 sk- 开头的密钥（仅显示一次，请妥善保存）

2.2 最小可用请求

curl https://ocitoken.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的令牌" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "user", "content": "你好"}
    ]
  }'

成功时返回 OpenAI 标准 chat.completion JSON。

3. 鉴权

所有 Relay API 请求必须携带令牌，支持以下方式（任选其一）：

方式	示例
Bearer（推荐）	Authorization: Bearer sk-xxxxxxxx
裸 sk 前缀	Authorization: sk-xxxxxxxx

Claude 原生接口（/v1/messages） additionally 支持：

x-api-key: sk-xxxxxxxx
anthropic-version: 2023-06-01

Gemini 原生接口（/v1beta/models/...） additionally 支持：

x-goog-api-key: sk-xxxxxxxx

或在 URL 查询参数中：?key=sk-xxxxxxxx

令牌限制

令牌可配置 IP 白名单、过期时间、可用模型、额度上限
额度不足或令牌无效时返回 401 或带 error 字段的 JSON

4. 可用模型

以下为当前平台已接入模型示例（以管理员后台实际配置为准，未列出的模型名可能返回 503 或 model_not_found）。如有自定义模型，可在控制台查看完整列表：

模型名	类型	推荐接口
gpt-4o	文本对话	POST /v1/chat/completions
deepseek-chat	文本对话	POST /v1/chat/completions
kimi-k3.1-pro	文本对话	POST /v1/chat/completions
gpt-image-2	文生图	POST /v1/images/generations
doubao-seedance-2.0	视频生成	POST /v1/video/generations
doubao-seedance-2.0-fast	视频生成	POST /v1/video/generations

查询模型列表：

curl https://ocitoken.com/v1/models \
  -H "Authorization: Bearer sk-你的令牌"

5. 文本对话（OpenAI 兼容）

端点：POST /v1/chat/completions

5.1 非流式

curl https://ocitoken.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的令牌" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "system", "content": "你是一个有帮助的助手。"},
      {"role": "user", "content": "用三句话介绍量子计算。"}
    ],
    "temperature": 0.7,
    "max_tokens": 1024
  }'

5.2 流式（SSE）

curl -N https://ocitoken.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的令牌" \
  -d '{
    "model": "deepseek-chat",
    "stream": true,
    "messages": [
      {"role": "user", "content": "写一首关于春天的短诗"}
    ]
  }'

响应为 text/event-stream，每行 data: {...}，结束时为 data: [DONE]。

5.3 Python（OpenAI SDK）

from openai import OpenAI

client = OpenAI(
    api_key="sk-你的令牌",
    base_url="https://ocitoken.com/v1",
)

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

流式：

stream = client.chat.completions.create(
    model="deepseek-chat",
    messages=[{"role": "user", "content": "Hello"}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

6. Claude 原生接口（可选）

若客户端使用 Anthropic SDK，可直连：

端点：POST /v1/messages

curl https://ocitoken.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk-你的令牌" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "解释一下 REST 和 GraphQL 的区别"}
    ]
  }'

7. 图像生成

7.1 gpt-image-2（OpenAI Images API）

端点：POST /v1/images/generations

注意：请使用 images 接口，不要用 chat/completions。

curl https://ocitoken.com/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的令牌" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只在窗台晒太阳的橘猫，水彩风格",
    "n": 1,
    "size": "1024x1024"
  }'

响应中 data[].url 或 data[].b64_json 为生成结果（取决于上游返回格式）。

7.2 Gemini 图像模型

Gemini 图像生成耗时较长，强烈建议使用流式。

方式 A：OpenAI Chat 格式（推荐，兼容性最好）

curl -N https://ocitoken.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的令牌" \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "stream": true,
    "messages": [
      {"role": "user", "content": "生成一张 1:1 的红色圆形图标，简约扁平风格"}
    ]
  }'

图像可能以 Markdown 内嵌 base64、或流式 chunk 中的结构化字段返回，请按客户端框架解析 content。

8. 视频生成

操作	方法	路径
创建任务	POST	/v1/video/generations
查询任务	GET	/v1/video/generations/{task_id}

8.1 豆包视频（doubao-seedance）

豆包视频渠道通过本平台统一接口接入。必须使用顶层字段 prompt，不要只传 content 数组。

模型名	说明
doubao-seedance-2.0	标准版，画质优先
doubao-seedance-2.0-fast	快速版，生成速度更快，适合预览或批量场景

文生视频（创建任务）

curl -sS https://ocitoken.com/v1/video/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的令牌" \
  -d '{
    "model": "doubao-seedance-2.0",
    "prompt": "一只橘猫在草地上奔跑，电影感",
    "duration": 4,
    "metadata": {
      "ratio": "16:9",
      "resolution": "720p"
    }
  }'

字段	必填	说明
model	是	doubao-seedance-2.0 或 doubao-seedance-2.0-fast
prompt	是	视频描述文本
duration	否	时长（秒），如 4
metadata.ratio	否	画幅比例，如 16:9
metadata.resolution	否	分辨率档，如 720p / 1080p / 4k

查询任务

curl -sS https://ocitoken.com/v1/video/generations/你的任务ID \
  -H "Authorization: Bearer sk-你的令牌"

状态常见值：queued / processing / succeeded / failed。成功后可在响应的 url 或 metadata.url 中获取视频地址（以实际返回为准）。

常见错误

错误信息	原因	处理
prompt is required	未传 prompt，或只传了 content	改用顶层 prompt 字段
pre_consume_token_quota_failed	令牌或账户额度不足	提高账户余额或令牌额度
504	视频生成耗时较长	使用「创建任务 + 轮询查询」，并调大代理超时

9. 常用端点一览

能力	方法	路径
模型列表	GET	/v1/models
Chat Completions	POST	/v1/chat/completions
Completions（旧）	POST	/v1/completions
Claude Messages	POST	/v1/messages
文生图	POST	/v1/images/generations
图编辑	POST	/v1/images/edits
Embeddings	POST	/v1/embeddings
Gemini 原生	POST	/v1beta/models/{model}:{action}
视频任务	POST	/v1/video/generations
视频查询	GET	/v1/video/generations/{task_id}

10. 错误处理

失败时通常返回 JSON，OpenAI 兼容格式示例：

{
  "error": {
    "message": "Invalid token",
    "type": "new_api_error",
    "code": "invalid_token"
  }
}

HTTP 状态码	常见原因
401	令牌缺失、无效或已过期
403	IP 不在白名单、模型无权限
429	请求频率超限或额度不足
500 / 502 / 503	上游故障、渠道不可用、模型超时
504	上游响应超时（图像/视频长任务较常见）

排查建议：

确认 Authorization 头格式正确
确认 model 名称与后台一致（区分大小写）
图像/视频任务优先使用流式或异步轮询
在控制台使用日志中查看详细错误与计费记录