接入指南

Sakana Fugu API 快速上手

能复制的代码不等于能上线的代码。一个合格接入还要配置错误立即暴露、网络重试有边界，并完整记录会计费的编排 token。本指南把这三件事一起做好。

发布并核验于 2026 年 7 月 21 日下文附第一方来源

1. 写请求前先选模型

三款模型共用接口形状，但路由控制、价格可预测性、准入和适用任务不同。模型选择应该是明确配置，不是“质量越高越好”的神秘开关。

Model ID	适合	重要限制
`fugu`	交互编程、聊天、常规审查、第一轮评估	按量成本随实际路由变化；可排除指定 agent
`fugu-ultra`	质量值得额外时间和费用的复杂多步骤推理	固定完整 agent pool；当前文档称使用 1 到 3 个 agent
`fugu-ultra-20260615`	固定到官方记录的日期版本	除非明确需要 pin version，否则优先稳定 ID
`fugu-cyber`	经授权的防御性安全推理与调查	只支持按量计费，获批后才会出现在可用模型中

部署阶段应调用 GET /v1/models，不要假设每把 key 都能使用所有 model ID。这样能把模糊的生成失败，变成清楚的部署配置错误。

2. 启动时就校验配置

密钥应放环境变量。缺失时立即报出准确变量名，不要等到发请求后才出现含糊的认证或 URL 错误。

client.py

import os
from openai import OpenAI


def require_environment_value(name: str) -> str:
    value = os.environ.get(name, "").strip()
    if not value:
        raise RuntimeError(f"Missing required environment variable: {name}")
    return value


def create_fugu_client() -> OpenAI:
    base_url = require_environment_value("FUGU_BASE_URL").rstrip("/")
    if not base_url.endswith("/v1"):
        base_url += "/v1"
    return OpenAI(
        api_key=require_environment_value("FUGU_API_KEY"),
        base_url=base_url,
        timeout=120.0,
        max_retries=2,
    )

为什么只重试两次？

少量有限重试可以吸收偶发连接或限流错误。无限循环会重复执行昂贵的自主任务、掩盖持续故障，也让调用方无法判断系统到底发生了什么。

3. 新接入优先 Responses API

Sakana AI 当前支持 Responses、Chat Completions 和 Models endpoint。官方 model 文档更推荐 Responses，用于工具、多模态、reasoning 控制和函数调用。

直接响应

from client import create_fugu_client


def review_change(change_description: str) -> str:
    if not change_description.strip():
        raise ValueError("change_description must not be empty")

    response = create_fugu_client().responses.create(
        model="fugu",
        instructions="先找正确性风险，并明确说明不确定性。",
        input=change_description,
        max_output_tokens=2000,
    )
    return response.output_text


print(review_change("审查这个数据库迁移的回滚风险。"))

本地空值检查看似简单，却能避免一次无意义的计费请求，并在进入网络边界前给出具体错误。

4. 流式输出也要保留最终响应对象

Streaming 能降低用户等待感，但最终 response 对象仍包含状态与 usage。不能只打印文字增量就把它丢掉。

流式响应

from client import create_fugu_client


def stream_answer(prompt: str):
    client = create_fugu_client()
    with client.responses.stream(model="fugu-ultra", input=prompt) as stream:
        for event in stream:
            if event.type == "response.output_text.delta":
                print(event.delta, end="", flush=True)
        return stream.get_final_response()


final_response = stream_answer("比较两种回滚方案并列出失败模式。")
print()
print(final_response.usage)

调用方断开时，要提前决定是否取消上游任务。除非确认操作可安全重复，且上一请求没有完成，否则不要自动再次提交同一任务。

5. 兼容形状，不等于参数语义完全一致

当前 Sakana model 页面明确记录了下列差异。

字段或行为	当前文档行为	接入影响
`temperature`	Responses 接受但忽略	不要围绕它设计质量控制
`top_p`、penalty、seed、stop	Chat Completions 接受但忽略	所需确定性必须通过真实输出验证
`previous_response_id`	不接受	在 input 中发送完整对话历史
`max_output_tokens`	对 Ultra 只限制最终模型输出，不限制 orchestrator 最大用量	不能把它当完整成本上限
`reasoning.effort`	支持 high、xhigh、max；xhigh 与 max 是 alias	不要假设存在三个独立档位
内置 web search	通过 Responses tools 形状支持	上线前验证引用和工具输出处理

6. 保存所有会计费的 usage 字段

Ultra 与 Cyber 在普通 input/output 之外，还返回编排 token 明细。Sakana AI 表示这些是真实使用量，会按对应输入、缓存或输出费率计入最终费用。

7. 把常见故障变成具体动作

401 或 403

检查 key 是否存在、有效，并绑定预期 billing mode。Cyber 还需确认访问已获批。日志绝不能打印 secret 本身。

404 model not found

用同一 key 与 base URL 调 Models API。启动时直接报出缺失 model ID，不要悄悄换成另一个模型。

429 限流

遵循服务端重试提示，总尝试次数必须有限，最终错误要暴露。队列可以削峰，但队列也要有容量与过期策略。

Timeout

日志要区分连接耗时和任务耗时。困难多智能体任务可能确实较久，但无限加大 timeout 不能替代取消、可观测性与用户状态提示。

费用异常

用完整 usage 对照价格公式，检查编排字段和单次请求是否超过 272K context。不能只看可见回答长度猜费用。

答案好看但错误

不要盲目重试。保存 prompt、工具、model ID 与 response ID，按固定规则评分，并让高风险任务进入人工复核。

8. 上线检查清单

API key 与 base URL 为必填，并在启动时校验。
通过 /v1/models 验证所选模型。
Timeout 与 retry 都有明确有限值。
请求本身可安全重试，或应用层有幂等策略。
日志记录模型、耗时、状态、关联 ID，但默认不记录 secret 或敏感 prompt。
保留完整 usage 对象用于成本核账。
不会把被忽略参数展示成有效控制项。
降级行为写清楚：要么明确失败，要么使用批准过的具名 fallback 并说明质量取舍。
在 EU / EEA 部署前重新确认官方可用性。
Cyber 只用于经批准、经授权、有书面范围的安全测试。

来源与核验边界

Sakana AI Models 文档：ID、endpoint、支持字段、示例与 usage 细节
Sakana AI Pricing 文档：计费模式与 token 费率
Sakana AI Fugu 产品页：模型定位、agent opt-out 与可用性

本页说明的是公开文档行为，不是私有兼容性认证。正式发布前应重新查询 Models endpoint 和官方文档。