API ドキュメント

まるの API は OpenAI の API と同じ形で呼べます(OpenAI 互換)。OpenAI の公式 SDK の接続先を変えるだけで使えます。 クレジットはチャットと共通です。

はじめに

  1. ログインして API キー の画面でキーを発行します。キー(maru_sk_ で始まる文字列)は発行したときに 1 回だけ表示されます。 サーバーにはハッシュ値だけを保存するので、後から表示し直すことはできません。キーは何本でも発行でき、名前を付けて、キーごとの利用量を見たり削除したりできます。
  2. 接続先(base URL)は https://api.maruagent.com/v1 です。
  3. リクエストに Authorization: Bearer maru_sk_... のヘッダーを付けます。ログインの Cookie では呼べません。 ブラウザーから直接呼ぶための CORS のヘッダーは返さないので、キーはサーバーや手元のプログラムから使ってください。

消費するクレジットは、各社に払う原価(1 ドル = 165 円で換算)です。チャットの画面と同じ残高から引かれ、 利用明細(/usage)に載ります。API で送った会話は会話履歴に保存しません。

接続例

OpenAI の公式 SDK(Python の openai、JavaScript の openai)で、base_url(baseURL)と API キーを指定します。 例ではキーを環境変数 MARU_API_KEY に入れています。

Python

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)
Python(ストリーム)
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)
Python(画像生成)
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)

JavaScript(チャット)
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);
JavaScript(ストリーム)
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);
}
JavaScript(画像生成)
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(チャット)
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(ストリーム)
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(Web 検索つき)
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(モデルの一覧)
curl https://api.maruagent.com/v1/models \
  -H "Authorization: Bearer $MARU_API_KEY"
curl(画像生成)
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
IDモデル
auto自動選択。質問の難易度を小型のモデルで判定し、小型のモデルか主力のモデルに回します。判定の分も消費します。応答の model は実際に答えたモデルです
gpt-6-astraGPT-6 Astra
gpt-6.1-solGPT-6.1 Sol
claude-fable-5-2Claude Fable 5.2
claude-opus-5-5Claude Opus 5.5
claude-sonnet-5-5Claude Sonnet 5.5
gemini-4-argonGemini 4 Argon
gemini-4-hydrogenGemini 4 Hydrogen
grok-4.7Grok 4.7

受け付けるパラメータ

chat/completions で受け付けるパラメータ
パラメータ扱い
model必須。上の表のどれか
messages必須。1〜500 件。role は system・developer(system と同じ扱い)・user・assistant。content は文字列か、text・image_url の配列(assistant は refusal も可、null も可)。 最後のメッセージ(system・developer を除く)は user にします。空のメッセージは 400(empty_message)
image_urluser のメッセージにだけ付けられます。data: URL(base64)だけを受け付け、https などの URL は取りに行きません(400 invalid_image_url)。 PNG・JPEG・WebP。1 枚 20MB まで、1 回に 10 枚・合計 15MB まで。画像を読めないモデルもあります
stream真偽値。既定は false
stream_options.include_usagestream: true のときだけ。true なら、最後に choices が空の配列で usage の入ったチャンクを 1 つ送ります
max_tokens・max_completion_tokens1 以上の整数。両方あれば小さい方。省略しても、モデルごとの既定の上限と、残高から出せる量の小さい方で打ち切ります
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 にパラメータ名)で断ります。

chat/completions で断るパラメータ
パラメータ内容
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_logprobslogprobs
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 枚(400 too_many_images)、合計 15MB(413 images_too_large)まで
  • 本文全体が大きすぎるときは 413 body_too_large

応答

OpenAI の chat.completion の形です。finish_reason は、出力の上限で止まったら length、それ以外は stop。usage の prompt_tokens はキャッシュの読み書きを含む入力の全体、completion_tokens_details.reasoning_tokens は思考のトークンです。

応答の例(JSON)
{
  "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)で返します。

images/generations のパラメータ
パラメータ扱い
prompt必須。4,000 文字まで
model省略か gemini-nano-banana-2.1。ほかは 404(model_not_found)
size下の表のどれか。省略は auto。ほかは 400(invalid_size)
n1 以上で、解像度ごとの上限まで(下の表)。省略は 1
response_formatb64_json だけ。url は 400(unsupported_parameter)
断るもの(400 unsupported_parameter)stream: true、partial_images(0 以外)、style、output_format(png 以外)、background・quality(auto 以外)、output_compression(100 以外)
size と解像度・縦横比・1 回の枚数の上限
size解像度・縦横比n の上限
auto1K・1:14
1024x10241K・1:14
1536x10241K・3:24
1024x15361K・2:34
1792x10241K・16:94
1024x17921K・9:164
2048x20482K・1:12
4096x40964K・1:11

応答の size は実際にできた画像の大きさ、usage は思考とテキストの分のトークンです(画像そのものは 1 枚の料金で数えます)。maru には消費・残高に加えて、頼んだ枚数(images_requested)と作れた枚数(images_generated)が入ります。1 枚も作れなかったときは 502 で、クレジットは引きません。

応答の maru の拡張

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" } } で返します。メッセージは日本語です。

エラーの例(402)
{
  "error": {
    "message": "クレジットが足りません",
    "type": "insufficient_quota",
    "param": null,
    "code": "insufficient_credits"
  }
}
ステータスとエラーのコード
ステータスtype主な code
400invalid_request_errorunsupported_parameter、invalid_json、empty_message、invalid_image_url、invalid_image_format、too_many_images、invalid_size、選んだモデルが添付を読めない(unsupported_attachment など)、ほか code が null の形の誤り
401authentication_errorinvalid_api_key(キーが無い・正しくない・削除済み)
402insufficient_quotainsufficient_credits(入力の分、または最低限の出力の分の残高が無い)
403permission_errormoderation_flagged(利用規約に反するおそれのある内容)、account_deleting(退会の手続き中)
404not_found_errormodel_not_found、unknown_url
409invalid_request_errorreservation_closed(同じリクエストが既に処理された)
413invalid_request_errorbody_too_large、input_too_large、image_too_large、images_too_large
429rate_limit_errorrate_limited、rate_limited_day(Retry-After つき)
500api_errorsave_failed、internal_error
502api_errorprovider_error(各社でエラー)、no_image(画像を作れなかった)。クレジットは引きません
503api_errorunavailable、credit_unavailable(残高を確認できない)、moderation_unavailable(入力の確認ができない)。時間をおいてやり直してください

モデルごとの消費クレジット

料金表(2026年11月16日 時点)から計算した値です。1 クレジット = 各社に払う原価 1 円(1 ドル = 165 円)。 段のあるモデルは、入力(キャッシュの読み書きを含む)のトークン数でその回の段が決まり、全部のトークンにその段の単価が付きます。 出力には思考のトークンを含みます。実際の消費は内部で小数のまま計算し、画面と credits_charged では小数 1 桁に切り上げて表示します。 今の値は GET /v1/models でも確かめられます。

GPT-6 Astra(OpenAI) gpt-6-astra

GPT-6 Astra の 100 万トークンあたりのクレジット
100 万トークンあたり入力キャッシュ読み取り出力
入力 272,000 トークンまで1,6501658,250
入力 272,001 トークン以上3,30033012,375
  • Web 検索: 1 回あたり 1.65 クレジット

GPT-6.1 Sol(OpenAI) gpt-6.1-sol

GPT-6.1 Sol の 100 万トークンあたりのクレジット
100 万トークンあたり入力キャッシュ読み取り出力
入力 272,000 トークンまで33016.51,650
入力 272,001 トークン以上660332,475
  • Web 検索: 1 回あたり 1.65 クレジット

Claude Fable 5.2(Anthropic) claude-fable-5-2

Claude Fable 5.2 の 100 万トークンあたりのクレジット
100 万トークンあたり入力キャッシュ読み取り出力
入力の長さによらず1,320336,600
  • Web 検索: 1 回あたり 1.65 クレジット

Claude Opus 5.5(Anthropic) claude-opus-5-5

Claude Opus 5.5 の 100 万トークンあたりのクレジット
100 万トークンあたり入力キャッシュ読み取り出力
入力の長さによらず660333,300
  • Web 検索: 1 回あたり 1.65 クレジット

Claude Sonnet 5.5(Anthropic) claude-sonnet-5-5

Claude Sonnet 5.5 の 100 万トークンあたりのクレジット
100 万トークンあたり入力キャッシュ読み取り出力
入力の長さによらず33016.51,650
  • Web 検索: 1 回あたり 1.65 クレジット

Gemini 4 Argon(Google) gemini-4-argon

2026年11月15日 9:00(日本時間) から(今の単価)

Gemini 4 Argon の 100 万トークンあたりのクレジット
100 万トークンあたり入力キャッシュ読み取り出力
入力の長さによらず33016.51,650
  • Web 検索: 検索クエリ 1 件あたり 2.31 クレジット

2026年12月1日 9:00(日本時間) から

Gemini 4 Argon の 100 万トークンあたりのクレジット
100 万トークンあたり入力キャッシュ読み取り出力
入力の長さによらず660333,300
  • Web 検索: 検索クエリ 1 件あたり 2.31 クレジット

Gemini 4 Hydrogen(Google) gemini-4-hydrogen

Gemini 4 Hydrogen の 100 万トークンあたりのクレジット
100 万トークンあたり入力キャッシュ読み取り出力
入力の長さによらず247.512.3751,237.5
  • Web 検索: 検索クエリ 1 件あたり 2.31 クレジット

Nano Banana 2.1(Google) gemini-nano-banana-2.1

Nano Banana 2.1 の 100 万トークンあたりのクレジット
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

Grok 4.7 の 100 万トークンあたりのクレジット
100 万トークンあたり入力キャッシュ読み取り出力
入力 199,999 トークンまで33082.5990
入力 200,000 トークン以上6601651,980
  • Web 検索: 1 回あたり 0.825 クレジット

キャッシュの書き込みの単価があるモデル(OpenAI・Anthropic)は、書き込んだ分にその単価が付きます(GET /v1/models には載せていません)。 自動選択は、判定に使う小型のモデルの分と、回答したモデルの分の合計を消費します。