# some.im — AI API 网关 / Unified LLM gateway some.im 提供面向产品与业务的统一 AI 模型接入：在可核对用量与计费的前提下，通过一个网关路由并调用多家大模型与媒体生成能力。它支持 OpenAI 兼容接口、Anthropic Messages、Google Gemini、DashScope 及可配置的 OpenAI-Compatible / newAPI / 私有化上游线路。 some.im offers a unified AI gateway for teams that need multiple AI vendors and models behind one integration surface, with model routing, usage metering, billing, failover, media generation, and operational observability. ## 站点地图与爬虫约定 Sitemap: https://some.im/sitemap.xml Robots: https://some.im/robots.txt 若你是自动化代理或检索系统，请优先读取 sitemap.xml 获取完整 URL 集合；需要理解产品定位、API 入口和接入方式时再读本文件。请不要抓取登录后的控制台数据，也不要把 API Key、Webhook Secret、Claude Code 配置中的密钥写入日志或输出给第三方。 ## 公开页面 - https://some.im/ — 官网首页 - https://some.im/beta — Beta 介绍 - https://some.im/tutor — API 调用教程 - https://some.im/zh/docs/moderation — 提示词审核 API（POST /v1/moderation/prompt） - https://some.im/reports — 模型评测报告库 - https://some.im/skills — Skills 市场（开源 Agent Skills 检索 + zip 下载） - https://some.im/status — 系统状态 - https://some.im/partners — 渠道合作 - https://some.im/terms — 服务条款 - https://some.im/privacy — 隐私政策 - https://some.im/customer/login — 客户登录 - https://some.im/customer/register — 客户注册 - https://some.im/customer/tmp-files — 客户临时素材上传（登录后；图片参考图临时托管） ## IDE / CLI helpers (public, localized) SEO-friendly routes use a language prefix such as **`/zh`**, **`/en`**, **`/ja`**. - **Claude Code**: `/{lang}/cc` — gateway **root** (`ANTHROPIC_BASE_URL` **without** `/v1`). Short entry: **`/cc`** (redirects with locale). - **Cursor (OpenAI-compatible)**: `/{lang}/tools/cursor` - **Cline (VS Code extension)**: `/{lang}/tools/cline` - **Continue (VS Code)**: `/{lang}/tools/vscode` Unprefixed shortcuts: **`/tools`**, **`/tools/cursor`**, **`/tools/cline`**, **`/tools/vscode`** redirect to **`/{preferredLocale}/tools/...`** (default tool is **cursor** for bare `/tools`). Detailed walkthrough with screenshots: **`/{lang}/tutor/ide-tools`**. Signing in is required **before** exporting snippets that embed real **`sk_...`** secrets or creating keys from these pages (aligned with **`validGitHubOAuthCustomerNext`** on the OAuth `next` redirect). English mirror: Claude Code helpers target **Anthropic Messages**-shaped traffic; Cursor/Cline/Continue helpers target **`…/v1` OpenAI-compatible** **`POST …/chat/completions`**. ## 客户控制台「大师」专题介绍页（公开 · SEO） 多语种路径形如 **`/{lang}/features/drama-master`**、**`/{lang}/features/design-master`**（`lang` ∈ `zh` / `en` / `ja`）。未写语种前缀时可用 **`/features/...`** 或 **`/features`**（后者默认跳到短剧专题；见前端 `LegacyLocaleRedirect`）。 专题页文末主按钮会先进入 **`/customer/login`** 或 **`/customer/register`**，并在查询参数 **`next=`** 中携带 **`/customer/drama-master`** 或 **`/customer/design-master`**，登录成功后直达对应控制台页面（不涉及外站）。 **hreflang**：`/{lang}` 镜像页对白名单路由（tutorial、文档、法务、IDE 助手、`/features/drama-master` 等）在 `` 输出 **`alternate`/`x-default`**；**专题页**：可见 FAQ 与 `FAQPage` JSON-LD 一致；站点级 `canonical`/`og:url` 统一去掉尾随斜杠以降低重复抓取噪音。 ## 控制台「大师」产品（需登录，勿索引私有数据） The following live under **`/customer/...`** behind authentication. Automated agents MUST NOT crawl authenticated console HTML or store API keys from these flows. - **出图大师 (Design Master)**: **`https://some.im/customer/design-master`** — unified image/visual generation workflows in the tenant console (exact UI may evolve). - **短剧大师 (Drama Master)**: **`https://some.im/customer/drama-master`** — short drama / episodic authoring, AI structure scaffolding, timelines, studio & task views (nested paths such as **`/customer/drama-master/tasks`**, **`/customer/drama-master/new`**, **`/customer/drama-master/projects/{id}`** follow the SPA). - **临时素材 (Temporary Assets)**: **`https://some.im/customer/tmp-files`** — upload JPEG / PNG / GIF / WebP reference images up to 8 MB into **`/some-files/tmp/{YYMMDD}/{random}.{ext}`**; uploader is recorded and files expire after 24 hours. 第三方集成出图 / 出视频请**仅**使用下文 **`{gateway}/v1/images/*`、`…/v1/videos/*`** 等公开 Bearer 接口；本文不列出登录后控制台专用的 REST 路径。 需要把本地参考图变成公网 URL 时，可使用登录后的控制台临时素材接口：`POST /api/v1/customer/tmp-files`（服务端中转）或 `POST /api/v1/customer/tmp-files/upload-url` + 浏览器 `PUT` + `POST /api/v1/customer/tmp-files/complete`（直传后验真）。该能力只接受真实图片，最大 8 MB，24 小时有效。 ## Skills 市场（开源 Agent Skills） 聚合来自公开 GitHub 仓库的 ~1900 个 Agent Skills，并支持服务端 MCP 发布自有 skill。可检索、查看 SKILL.md、按 GitHub stars 排序，并下载为可直接放进 Claude Code `skills/` 目录的 zip 包；内置 skill 解压即 `/SKILL.md`，MCP 发布的 skill 会保留多文件目录树。 - 浏览页面：`https://some.im/skills`（列表，服务端渲染 + 客户端检索）、`https://some.im/skills/{slug}`（单个 skill 详情，SSR） - 精简索引 API：`GET https://some.im/api/v1/public/skills/index` — 全量精简索引 JSON（id/name/slug/summary/category/risk_level/risk_flags/stars/rating/source_repo/license/bytes + 分类与风险分面计数），供前端本地分页检索 - 详情 API：`GET https://some.im/api/v1/public/skills/{slug}` — 单个 skill 完整元数据 + 评分 + 按语言协商后的 SKILL.md 正文 - 下载 API：`GET https://some.im/api/v1/public/skills/{slug}/download` — zip 打包（MCP 发布内容保留子目录/多文件；`Content-Disposition: attachment`，带基于内容指纹的 ETag，支持 If-None-Match → 304） - MCP 发布：`/api/v1/mcp` 工具 `publish_skill`、`get_skill_localization`、`update_skill_localization` 可发布多文件 skill、读取待翻译描述/详情并回填多语言内容。 评分（`rating`）由各仓库 GitHub stars 经对数映射推导到 [3.5, 5.0]，`rating_count` 为真实 star 数，仅供参考，非用户评价。 ## API 总览 生产网关 Base URL（本站仅推荐以下两个 API 域名，路径与鉴权相同，均为 …/v1 前缀）： - **全球主站**（新加坡）：`https://some.im/v1` — 海外及默认国际线路 - **中国分站**：`https://api.niuwoai.com/v1` — **中国境内用户建议优先使用**，延迟通常更低 自定义域名或历史别名不在推荐列表内；集成时请仅在上述二者中选择。 ### 客户端自动选路与地理识别 无需认证接口： ```http GET https://some.im/api/v1/public/client-location ``` 用途：返回当前请求的公网 IP、Cloudflare 国家/地区代码、路由区域和建议 API Base。客户端需要判断用户是否在中国境内时，必须调用 `some.im` 这个主站接口；`api.niuwoai.com` 是国内边缘入口，没有 Cloudflare 外层保护，通常只能返回 IP，`country` 会是 `null`，不应用它来做国家/地区判断。 典型响应： ```json { "code": 0, "data": { "ip": "203.0.113.10", "country": "CN", "region": "china", "recommended_api_base": "https://api.niuwoai.com/v1" }, "message": "success" } ``` 选择规则：`country` 为 `CN` 时使用 `https://api.niuwoai.com/v1`；其他国家/地区或 `country=null` 时使用 `https://some.im/v1`。 鉴权： - 推荐：`Authorization: Bearer {API_KEY}` - 兼容：`X-Api-Key: {API_KEY}` - WebSocket 实时任务也可使用查询参数：`?token={API_KEY}` 常用请求头： - `Content-Type: application/json` - `Accept-Language: zh-CN` 或 `en-US` - `X-Request-ID: {your-request-id}`，便于排查 常用响应头： - `X-Request-ID` / `X-Request-Id`：请求追踪 ID - `X-App-Version` 或 `X-someApi-Version`：服务端版本 - `X-Routed-Model`：实际路由模型 - `X-Failover-From`：发生兜底切换时的原模型 - `X-Rate-Limit-Remaining` / `X-Rate-Limit-Reset`：限流信息 ## OpenAI 兼容聊天接口 接口： ```text POST https://some.im/v1/chat/completions Authorization: Bearer {API_KEY} Content-Type: application/json ``` 示例： ```bash curl https://some.im/v1/chat/completions \ -H "Authorization: Bearer ${SOME_API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "model": "qwen-turbo", "messages": [ { "role": "system", "content": "You are a concise assistant." }, { "role": "user", "content": "用三句话解释 some.im 是什么。" } ], "temperature": 0.7, "max_tokens": 1000, "stream": false }' ``` 流式输出： ```json { "model": "qwen-turbo", "messages": [ { "role": "user", "content": "写一个极简 API 接入 checklist。" } ], "stream": true } ``` 流式响应为 SSE，客户端逐行解析 `data: {...}`，以 `data: [DONE]` 作为结束标记。若上游返回 usage，结算以上游 usage 或网关统计为准；若上游未返回 usage，网关会按模型规则估算并在用量记录中标识。 使用 OpenAI SDK 时，把 `baseURL` 改为 some.im 网关即可： ```javascript import OpenAI from "openai"; const client = new OpenAI({ apiKey: process.env.SOME_API_KEY, baseURL: "https://some.im/v1" }); const completion = await client.chat.completions.create({ model: "qwen-turbo", messages: [{ role: "user", content: "Hello from some.im" }] }); console.log(completion.choices[0]?.message?.content); ``` ## 模型列表 接口： ```text GET https://some.im/v1/models Authorization: Bearer {API_KEY} ``` `GET /v1/models` 返回当前租户可用且已配置定价的逻辑模型 ID，不是上游厂商原始模型列表的完整镜像。运营可为不同租户配置不同的逻辑模型名、别名模型和上游线路，所以请以本接口和控制台展示为准。正所谓模型名这事，外头看是门牌号，里面可能是整条胡同，别拿门牌号硬猜房东。 需要判断模型是否支持图片输入、工具调用、思考，以及上下文和最大输出上限时，可调用 `GET https://some.im/v1/model-capabilities`，鉴权方式相同。该接口是 some.im 扩展，并非 OpenAI 标准；其中空数组或 `null` 表示目录尚未声明，只有明确的 `false` 才表示已声明不支持。 模型名支持 `some/` 前缀避让：当请求中的 `model` 形如 `some/claude-opus-4.7`、`some/qwen-turbo` 时，服务端会先去掉开头的 `some/`，再按 `claude-opus-4.7`、`qwen-turbo` 做租户模型映射与计费匹配。这个写法适合 Cursor、Claude Code 或其它 IDE / Agent 工具中模型名已被占用的场景；客户侧可填 `some/claude-opus-4.7`，网关侧仍识别为平台配置的 `claude-opus-4.7`。 下列为平台一套已配置的聊天类逻辑模型 ID 示例（与控制台某租户模型下拉一致），**仅作命名参考**；可用集合、定价与映射仍以 `GET /v1/models` 与你的控制台为准。 - `qwen-flash` - `qwen-max` - `qwen-plus` - `qwen3.6-plus` - `glm-5` - `deepseek-v4-flash` - `deepseek-v4-pro` - `gpt-5.1-codex-max` - `gpt-5.3-codex` - `gpt-5.3-codex-spark` - `gpt-5.4` - `gpt-5.5` - `claude-haiku-4.5` - `claude-opus-4.6` - `claude-opus-4.7` - `kimi-k2.5` - `kimi-k2.6` ### 虚拟逻辑模型（平台自动选型 / Failover 链） 以下 id 为 **对客可见的逻辑名**，用于 **`/v1/chat/completions`**、**`/v1/messages`** 等聊天类路由；平台按 **虚拟模型链（failover_chain）** 依次尝试链内 **物理逻辑模型**，直至命中可用上游。**不是**专用「出图 / 短剧视频」模型——图片 / 视频生成仍使用已在 **`/v1/models`** 与定价中开放的 **图片 / 视频** 逻辑模型 id。 - **`someim-auto-flash`**：偏 **低延迟 / 日常** 的自动选型别名（轻量高速线路优先；链内顺序由运营配置）。适合对话、补全、常见工具调用。 - **`someim-auto-pro`**：偏 **高质量 / 复杂推理** 的自动选型别名（更强能力线路优先；顺序由运营配置）。适合难任务、长上下文、对稳定性敏感的场景。 **计费**：用量与入账的 **BillingLogicalModel** 跟随 **实际命中** 的那条物理逻辑模型映射，而非单独以 `someim-auto-*` 作为计费键（与控制台「映射 / 虚拟模型链」及模型广场「虚拟路由」说明一致）。链名种子可在平台存在，但是否对你租户可见、是否有定价行，仍以 **`GET /v1/models`** 与控制台为准。 ## Anthropic Messages / Claude 兼容入口 接口： ```text POST https://some.im/v1/messages x-api-key: {API_KEY} anthropic-version: 2023-06-01 Content-Type: application/json ``` 示例： ```bash curl https://some.im/v1/messages \ -H "x-api-key: ${SOME_API_KEY}" \ -H "anthropic-version: 2023-06-01" \ -H "Content-Type: application/json" \ -d '{ "model": "some/claude-sonnet-4.6", "max_tokens": 1024, "messages": [ { "role": "user", "content": "请给我一个 Go API 网关排障清单。" } ], "stream": false }' ``` `Authorization: Bearer {API_KEY}` 也可用于网关鉴权；如果客户端只支持 `X-Api-Key` 或 `x-api-key`，优先按该客户端约定配置。 ### OpenAI 兼容上游 × 对外 Anthropic Messages（桥接） 当你在控制台把某 **logical model** 映射到 **OpenAI 兼容**上游（路由模板 `protocol_hint` **不是** `anthropic`）时，对客 URL **仍是** `POST {网关}/v1/messages`，HTTP 层仍可用 **Bearer sk_…** 与上面一致；网关内部将该请求 **翻译**为上游 `POST …/v1/chat/completions`，再把 **chat.completion**（或流式 OpenAI SSE）**封装回** Anthropic **message**（或 Messages 风格 SSE）。这样 **Claude Code / Anthropic SDK** 只需把 Base 指到网关根，**model** 填你已映射的 **千问 / Kimi / DeepSeek / Gemini（OpenAI 形）**等逻辑名即可。**注意**：此类路径上 **max_tokens 必填**；多模态/thinking/部分错误 JSON 可能与直连 Anthropic 有差异——以 `docs/15-API接口规范.md` §4.2 与实测为准。 如需让 Claude Code 通过 some.im 代理 Anthropic 兼容接口，可修改本机 `~/.claude/settings.json`。不要把真实 Key 提交到仓库。 ```json { "env": { "ANTHROPIC_API_KEY": "{$YOU_SOME_KEY}", "ANTHROPIC_BASE_URL": "https://some.im", "API_TIMEOUT_MS": "3000000", "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1", "ANTHROPIC_DEFAULT_HAIKU_MODEL": "some/claude-haiku-4.5", "ANTHROPIC_DEFAULT_SONNET_MODEL": "some/claude-sonnet-4.6", "ANTHROPIC_DEFAULT_OPUS_MODEL": "some/claude-opus-4.7" }, "alwaysThinkingEnabled": false, "rhetorical_style": "相声演员的精准+鲁迅的犀利" } ``` 说明： - `ANTHROPIC_BASE_URL` 使用 `https://some.im`，Claude Code 会自行拼接 Anthropic API 路径。 - `ANTHROPIC_API_KEY` 填写 some.im 控制台创建的客户 API Key。 - 默认模型名可使用运营为租户配置的逻辑模型名；实际供应商、线路与真实模型由 some.im 网关映射。若 IDE 或工具已占用裸模型名，可在前面加 `some/`，例如 `some/claude-opus-4.7`，服务端会按 `claude-opus-4.7` 解析。 - `API_TIMEOUT_MS` 可按长上下文或工具调用需求调大。 ## OpenAI 兼容图片生成 同步图片生成接口： ```text POST https://some.im/v1/images/generations Authorization: Bearer {API_KEY} Content-Type: application/json ``` 示例： ```bash curl https://some.im/v1/images/generations \ -H "Authorization: Bearer ${SOME_API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2", "prompt": "A clean product hero image for an AI API gateway, glassmorphism, dark background", "size": "1024x1024", "n": 1, "response_format": "url" }' ``` 常用字段： - `model`：逻辑模型名，例如 `gpt-image-2`、`wan2.7-image`、`nano-banana-2`，以控制台和 `/v1/models` 为准。 - `prompt`：图片提示词，必填。 - `size`：如 `1024x1024`、`1792x1024`、`1024x1792`。 - `n`：生成张数。部分模型如 DALL-E 3 / GPT Image 系列会强制为 1。 - `response_format`：`url` 或 `b64_json`，具体支持取决于上游线路。 ### 图生图（参考图） 与文生图共用 `POST /v1/images/generations`，在 JSON 请求体中附上**可公网访问**的参考图 URL 即可（无需再调已废弃的 `POST /v1/images/edits`）。推荐字段名 `reference_image_url`；`image_url` 为等价别名。 单张参考图示例： ```bash curl https://some.im/v1/images/generations \ -H "Authorization: Bearer ${SOME_API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "model": "wan2.7-image", "prompt": "将参考图改为赛博朋克夜景风格，保留主体构图", "reference_image_url": "https://example.com/input.png", "size": "1024x1024" }' ``` 多张参考图（多图生图）可用 `image_urls` 数组，或 OpenAI 形的 `images`（字符串 URL 或 `{"url":"https://…"}` 对象）；网关会归一化为 `image_url` / `reference_image_url` 后转发： ```json { "model": "nano-banana-2", "prompt": "融合两张参考图的色彩与材质，生成一张产品海报", "image_urls": [ "https://example.com/ref-a.png", "https://example.com/ref-b.png" ], "size": "1024x1024" } ``` 参考图字段（任选一种写法）： - `reference_image_url`（string）：单张参考图，推荐。 - `image_url`（string）：与上一字段等价。 - `image_urls`（string[]）：多张参考图。 - `images`（array）：OpenAI 兼容写法。 - `reference_image_urls`（string[]）：异步媒体线路也常用。 注意：参考图须为上游能直接下载的 HTTPS/HTTP 直链；是否支持图生图取决于控制台为该 `model` 映射的线路。 ### 图片：更多可选参数（网关可识别） 除 OpenAI 标准字段外，下列键在 **OpenAI 兼容透传** 或 **媒体池回退**（响应头可能出现 `X-Someapi-Image-Source: media_fallback`）时会被识别；上游是否采纳取决于线路： | 字段 | 说明 | |------|------| | `negative_prompt` | 负向提示 | | `aspect_ratio` | 如 `1:1`、`16:9`、`9:16`；未传 `size` 时可单独使用 | | `width` / `height` | 显式像素，与 `size` 二选一 | | `num_images` | 与 `n` 同义（媒体线路常用）；image_gen 多限制 1–4 | | `seed` | 随机种子（部分上游支持） | | `image` | 单张参考图 URL 别名（同 `reference_image_url`） | | `webhook` / `callback_url` | 当 POST 返回异步 `task_id` 时的终态 HTTPS 回调；**webhook 优先**，不会转给上游 | 显式异步图片任务：`POST /v1/images/async-generations`（请求体字段与上相同，含参考图与 `callback_url`）。 生成前可做提示词预检： ```text POST https://some.im/v1/moderation/prompt Authorization: Bearer {API_KEY} Content-Type: application/json ``` ```json { "prompt": "A serene landscape at sunset", "external_id": "preflight:image-job-123" } ``` 若返回 `decision: flag` 或 `decision: deny`，建议不要继续调用生成接口。若审核上游暂时不可用，平台策略为 fail-open：返回 `decision: allow` 并记录告警日志，最终仍以实际生成请求结果为准。 文档页定位：`https://some.im/zh/docs/moderation`（英文 / 日文可替换为 `/en/docs/moderation`、`/ja/docs/moderation`）。 ## 异步图片生成 本节及以下「异步视频生成」仅针对 **公开网关** `…/v1/images/*`、`…/v1/videos/*` 上的 **`sk_` Bearer** 集成。 当模型映射到 newAPI / 异步媒体线路时，仍使用： ```text POST https://some.im/v1/images/generations Authorization: Bearer {API_KEY} Content-Type: application/json ``` 请求示例（文生图）： ```json { "model": "wan2.7-image", "prompt": "一张赛博朋克城市夜景，电影感构图", "size": "1024x1024", "callback_url": "https://example.com/webhooks/some-im" } ``` 图生图时在请求体增加 `reference_image_url` 或 `image_url`（与同步接口相同）；多张可用 `image_urls` / `images` / `reference_image_urls`： ```json { "model": "wan2.7-image", "prompt": "在参考图基础上改为水彩插画风格", "reference_image_url": "https://example.com/input.png", "size": "1024x1024", "callback_url": "https://example.com/webhooks/some-im" } ``` 提交成功后通常返回任务： ```json { "id": "task_xxx", "status": "queued" } ``` 轮询： ```text GET https://some.im/v1/images/generations/{task_id} Authorization: Bearer {API_KEY} ``` 完成示例： ```json { "id": "task_xxx", "status": "completed", "result": { "data": [ { "url": "https://..." } ] } } ``` 失败示例： ```json { "id": "task_xxx", "status": "failed", "error": { "message": "upstream failed" } } ``` ## 异步视频生成 接口： ```text POST https://some.im/v1/videos/generations Authorization: Bearer {API_KEY} Content-Type: application/json ``` 文生视频示例： ```json { "model": "video-t2v", "prompt": "A slow cinematic dolly shot through a futuristic API control room", "duration": 5, "aspect_ratio": "16:9", "callback_url": "https://example.com/webhooks/some-im" } ``` 图生视频示例： ```json { "model": "video-i2v", "prompt": "让画面中的机器人轻轻挥手，镜头缓慢推进", "reference_image_url": "https://example.com/input.png", "duration_seconds": 5, "aspect_ratio": "16:9", "callback_url": "https://example.com/webhooks/some-im" } ``` `reference_image_url`、`image_url`、`image` 三者为等价别名（公网可访问 URL）。 ### 视频：更多可选参数 | 字段 | 说明 | |------|------| | `duration` / `duration_seconds` / `seconds` | 时长（秒）；未传多默认为 5；部分线路支持 `-1` 智能时长 | | `aspect_ratio` | 如 `16:9`、`9:16`、`1:1` | | `resolution` | 如 `720p`、`1080p`、`2k` | | `fps` | 帧率，未传多默认为 24 | | `negative_prompt` | 负向提示 | | `reference_image_urls` | 多参考图（最多 9，如 Replicate Seedance） | | `reference_video_urls` | 参考视频 URL（最多 3） | | `reference_audio_urls` | 参考音频 URL（最多 3） | | `reference_end_image_url` | 尾帧参考图 | | `enable_audio` | 是否生成同步音频（如 Seedance `generate_audio`） | | `replicate_seedance_input` | object，与自动映射的 Replicate input 浅合并覆盖（高阶） | | `webhook` / `callback_url` | 任务终态回调；webhook 优先，不转上游 | 视频编辑（基于已有视频）：`POST /v1/videos/edits`，请求体与 `generations` 相同，**必须**包含公网可访问的参考视频 URL（推荐 `reference_video_url`；亦接受 `video_url`、`reference_video_urls` 首项）。**不要**在此接口使用 `image_url`——图生视频请走 `POST /v1/videos/generations` 的 `reference_image_url` / `image_url`。 轮询： ```text GET https://some.im/v1/videos/generations/{task_id} Authorization: Bearer {API_KEY} ``` 完成示例： ```json { "id": "task_xxx", "status": "completed", "result": { "videos": [ { "url": "https://..." } ] } } ``` 部分图生视频 / 视频编辑场景可使用： ```text POST https://some.im/v1/videos/edits ``` 该接口请求体与 `videos/generations` 基本一致，但要求提供 `reference_video_url`。 ## 实时任务推送 WebSocket 异步图片 / 视频任务可通过 WebSocket 接收状态推送： ```text wss://some.im/v1/realtime/generations?token={API_KEY} ``` 也可使用 Header 鉴权： ```text Authorization: Bearer {API_KEY} ``` 服务端会广播与轮询接口同形的 JSON 文本帧。客户端应按 `id` / `task_id` 和 `status` 去重，终态以 `completed` 或 `failed` 为准。WebSocket、Webhook、HTTP 轮询可能乱序到达，合并状态时不要只看到达时间。 ## Webhook 回调 异步任务可在请求中传 `callback_url` / `webhook`，或在控制台配置默认异步回调 URL。终态时平台会 POST 到用户 URL，载荷通常包含： ```json { "task_id": "task_xxx", "status": "completed", "result": { "url": "https://..." }, "cost": 0.01, "timestamp": "2026-04-30T10:00:00Z", "signature": "sha256_signature" } ``` 接收方必须做幂等处理：同一 `task_id` 可能因重试收到多次。建议校验 HMAC 签名，签名原文可按项目约定使用 `task_id + status + timestamp`。 ## 余额、计费与预占 - 聊天接口按完成请求的模型和 usage 计费；故障切换时按实际完成模型计费。 - 流式请求结束前可能先做预授权或保守估算，结束后按 usage 或网关统计结算。 - 异步图片 / 视频任务在上游返回任务 ID 且本地落库后，会按保守上界做余额预占。 - 控制台和客户 API 展示的 `balance` 通常是可用余额：账面余额减去 active 预占。 - 任务 `completed` 时释放预占并扣实际费用；任务 `failed` 时释放预占且不扣该任务费用。 ## 路由、别名模型与故障切换 客户请求中的 `model` 是逻辑模型名。some.im 可按租户、API Key、协议入口把逻辑模型名映射到不同上游线路和真实模型标识，例如 Poe、OpenRouter、官方直连、DashScope、私有化 OpenAI-Compatible 服务等。 因此： - 不要根据模型名猜测真实供应商。 - `/v1/models` 只表示当前租户可用的逻辑模型。 - 成功响应可能带 `X-Routed-Model`、`X-Failover-From` 等排障头。 - 若启用兜底链或平台健康熔断，临时故障时可能切换到备用线路；能力不完全等价时以控制台和服务协议说明为准。 ## 错误处理建议 - `401` / `20001`：API Key 无效或过期，检查控制台密钥。 - `402` / `30001`：余额不足，充值或降低并发。 - `400` / `30041`：提示词审核 `deny`。 - `400` / `30042`：提示词审核 `flag`，平台按拒绝处理。 - `429` / `30002`：触发限流，按 `Retry-After` 或指数退避重试。 - `502` / `50001-50003`：上游超时、错误或限流，可做有限重试并保留 `X-Request-ID`。 - `503`：边缘快照未就绪、relay 未配置或服务暂不可用。 ## 集成最佳实践 - API Key 只放服务端，不要写入前端代码、移动端包或公开仓库。 - 每次请求带 `X-Request-ID`，排障时同时提供模型名、时间、HTTP 状态和响应头。 - 对 POST 请求可使用 `X-Idempotency-Key`，避免网络重试造成重复任务。 - 异步任务同时接入 Webhook 与轮询更稳；Webhook 负责实时通知，轮询负责兜底确认。 - 对图片和视频生成先调用 `/v1/moderation/prompt` 可减少无效任务。 - 生产环境对 429/5xx 做指数退避；不要无限重试长耗时生成任务。 ## 与本文件 - https://some.im/llm.txt — 面向 LLM 的说明文件（llm.txt） - https://some.im/llms.txt — 面向 LLM 的说明副本（llms.txt，内容一致） 本文是给 LLM、搜索代理和集成工程师的压缩版说明；完整产品、计费、控制台、工单、部署、监控和测试细节以站点、控制台与正式协议为准。