The Fugu API Guide: Endpoints, Gotchas, and Working Code

Fugu’s API looks familiar on purpose — OpenAI-compatible endpoints, a standard SDK workflow, bearer-token auth — and then diverges in ways that matter: parameters that are silently ignored, a Responses API that refuses conversation IDs, output caps that don’t cap costs, and a usage object with billable lines most APIs don’t have. This is the complete developer reference for Sakana Fugu, verified against Sakana’s live documentation on August 19, 2026.

The endpoints

Base URL: https://api.sakana.ai/v1. Four endpoints:

Endpoint	What it is
/v1/responses	OpenAI-compatible Responses API — Sakana’s recommended endpoint for generation
/v1/chat/completions	OpenAI-compatible Chat Completions — the drop-in path for existing code
/v1/messages	Anthropic-compatible Messages API — what the Claude Code integration uses
/v1/models	Model listing (note: fugu-cyber appears only for keys in pay-as-you-go billing mode)

Having both OpenAI- and Anthropic-compatible surfaces means most existing clients work by changing only the base URL and key — which is exactly how the Claude Code and Codex integrations are built.

Auth and keys

Create keys in the Sakana console. They start with fish_, are shown once at creation, and authenticate as a bearer token: Authorization: Bearer $SAKANA_API_KEY. Sakana’s terms attribute all usage on a key to its owner and prohibit sharing credentials — treat keys like passwords and rotate on any suspicion. (Also worth knowing before you send sensitive data: API inputs and outputs are used for training by default, with an opt-out, and entering personal information is prohibited.)

Quickstart

Verify your key with the exact curl from Sakana’s get-started page:

export SAKANA_API_KEY={your api key}
curl -X POST https://api.sakana.ai/v1/chat/completions 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer $SAKANA_API_KEY" 
  -d '{"model":"fugu","messages":[{"role":"user","content":"How many r in word strawberry"}]}'

And the recommended path — the Responses API through the standard OpenAI SDK:

from openai import OpenAI

client = OpenAI(
    base_url="https://api.sakana.ai/v1",
    api_key="YOUR_API_KEY",
)

response = client.responses.create(
    model="fugu-ultra",
    input="Write a concise explanation of how TLS works",
    timeout=120.0,
)
print(response.output_text)

That explicit timeout is from Sakana’s own example, and it’s load-bearing: the docs note that complex tasks — especially on fugu-ultra and fugu-cyber — may need increased client-side timeouts, because a multi-agent turn can genuinely run long. (Sakana’s own Codex config sets a two-hour stream idle timeout.)

The model IDs

Model ID	What it is	Effort levels
fugu	Default: balances performance and latency, routes across the full provider pool	high, xhigh
fugu-ultra	Alias, resolves to the latest Ultra	(as its target)
fugu-ultra-v1.1	Current Fugu Ultra	high, xhigh, max
fugu-ultra-v1.0	Previous Ultra (formerly fugu-ultra-20260615)	high, xhigh
fugu-cyber	Security-specialized; access-gated, PAYG billing mode required	high, xhigh
sakana-namazu	Separate Japanese-specialized model (not a Fugu variant)	—

On effort levels, Sakana’s documentation is precise and worth quoting in substance: max is a distinct maximum level only on fugu-ultra-v1.1; on fugu, fugu-ultra-v1.0, and fugu-cyber, max is accepted for compatibility but maps to xhigh. Set the level via reasoning.effort (e.g. effort="high"); any other value is rejected. All Fugu models have a 1,000,000-token context window, with a higher price tier above 272K tokens of context.

The gotchas: parameters that don’t do what you think

This list is the difference between code that works on Fugu and code that works as you intended. All documented by Sakana:

• Accepted but ignored: temperature, top_p, stop, seed, frequency_penalty, presence_penalty. No errors — your sampling settings just don’t exist. If your test suite assumes a seeded model is deterministic, it will mislead you.
• parallel_tool_calls: accepted but ignored; the server forces it on where supported.
• previous_response_id is not accepted on the Responses API. There is no server-side conversation state: send the full history in input every turn. This has real cost consequences — history grows your input every turn, so cache-friendly prompt structure matters.
• Output caps don’t cap costs: on Fugu Ultra, max_output_tokens / max_completion_tokens limit only the final visible response — the orchestrator still uses its own internal maximum. There is no per-request hard cost cap.

Responses vs. Chat Completions: which to use

	Responses (/v1/responses)	Chat Completions
Sakana’s position	Officially recommended for generation	Supported, drop-in compatible
Conversation state	Stateless — previous_response_id rejected; resend history in input	Stateless by design — resend messages
Built-in tools	Built-in web_search supported (OpenAI-compatible shape; advanced options unsupported)	—
Best for	New code, tool use, the officially tested path (it’s what the Codex integration uses: wire_api = "responses")	Porting existing OpenAI-style code with minimal changes

Structured output

Fugu supports structured output via text.format (Responses) / response_format (Chat Completions), with both json_object and json_schema modes. Given that sampling parameters are ignored, a JSON schema is your main lever for output shape — use it rather than prompt-begging for valid JSON. (One distribution caveat: if you access Fugu through OpenRouter instead of directly, response_format is excluded there and you use its structured_outputs mechanism — details in the OpenRouter guide.)

Built-in web search

The Responses API supports Sakana’s built-in web_search tool in the standard OpenAI-compatible shape — declare it in tools and the model searches as needed. Advanced search options aren’t supported. Your own function tools work through standard tool definitions on both OpenAI-compatible endpoints.

The custom model pool: provider opt-out per key

By default, fugu routes across all supported providers. If policy or privacy forbids a particular underlying vendor, enable Fugu custom model pool while creating or editing the API key and leave only the providers you want; leave the setting off for the full default pool. This is a per-key setting — you can run one key with the full pool and a restricted key for sensitive workloads side by side.

Reading usage — and paying for it

Fugu Ultra and Fugu Cyber responses include usage fields most APIs don’t have: input_tokens_details.orchestration_input_tokens, .orchestration_input_cached_tokens, and output_tokens_details.orchestration_output_tokens. Unlike the informational token details on other platforms, these are real billed usage at standard rates, and total_tokens includes them. Log them from day one. The full mechanics — worked examples, audit arithmetic, cost controls — are in the orchestration tokens guide, and the calculator models them.

Capabilities, from the official model catalog

Sakana publishes a machine-readable model catalog (the same fugu.json its Codex integration deploys). A few capability fields from it are worth having at hand — as of August 19, 2026:

Model	Input modalities	Parallel tool calls	Reasoning summaries
fugu	text, image	yes	no
fugu-ultra-v1.1	text, image	yes	yes
fugu-ultra-v1.0	text, image	yes	yes
fugu-cyber	text, image	yes	yes

All four share the 1M context window and the high/xhigh effort pair, with max distinct only on fugu-ultra-v1.1. Remember that parallel tool calls are server-managed — your parallel_tool_calls parameter is ignored and the server forces it on where supported.

Bonus: Sakana Namazu on the same key

Your Fugu key also unlocks Sakana Namazu, the company’s separate Japanese-specialized model — useful as a cheap connectivity check and pipeline stand-in ($0.95/M input vs Ultra’s $5, as of August 2026, pay-as-you-go only). Sakana’s own connectivity test:

export SAKANA_API_KEY={your api key}
curl -X POST https://api.sakana.ai/v1/chat/completions 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer $SAKANA_API_KEY" 
  -d '{"model":"sakana-namazu","messages":[{"role":"user","content":"こんにちは！"}]}'

Namazu goes beyond Fugu’s modalities: image input, file input (PDF, XLSX, CSV, DOCX and more), built-in tools (web_search, code_interpreter), and extended thinking — with thinking tokens billed at the output rate and tool usage billed separately (details in the pricing guide).

Production advice

• Set long client timeouts for fugu-ultra and fugu-cyber, and make retries deliberate: Sakana documents Fugu as stateless, so retries are idempotent — but each retry is a fully billed request, so cap them.
• Pin model versions in production (fugu-ultra-v1.1, not the fugu-ultra alias) so a new Ultra release never changes your model silently — the same principle Sakana applied to its own Codex integration.
• Structure prompts for the cache: stable prefix first, variable content last. Cached input is 90% cheaper and the discount applies to orchestration input too.
• Budget at the gateway, not the request: per-request caps don’t exist; meter cumulative billed tokens from usage objects and enforce your own daily ceilings.
• Pick billing deliberately: pay-as-you-go tokens are served at higher priority than subscription tokens — production traffic belongs on pay-as-you-go, human sessions on plans.

Next steps: wire Fugu into your editor via Claude Code or Codex, understand what you’ll actually be billed, or skip the account entirely and probe the API behavior through the playground and the OpenRouter route.