AI API 与开发者工具

Sunra API：统一多模态 AI 推理的实用指南

了解 Sunra API 提供什么、如何调用多模态与大语言模型、如何安全认证、估算成本，以及上线前应该测试哪些指标。

文 / 01Router 编辑部2026年10月28日17 分钟阅读

Sunra API：统一多模态 AI 推理的实用指南

**Sunra API 是一个面向开发者的平台，可以通过生产级 API、SDK 和队列系统调用多模态 AI 模型与大语言模型。**它的核心价值并不是让所有模型拥有完全相同的能力，而是让应用可以使用一个账户体系发现模型、完成认证、提交任务、追踪长任务，并根据技术栈选择合适的接口格式。

这个区别很重要。统一 API 可以减少接入工作，却不能抹平模型之间的输入格式、输出限制、延迟、安全行为、许可协议和计费规则。评估 Sunra 的合理方式，是把它当作推理平台来检查：先确认需要的具体端点，固定模型和参数，测量完整工作流，并保留备用方案。

本文介绍 Sunra API 是什么、它如何组织接口、如何发起第一次请求、如何处理认证和异步任务、如何估算价格，以及在把它放进面向用户的功能之前应该测试什么。本文讨论的是 platform.sunra.ai 与 docs.sunra.ai 上的开发者平台，不是 sunra.ai 上独立的 Sunra 创意工作区。

本文核查于 2026 年 10 月 29 日。API 行为和示例依据 Sunra 公开文档整理；价格、模型可用性和条款可能变化。插图是概念性的编辑图，不是 Sunra 内部基础设施的结构图。

Sunra API 核心信息速览

问题	基于公开文档的回答
Sunra 是什么？	一个提供多模态推理和 LLM API 的一体化模型平台。
可以生成或处理什么？	取决于具体模型和端点，包括图像、视频、语音、文本、Embedding 等模型特定输出。
多模态 API 的基础地址是什么？	`https://api.sunra.ai`，用于预测和队列 API。
LLM API 的基础地址是什么？	`https://api-llm.sunra.ai`，用于兼容 OpenAI 和 Anthropic 格式的接口。
如何认证？	两类 API 共用一个 Sunra API Key，但原始 HTTP 请求使用不同的认证方案。
每个请求都会立即返回吗？	不会。较长的多模态任务会进入队列，并通过请求状态和结果端点追踪。
所有请求都采用同一种计费方式吗？	不同。Sunra 同时记录预定义价格和按实际用量结算的价格。
它能替换所有服务商的 API 吗？	不能。兼容性只适用于特定接口格式，模型 Schema 和能力仍需单独核实。

Sunra 文档将服务描述为一个同时覆盖扩散模型、媒体模型和 LLM 的统一访问层。文档也明确区分了两个产品接口：多模态预测使用 api.sunra.ai，LLM 请求使用 api-llm.sunra.ai。这种划分是有价值的，因为它把请求契约说清楚了，而不是假设图像生成和聊天补全属于同一个协议。

平台真正统一了什么

在 AI 基础设施中，“统一”可能有多种含义。对 Sunra 来说，它主要表示围绕大量模型端点提供统一的账户、模型目录、认证方式、客户端库体验和队列模式。它并不意味着为一个模型写的提示词可以不加修改地发送给所有其他模型。

图像端点可能需要提示词、尺寸、输出格式或参考图；视频端点可能增加时长、分辨率和参考素材；语言端点会接收消息或输入项目，并可能支持工具、结构化输出或流式传输；语音端点则有自己的音频格式和限制。真正的输入 Schema 仍然由具体端点决定。

当应用需要比较不同模型，或希望加入新模态而不为每个供应商重新实现完整的计费和任务追踪系统时，这种架构很有价值。如果产品只依赖一个窄场景模型，而且已有成熟的直连方案，则应要求统一平台通过更丰富的模型目录、更简单的运维、路由能力或支持服务证明它值得增加一层抽象。

因此，第一个工程问题不应是“怎样调用 Sunra”，而应是“这个功能需要哪个模型端点、什么输入 Schema、什么输出契约和什么失败处理方式”。把模型 ID 与端点路径作为功能配置的一部分，而不是埋在业务代码里的普通字符串。

两类 API 与认证方式

Sunra 的认证文档规定，两类产品 API 使用同一个 API Key，但原始 HTTP 请求的认证方案不同：

多模态预测和队列请求使用 api.sunra.ai，请求头为 Authorization: Key $SUNRA_KEY。
LLM 补全请求使用 api-llm.sunra.ai，请求头为 Authorization: Bearer $SUNRA_KEY。

当项目先使用 SDK，后来又加入直接 HTTP 请求时，这个差异很容易被忽略。使用错误的方案时，一个有效的 Key 也可能表现得像账户或权限错误。建议把基础地址、认证方式和端点类型放在同一个有类型约束的配置对象里。

官方建议将 Key 放在类似 SUNRA_KEY 的环境变量中。API Key 可以访问账户余额，应像密码一样管理。不要把它放进浏览器 JavaScript、移动应用安装包、公开代码仓库或 URL 查询参数。如果浏览器需要发起生成任务，应请求自己的后端，再由后端调用 Sunra。

下面是一个最小的多模态队列请求示例：

curl -X POST \
  https://api.sunra.ai/v1/queue/black-forest-labs/flux-kontext-pro/text-to-image \
  -H "Authorization: Key $SUNRA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A technical notebook showing a small robot sorting colored cables",
    "width": 1024,
    "height": 768,
    "output_format": "jpeg"
  }'

这个例子只用于说明请求结构，不代表我们推荐使用该模型，也不保证其他端点接受同样的参数。生产流量应先检查当前模型目录和端点 Schema。

发起第一个多模态请求

JavaScript/TypeScript 客户端可以把端点调用写得更简洁。Sunra 快速入门文档展示了 npm install @sunra/client、SUNRA_KEY 环境变量，以及等待结果的 sunra.subscribe()：

import { sunra } from "@sunra/client";

const result = await sunra.subscribe(
  "black-forest-labs/flux-kontext-pro/text-to-image",
  {
    input: {
      prompt: "A rabbit wearing glasses reading under a mushroom, watercolor style",
      width: 1024,
      height: 768,
      output_format: "jpeg",
    },
  },
);

console.log(result.data);

这里的关键是：subscribe() 是对队列请求的便捷封装。命令行实验等待结果很方便；对于 Web 产品，更适合建立持久化任务记录：创建本地任务、提交到 Sunra、保存请求 ID、异步更新状态，并在浏览器关闭后给用户展示仍然可恢复的状态。

第一次接入还应该记录模型标识、端点、请求参数、适用的供应商或路由选项、请求 ID、时间戳和最终输出引用。不要把 API Key 写入这些记录。如果提示词可能含有个人信息或机密信息，应在记录前制定留存和访问规则。

队列、状态与 Webhook

长时间运行的 AI 任务与普通 HTTP 请求面对的是不同的产品问题。请求可能等待容量、运行数秒或数分钟、在上游失败，或者在用户离开页面后才完成。Sunra 的队列 API 会返回 request_id，以及查询状态、获取结果和取消请求的 URL。

文档记录的生命周期包括 IN_QUEUE、IN_PROGRESS 和 COMPLETED；完成响应包含成功标记，预测失败时还会包含错误对象。状态流端点使用服务器发送事件持续推送，直到进入终止状态。如果提交时传入 Webhook，Sunra 可以在任务完成或失败后通知你的服务器，不必为每个请求持续轮询。

应把队列当成外部状态机处理。Webhook 处理器必须具备幂等性：同一个回调不能让用户得到两份结果、让内部账本扣款两次，或让任务错误地前进多步。校验回调是否属于你创建的请求和模型，验证载荷，再根据本地当前状态执行有条件的状态转换。

轮询应使用有上限的退避和服务端超时；流式处理应在文档规定的终止事件到达后关闭连接；Webhook 应在完成持久化校验后尽快返回成功，再把耗时处理放入自己的队列。这样可以在上游负载变化时保护自己的服务和用户体验。

兼容 LLM 的接口

Sunra 文档在 https://api-llm.sunra.ai 下说明了四类 LLM API 格式：

Chat Completions：/v1/chat/completions，使用 OpenAI Chat Completions 格式。
Anthropic Messages：/v1/messages，使用 Anthropic 消息格式，并在对应模型支持时提供扩展思考和工具能力。
Responses：/v1/responses，使用 OpenAI Responses 格式，支持灵活的输入项目以及对应模型提供的工具和结构化输出。
Embeddings：/v1/embeddings，使用 OpenAI Embeddings 格式，为搜索、聚类、分类和 RAG 生成向量。

这四类接口都使用 Bearer 认证。如果项目已经围绕 OpenAI 或 Anthropic SDK 构建，兼容格式可以减少迁移工作；但兼容不等于行为完全相同。上线前仍应核实模型 ID、流式语义、工具支持、上下文和输出限制、结构化输出保证，以及路由行为。

一个 OpenAI 兼容的请求大致如下：

curl -X POST https://api-llm.sunra.ai/v1/chat/completions \
  -H "Authorization: Bearer $SUNRA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-2.5-flash",
    "messages": [
      {"role": "user", "content": "Summarize this incident in three bullets."}
    ]
  }'

对于较长的生成，文档建议使用流式传输，因为耗时过长的非流式请求可能在边缘层被终止。这是运行约束，不只是界面设计偏好。客户端应处理部分输出、断开连接、重试，以及正常完成和流被取消之间的区别。

价格与成本估算

Sunra 的价格文档区分了预定义价格与按实际使用量结算。

对预定义价格端点，平台可以在任务运行前根据请求参数确定费用。当模型分辨率、时长、图像数量或其他选项已知时，这种模式便于给出可预测报价。对按实际使用量结算的端点，Sunra 可能在提交时冻结一个上限金额，任务完成后依据实际用量结算，并将差额释放回余额。

不要拿视频价格去估算图像任务，也不要以模型名称判断费用。时长、分辨率、参考素材、输出尺寸和 token 使用量都可能影响价格。视频可能按输出秒数计费；图生视频可能额外计算参考素材；某些图像端点会计算参考图数量或提示词 token。

Sunra 文档提供了可编程的价格端点：

GET /v1/models 列出模型 ID，不需要 API Key。
GET /v1/pricing 列出价格卡片，包括人类可读的展示信息和提示信息，需要 API Key。
GET /v1/pricing/model/{model_id}/endpoint/{endpoint} 返回某个模型端点的机器可读计费规则。

价格列表支持分页。应用需要预估时，应先解析模型 ID，再读取端点规则，按照文档规定的顺序计算请求参数，并向用户说明假设条件。目录数据需要谨慎缓存，并附上刷新时间，因为价格和模型可用性都可能变化。

业务上应关注的并不只是每次请求价格，而是每个验收通过结果的成本。如果一张图要生成三次才有一张被审核接受，那么最终结果成本应包含被拒绝和重试的尝试。估算单位经济性时，还要考虑重试、内容审核拒绝、存储、后处理和人工审查。

安全与生产架构

一个最小的安全生产架构通常是：

客户端向自己的后端发送经过验证的功能请求。
后端验证用户身份、执行配额与内容策略，并选择允许使用的模型端点。
后端使用服务端保存的 Key 向 Sunra 提交任务。
后端保存外部请求 ID 和脱敏任务记录。
Worker、轮询循环或 Webhook 更新任务，并向客户端返回安全的结果。

如果用户可以任意选择供应商端点，可能绕过你的预算、隐私或内容控制，因此客户端不应直接拥有这种选择权。为每个产品功能维护允许使用的模型列表。对尺寸、时长、参考 URL、文件类型和提示词长度执行服务端校验，并在可能被滥用的地方增加用户级和 IP 级限流。

Sunra 的 JavaScript 文档介绍了存储上传能力，并给出 100 MB 的单文件大小上限。这不是完整的应用上传策略。自己的服务仍应在可行时使用更低的限制，校验 MIME 类型和文件内容，对不可信文件进行扫描或隔离，并避免在不再需要时长期保存私有源文件。模型接受一个 URL，也不代表应用可以安全地从所有来源抓取它。

日志需要足够支持排错，但不能变成用户私密数据的副本。可以记录任务 ID、模型、端点、状态、耗时、响应大小、错误类型和费用元数据。API Key、认证头、私有文件 URL 和敏感提示词都应脱敏。数据留存规则应提前写清楚。

SDK、文件与模型 Schema

Sunra 的公开客户端资料覆盖 JavaScript/TypeScript、Python、Java 等集成方式，官方客户端仓库也提供示例和适用于常见框架的服务端代理包。SDK 可以提高开发效率，但团队仍然应该理解底层 HTTP 契约，以便排查供应商错误、超时和版本变化。

JavaScript 客户端可以接收 File、Blob 或 data URI，自动上传到 Sunra 存储，然后把得到的 URL 传给模型端点。自动上传很适合原型；生产环境则需要决定是直接上传、发放短期上传权限，还是先通过包含扫描和策略检查的服务端层转发文件。

多模型平台尤其需要关注 Schema。应从模型目录或 Schema 端点发现输入字段，然后固定经过测试的配置。模型别名可能更适合人类阅读，但要获得可复现结果，还应该记录请求时实际使用的模型和端点版本。

如何实际评估 Sunra

公平的评估应该比较完整工作流，而不是比较一段演示。先从产品中选择一组有代表性的任务：简单场景、正常场景、边界场景和故意失败的输入。每项任务都应在运行前写出验收条件。

至少记录这些维度：

正确性： 输出是否完成任务，并保持所有必要约束？
质量： 图像、视频、音频或文本是否可以使用，是否需要过多编辑？
延迟： 包括排队、处理、传输和重试在内的完整工作流耗时是多少？
可靠性： 有多少任务成功，出现了哪些失败类型？
成本： 包括被拒绝结果和重试在内，完整尝试花费多少？
运维： 请求 ID、状态、Webhook、日志和取消是否易于管理？
安全： 凭证、文件、提示词和输出是否符合自己的策略？

条件允许时，用同一任务集与基线直连接入做比较。保持提示词、输入文件、模型配置、超时和验收检查尽可能一致，并记录日期、模型 ID、端点、供应商、SDK 版本和价格快照。一次成功的图片或回答只能证明路径可用，不能证明稳定性。

面向用户的功能还应做恢复测试：任务排队时关闭浏览器、重复发送相同请求、取消进行中的任务、重复投递同一个 Webhook、超出配额，以及在短暂供应商错误后重试。系统应该以用户能理解的方式失败，并且不能重复扣内部账、重复生成业务记录。

如果希望比较模型可用性或构建基于网关的原型，可以先查看 01Router 模型网关。再通过 01Router API 文档确认具体接入契约，并在作出成本承诺前查看 01Router 价格页面。这些链接是产品导航资源，不代表每个 Sunra 模型当前都已通过 01Router 提供。

常见问题

Sunra API 与 Sunra 网页应用是同一个东西吗？

不是。Sunra 在 sunra.ai 提供创意工作区，在 platform.sunra.ai 提供开发者平台。它们可能共享账户生态，但 API 接入应以开发者文档、API 基础地址、Key 管理、模型目录和适用于 API 的条款为准。

Sunra API 是否为每个模型提供一个统一端点？

不是。它围绕各个模型端点提供统一平台。模型路径、输入 Schema、输出类型、支持的功能和限制都可能不同。应使用端点 Schema 和模型资料，而不是假设所有参数通用。

可以把 Sunra API Key 放在前端应用中吗？

不应该。官方认证说明把 Key 视为可访问账户余额的凭证。应将它保存在后端，或使用服务端代理，只向浏览器返回它真正需要的任务状态或结果。

`sunra.subscribe()` 与队列方法有什么区别？

subscribe() 提交请求并等待结果，是便捷方法。队列方法允许应用提交任务、保存请求 ID、稍后查询状态、获取结果或取消任务。后者通常更适合持久化的 Web 工作流。

可以用 OpenAI SDK 调用 Sunra 的 LLM 端点吗？

文档介绍了兼容 OpenAI Chat Completions、Responses 和 Embeddings 的端点。兼容格式可以减少客户端改动，但仍需针对选定模型验证模型 ID、参数、工具、流式传输、限制和错误行为。

如何计算 Sunra API 成本？

从当前模型和端点的价格规则开始。纳入所有会影响计费的请求参数，再加入重试、被拒绝的输出、后处理、存储和审核。对按实际使用量结算的端点，应区分提交时冻结的上限和最终结算金额。

Sunra 是直连模型供应商 API 的替代品吗？

当统一访问、模型选择、队列管理或单一运维界面很重要时，它可以成为有用的抽象层，但不是自动替代品。应针对具体工作负载比较支持、数据处理、延迟、价格、模型可用性、合同条款和失败恢复。

资料来源与核实说明

Sunra 文档：Introduction：平台范围及 2026 年 7 月开发者站点迁移说明。
Sunra 文档：Authentication：API Key、基础地址、认证方案和密钥安全。
Sunra 文档：Multimodal Quickstart：SDK 安装和首个端点请求。
Sunra 文档：Queue：队列提交、状态、流式传输、取消和 Webhook。
Sunra 文档：LLM Quickstart：Chat Completions、Messages、Responses 和 Embeddings 格式。
Sunra 文档：Pricing：价格 API、预定义价格、按实际使用量结算和示例。
Sunra 文档：JavaScript / TypeScript：SDK、队列方法、存储上传和文件大小说明。
Sunra AI 官方客户端仓库：客户端支持范围和示例。

本文核查于 2026 年 10 月 29 日。上述 API 机制是对链接资料的事实性概括；架构建议、评估清单和“每个验收通过结果的成本”是编辑分析。实际开发前，应重新检查模型可用性、价格、限制、隐私条款和支持参数。

Sunra API：统一多模态 AI 推理的实用指南

目录

Sunra API 核心信息速览

平台真正统一了什么

两类 API 与认证方式

发起第一个多模态请求

队列、状态与 Webhook

兼容 LLM 的接口

价格与成本估算

安全与生产架构

SDK、文件与模型 Schema

如何实际评估 Sunra

常见问题

Sunra API 与 Sunra 网页应用是同一个东西吗？

Sunra API 是否为每个模型提供一个统一端点？

可以把 Sunra API Key 放在前端应用中吗？

sunra.subscribe() 与队列方法有什么区别？

可以用 OpenAI SDK 调用 Sunra 的 LLM 端点吗？

如何计算 Sunra API 成本？

Sunra 是直连模型供应商 API 的替代品吗？

资料来源与核实说明

`sunra.subscribe()` 与队列方法有什么区别？