API ドキュメント
まるの API は OpenAI の API と同じ形で呼べます(OpenAI 互換)。OpenAI の公式 SDK の接続先を変えるだけで使えます。 クレジットはチャットと共通です。
はじめに
- ログインして API キー の画面でキーを発行します。キー(
maru_sk_で始まる文字列)は発行したときに 1 回だけ表示されます。 サーバーにはハッシュ値だけを保存するので、後から表示し直すことはできません。キーは何本でも発行でき、名前を付けて、キーごとの利用量を見たり削除したりできます。 - 接続先(base URL)は
https://api.maruagent.com/v1です。 - リクエストに
Authorization: Bearer maru_sk_...のヘッダーを付けます。ログインの Cookie では呼べません。 ブラウザーから直接呼ぶための CORS のヘッダーは返さないので、キーはサーバーや手元のプログラムから使ってください。
消費するクレジットは、各社に払う原価(1 ドル = 165 円で換算)です。チャットの画面と同じ残高から引かれ、 利用明細(/usage)に載ります。API で送った会話は会話履歴に保存しません。
接続例
OpenAI の公式 SDK(Python の openai、JavaScript の openai)で、base_url(baseURL)と API キーを指定します。 例ではキーを環境変数 MARU_API_KEY に入れています。
Python
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.maruagent.com/v1",
api_key=os.environ["MARU_API_KEY"], # /keys で発行した maru_sk_... のキー
)
res = client.chat.completions.create(
model="claude-sonnet-5-5", # "auto" なら自動選択
messages=[
{"role": "system", "content": "あなたは丁寧なアシスタントです。"},
{"role": "user", "content": "柴犬の性格を 3 行で教えて"},
],
max_tokens=1000,
)
print(res.choices[0].message.content)
print(res.usage)
stream = client.chat.completions.create(
model="gpt-6.1-sol",
messages=[{"role": "user", "content": "短い詩を書いて"}],
stream=True,
stream_options={"include_usage": True},
)
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
if chunk.usage:
print()
print(chunk.usage)
import base64
img = client.images.generate(
model="gemini-nano-banana-2.1",
prompt="桜の下で座る柴犬のイラスト",
size="1024x1024",
n=1,
response_format="b64_json",
)
with open("shiba.png", "wb") as f:
f.write(base64.b64decode(img.data[0].b64_json))
JavaScript(Node.js)
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.maruagent.com/v1",
apiKey: process.env.MARU_API_KEY, // /keys で発行した maru_sk_... のキー
});
const res = await client.chat.completions.create({
model: "claude-sonnet-5-5", // "auto" なら自動選択
messages: [{ role: "user", content: "柴犬の性格を 3 行で教えて" }],
max_tokens: 1000,
});
console.log(res.choices[0].message.content);
// まるの拡張(消費したクレジットと残高)
console.log(res.maru);
const stream = await client.chat.completions.create({
model: "gpt-6.1-sol",
messages: [{ role: "user", content: "短い詩を書いて" }],
stream: true,
stream_options: { include_usage: true },
});
for await (const chunk of stream) {
process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
if (chunk.usage) console.log("\n", chunk.usage, chunk.maru);
}
import { writeFile } from "node:fs/promises";
const img = await client.images.generate({
model: "gemini-nano-banana-2.1",
prompt: "桜の下で座る柴犬のイラスト",
size: "1024x1024",
n: 1,
response_format: "b64_json",
});
await writeFile("shiba.png", Buffer.from(img.data[0].b64_json, "base64"));
curl
curl https://api.maruagent.com/v1/chat/completions \
-H "Authorization: Bearer $MARU_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "auto",
"messages": [{"role": "user", "content": "こんにちは"}]
}'
curl -N https://api.maruagent.com/v1/chat/completions \
-H "Authorization: Bearer $MARU_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-5-5",
"messages": [{"role": "user", "content": "こんにちは"}],
"stream": true,
"stream_options": {"include_usage": true}
}'
curl https://api.maruagent.com/v1/chat/completions \
-H "Authorization: Bearer $MARU_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-4-hydrogen",
"messages": [{"role": "user", "content": "今日の東京の天気は?"}],
"web_search_options": {}
}'
curl https://api.maruagent.com/v1/models \
-H "Authorization: Bearer $MARU_API_KEY"
curl https://api.maruagent.com/v1/images/generations \
-H "Authorization: Bearer $MARU_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt": "桜の下で座る柴犬のイラスト", "size": "1024x1024", "n": 1}'
POST /v1/chat/completions
チャットの回答を作ります。stream: true なら Server-Sent Events(chat.completion.chunk)で少しずつ返し、最後に data: [DONE] を送ります。
モデル
model には auto(自動選択)か、次の ID を指定します。それ以外は 404(model_not_found)です。
| ID | モデル |
|---|---|
auto | 自動選択。質問の難易度を小型のモデルで判定し、小型のモデルか主力のモデルに回します。判定の分も消費します。応答の model は実際に答えたモデルです |
gpt-6-astra | GPT-6 Astra |
gpt-6.1-sol | GPT-6.1 Sol |
claude-fable-5-2 | Claude Fable 5.2 |
claude-opus-5-5 | Claude Opus 5.5 |
claude-sonnet-5-5 | Claude Sonnet 5.5 |
gemini-4-argon | Gemini 4 Argon |
gemini-4-hydrogen | Gemini 4 Hydrogen |
grok-4.7 | Grok 4.7 |
受け付けるパラメータ
| パラメータ | 扱い |
|---|---|
model | 必須。上の表のどれか |
messages | 必須。1〜500 件。role は system・developer(system と同じ扱い)・user・assistant。content は文字列か、text・image_url の配列(assistant は refusal も可、null も可)。 最後のメッセージ(system・developer を除く)は user にします。空のメッセージは 400(empty_message) |
image_url | user のメッセージにだけ付けられます。data: URL(base64)だけを受け付け、https などの URL は取りに行きません(400 invalid_image_url)。 PNG・JPEG・WebP。1 枚 20MB まで、1 回に 10 枚・合計 15MB まで。画像を読めないモデルもあります |
stream | 真偽値。既定は false |
stream_options.include_usage | stream: true のときだけ。true なら、最後に choices が空の配列で usage の入ったチャンクを 1 つ送ります |
max_tokens・max_completion_tokens | 1 以上の整数。両方あれば小さい方。省略しても、モデルごとの既定の上限と、残高から出せる量の小さい方で打ち切ります |
temperature・top_p | 範囲(0〜2、0〜1)だけを確かめ、各社には渡しません |
web_search_options | オブジェクトがあれば Web 検索を使います(各社の検索機能)。中の指定(search_context_size など)は使いません。検索の回数分のクレジットを消費します。引用は message.annotations(url_citation)に入ります |
| 既定値のときだけ通すもの | n: 1、response_format: { "type": "text" }、modalities: ["text"]、logprobs: false、frequency_penalty: 0、presence_penalty: 0、verbosity: "medium"、service_tier: "auto"、logit_bias: {}、空の配列の tools など |
上の表にも下の表にも無いパラメータは、見ずに無視します。
断るパラメータ(400 unsupported_parameter)
次の指定は黙って無視せず、400(code: "unsupported_parameter"、param にパラメータ名)で断ります。
| パラメータ | 内容 |
|---|---|
tools・functions・tool_choice・function_call・parallel_tool_calls | ツールの呼び出し(空の配列は通します) |
assistant の tool_calls・function_call、role の tool・function | ツールの呼び出しと結果 |
audio、assistant の audio、content の input_audio | 音声の入出力 |
modalities(text 以外を含む) | テキスト以外の出力 |
content の file | ファイル(PDF など)の入力 |
n(1 以外) | 2 つ以上の回答 |
stop | 停止の文字列 |
logprobs: true・top_logprobs | logprobs |
prediction | 予測の出力 |
response_format(json_object・json_schema) | JSON の出力の指定 |
reasoning_effort・seed | 指定すると断ります |
logit_bias・frequency_penalty・presence_penalty・verbosity・service_tier | 既定値(空・0・medium・auto)以外 |
大きさの上限
- テキストは合計 400,000 文字まで(超えると 413
input_too_large)。モデルに送れる入力の長さを超えたときも 413 - 画像は 1 枚 20MB(413
image_too_large)、1 回に 10 枚(400too_many_images)、合計 15MB(413images_too_large)まで - 本文全体が大きすぎるときは 413
body_too_large
応答
OpenAI の chat.completion の形です。finish_reason は、出力の上限で止まったら length、それ以外は stop。usage の prompt_tokens はキャッシュの読み書きを含む入力の全体、completion_tokens_details.reasoning_tokens は思考のトークンです。
{
"id": "chatcmpl-01J...",
"object": "chat.completion",
"created": 1794787200,
"model": "claude-sonnet-5-5",
"choices": [
{
"index": 0,
"message": { "role": "assistant", "content": "こんにちは!", "refusal": null, "annotations": [] },
"logprobs": null,
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 12,
"completion_tokens": 8,
"total_tokens": 20,
"prompt_tokens_details": { "cached_tokens": 0 },
"completion_tokens_details": { "reasoning_tokens": 0 }
},
"maru": {
"credits_charged": "0.1",
"credits_charged_micro": 17160,
"credits_remaining": "399.9",
"credits_remaining_micro": 399982840
}
}
ストリームでは、最初のチャンクの delta が { "role": "assistant", "content": "" }、最後の choices のチャンクに finish_reason が入ります。maru の拡張は、include_usage が true なら usage のチャンクに、そうでなければ finish_reason のチャンクに付きます。 各社でエラーが起きたときは、ストリームの途中に { "error": { ... } } を 1 つ送って閉じます([DONE] は送りません)。
GET /v1/models・GET /v1/models/:id
使えるモデルの一覧です(auto、チャットの 8 種、画像生成の gemini-nano-banana-2.1)。OpenAI の形({ "object": "list", "data": [...] })に、maru の拡張として表示名・種類・コンテキスト長と、今の単価での消費クレジット(100 万トークンあたりの入力・キャッシュ読み取り・出力を入力の長さの段ごとに、Web 検索 1 回あたり、画像 1 枚あたり)を付けます。 消費クレジットは、表示用の小数 1 桁の文字列(credits、切り上げ)と、整数のマイクロクレジット(micro、1 クレジット = 1,000,000)の両方です。
POST /v1/images/generations
画像を作ります。モデルは Nano Banana 2.1(gemini-nano-banana-2.1)だけで、model を省略してもこれを使います。応答は 1 枚ずつ data[].b64_json(base64)で返します。
| パラメータ | 扱い |
|---|---|
prompt | 必須。4,000 文字まで |
model | 省略か gemini-nano-banana-2.1。ほかは 404(model_not_found) |
size | 下の表のどれか。省略は auto。ほかは 400(invalid_size) |
n | 1 以上で、解像度ごとの上限まで(下の表)。省略は 1 |
response_format | b64_json だけ。url は 400(unsupported_parameter) |
断るもの(400 unsupported_parameter) | stream: true、partial_images(0 以外)、style、output_format(png 以外)、background・quality(auto 以外)、output_compression(100 以外) |
| size | 解像度・縦横比 | n の上限 |
|---|---|---|
auto | 1K・1:1 | 4 |
1024x1024 | 1K・1:1 | 4 |
1536x1024 | 1K・3:2 | 4 |
1024x1536 | 1K・2:3 | 4 |
1792x1024 | 1K・16:9 | 4 |
1024x1792 | 1K・9:16 | 4 |
2048x2048 | 2K・1:1 | 2 |
4096x4096 | 4K・1:1 | 1 |
応答の size は実際にできた画像の大きさ、usage は思考とテキストの分のトークンです(画像そのものは 1 枚の料金で数えます)。maru には消費・残高に加えて、頼んだ枚数(images_requested)と作れた枚数(images_generated)が入ります。1 枚も作れなかったときは 502 で、クレジットは引きません。
応答の maru の拡張
| フィールド | 内容 |
|---|---|
credits_charged | このリクエストで消費したクレジット(小数 1 桁の文字列、切り上げ)。自動選択の判定の分を含みます |
credits_charged_micro | 同じ値の整数のマイクロクレジット(1 クレジット = 1,000,000) |
credits_remaining | 消費の後の残高(小数 1 桁の文字列、切り捨て)。分からないときは null |
credits_remaining_micro | 同じ値の整数のマイクロクレジット。分からないときは null |
images_requested・images_generated | 画像生成だけ。頼んだ枚数と作れた枚数 |
利用速度の上限
1 人あたり 1 分に 10 回、1 日に 500 回までです。API キーごとではなく 1 人あたりで、チャットの画面での送信と合算して数えます。1 日は日本時間の 0 時で区切ります。 超えると 429(1 分の上限は rate_limited、1 日の上限は rate_limited_day)を返し、Retry-After ヘッダーに待つ秒数を入れます。
エラー
エラーは OpenAI の形 { "error": { "message", "type", "param", "code" } } で返します。メッセージは日本語です。
{
"error": {
"message": "クレジットが足りません",
"type": "insufficient_quota",
"param": null,
"code": "insufficient_credits"
}
}
| ステータス | type | 主な code |
|---|---|---|
| 400 | invalid_request_error | unsupported_parameter、invalid_json、empty_message、invalid_image_url、invalid_image_format、too_many_images、invalid_size、選んだモデルが添付を読めない(unsupported_attachment など)、ほか code が null の形の誤り |
| 401 | authentication_error | invalid_api_key(キーが無い・正しくない・削除済み) |
| 402 | insufficient_quota | insufficient_credits(入力の分、または最低限の出力の分の残高が無い) |
| 403 | permission_error | moderation_flagged(利用規約に反するおそれのある内容)、account_deleting(退会の手続き中) |
| 404 | not_found_error | model_not_found、unknown_url |
| 409 | invalid_request_error | reservation_closed(同じリクエストが既に処理された) |
| 413 | invalid_request_error | body_too_large、input_too_large、image_too_large、images_too_large |
| 429 | rate_limit_error | rate_limited、rate_limited_day(Retry-After つき) |
| 500 | api_error | save_failed、internal_error |
| 502 | api_error | provider_error(各社でエラー)、no_image(画像を作れなかった)。クレジットは引きません |
| 503 | api_error | unavailable、credit_unavailable(残高を確認できない)、moderation_unavailable(入力の確認ができない)。時間をおいてやり直してください |
モデルごとの消費クレジット
料金表(2026年11月16日 時点)から計算した値です。1 クレジット = 各社に払う原価 1 円(1 ドル = 165 円)。 段のあるモデルは、入力(キャッシュの読み書きを含む)のトークン数でその回の段が決まり、全部のトークンにその段の単価が付きます。 出力には思考のトークンを含みます。実際の消費は内部で小数のまま計算し、画面と credits_charged では小数 1 桁に切り上げて表示します。 今の値は GET /v1/models でも確かめられます。
GPT-6 Astra(OpenAI) gpt-6-astra
| 100 万トークンあたり | 入力 | キャッシュ読み取り | 出力 |
|---|---|---|---|
| 入力 272,000 トークンまで | 1,650 | 165 | 8,250 |
| 入力 272,001 トークン以上 | 3,300 | 330 | 12,375 |
- Web 検索: 1 回あたり 1.65 クレジット
GPT-6.1 Sol(OpenAI) gpt-6.1-sol
| 100 万トークンあたり | 入力 | キャッシュ読み取り | 出力 |
|---|---|---|---|
| 入力 272,000 トークンまで | 330 | 16.5 | 1,650 |
| 入力 272,001 トークン以上 | 660 | 33 | 2,475 |
- Web 検索: 1 回あたり 1.65 クレジット
Claude Fable 5.2(Anthropic) claude-fable-5-2
| 100 万トークンあたり | 入力 | キャッシュ読み取り | 出力 |
|---|---|---|---|
| 入力の長さによらず | 1,320 | 33 | 6,600 |
- Web 検索: 1 回あたり 1.65 クレジット
Claude Opus 5.5(Anthropic) claude-opus-5-5
| 100 万トークンあたり | 入力 | キャッシュ読み取り | 出力 |
|---|---|---|---|
| 入力の長さによらず | 660 | 33 | 3,300 |
- Web 検索: 1 回あたり 1.65 クレジット
Claude Sonnet 5.5(Anthropic) claude-sonnet-5-5
| 100 万トークンあたり | 入力 | キャッシュ読み取り | 出力 |
|---|---|---|---|
| 入力の長さによらず | 330 | 16.5 | 1,650 |
- Web 検索: 1 回あたり 1.65 クレジット
Gemini 4 Argon(Google) gemini-4-argon
2026年11月15日 9:00(日本時間) から(今の単価)
| 100 万トークンあたり | 入力 | キャッシュ読み取り | 出力 |
|---|---|---|---|
| 入力の長さによらず | 330 | 16.5 | 1,650 |
- Web 検索: 検索クエリ 1 件あたり 2.31 クレジット
2026年12月1日 9:00(日本時間) から
| 100 万トークンあたり | 入力 | キャッシュ読み取り | 出力 |
|---|---|---|---|
| 入力の長さによらず | 660 | 33 | 3,300 |
- Web 検索: 検索クエリ 1 件あたり 2.31 クレジット
Gemini 4 Hydrogen(Google) gemini-4-hydrogen
| 100 万トークンあたり | 入力 | キャッシュ読み取り | 出力 |
|---|---|---|---|
| 入力の長さによらず | 247.5 | 12.375 | 1,237.5 |
- Web 検索: 検索クエリ 1 件あたり 2.31 クレジット
Nano Banana 2.1(Google) gemini-nano-banana-2.1
| 100 万トークンあたり | 入力 | キャッシュ読み取り | 出力 |
|---|---|---|---|
| 入力の長さによらず | 247.5 | — | 1,237.5 |
- Web 検索: 検索クエリ 1 件あたり 2.31 クレジット
- 画像 1 枚(1K): 5.544 クレジット
- 画像 1 枚(2K): 8.316 クレジット
- 画像 1 枚(4K): 18.645 クレジット
Grok 4.7(xAI) grok-4.7
| 100 万トークンあたり | 入力 | キャッシュ読み取り | 出力 |
|---|---|---|---|
| 入力 199,999 トークンまで | 330 | 82.5 | 990 |
| 入力 200,000 トークン以上 | 660 | 165 | 1,980 |
- Web 検索: 1 回あたり 0.825 クレジット
キャッシュの書き込みの単価があるモデル(OpenAI・Anthropic)は、書き込んだ分にその単価が付きます(GET /v1/models には載せていません)。 自動選択は、判定に使う小型のモデルの分と、回答したモデルの分の合計を消費します。