新着違うモデルを出品する販売者をどう見抜き、どう返金するか。

画像、動画、音楽、音声

テキストに使用するキーで、同じ残高から画像、動画、音楽、音声を生成し、録音をテキストに変換することもできます。モデル表 (または ?type=image, ?type=music, ?type=audio) からモデルを選択してください。各モデルのページには、その価格、種類、動作するリクエストが記載されています。

目的 ルート ソース画像の場所
プロンプトから新しい画像を生成 POST /v1/images/generations (なし)
画像を編集 POST /v1/images/edits image (または image_url, input_images, images)
プロンプトから動画を生成 POST /v1/video/generations (なし)
画像から始まる動画を生成 POST /v1/video/generations image_url (最初のフレーム); 最後のフレームは end_image_url
参照画像から動画を生成 POST /v1/video/generations input_images と "role": "reference"
画像に関するテキスト回答 POST /v1/chat/completions messages[].content の image_url 部分
音楽 POST /v1/music/generations (なし)
テキストから音声を生成 POST /v1/audio/speech (なし)
録音からテキストを生成 POST /v1/audio/transcriptions (なし; 録音は file に入ります)

ソース画像は、https:// リンク、data: URI (data:image/png;base64,iVBORw0…)、または PNG、JPEG、WebP のプレーンな base64 で、1リクエストあたり最大 8 です。画像ルートは、マルチパートアップロード (下記参照) も受け付けます。リンクは公開 https:// リンクである必要があります。http:// リンクは拒否されます。リダイレクトするリンク (例: https://picsum.photos/640/360) は、最大 5 回まで、他の公開 https:// リンクにのみ追跡され、モデルは最終的に到達したリンクを受け取ります。画像に繋がらないリンク、または使用できない場所にリダイレクトするリンクは、保留または課金される前に 400 invalid_image_url で拒否されます。インラインで送信された画像はリクエストを大きくします。10 MB 未満に抑えるか、リンクを送信してください。

チャットメッセージ (messages[].content の image_url) では、リンク (https:// または http://) は MartLLM によって開かれ、ほとんどのビジョンモデルがそれのみを受け付けるため、data: URL としてモデルに送信されます。各画像は最大 20 MB (1リクエストあたり 40 MB) で、リダイレクトは最大 5 回まで、公開アドレスにのみ追跡されます。Gemini モデルはリンクをそのまま受け取ります。画像に繋がらないリンクは 400 invalid_image_url で拒否され、何も課金されません。

画像を生成する

画像は回答として返されます。

curl https://api.martllm.com/v1/images/generations \
  -H "Authorization: Bearer $UBERLLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "venice/z-image-turbo", "prompt": "a red apple on a white table", "n": 1, "size": "1024x1024"}'
{ "created": 1792429247, "data": [{ "url": "https://api.martllm.com/v1/media/artifacts/<id>/0" }],
  "usage": { "cost_usd": 0.0099, "max_cost_usd": 0.0109 } }

usage.cost_usdが画像の費用です (X-UberLLM-Cost-USDヘッダーにも記載されています)。価格がまだ不明な稀な回答では、nullとなります。プロバイダーが請求した金額をお支払いいただきますが、そのために保留されたmax_cost_usdを超えることはありません。

response_formatは、/v1/images/generationsと/v1/images/editsの両方で、デフォルトでurlです。代わりに、回答内に画像を含めるには"response_format": "b64_json"を送信してください。モデルが画像自体を返した場合、MartLLMはそれをアカウントのファイルとして24時間保持し、そのリンク(https://api.martllm.com/v1/files/file_…/content)で回答します。このリンクは、後の編集の元画像としても機能します。同じキーでURLをダウンロードしてください:

curl -L -o image.png -H "Authorization: Bearer $UBERLLM_API_KEY" \
  "https://api.martllm.com/v1/media/artifacts/<id>/0"

nは1から10です。

画像を編集する

画像を編集するモデル(そのIDは通常-editで終わります)を使用し、ソース画像をimageで送信します:

curl https://api.martllm.com/v1/images/edits \
  -H "Authorization: Bearer $UBERLLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "google/nano-banana-pro-edit", "prompt": "make the sky a sunset",
       "image": "https://example.com/skyline.png"}'

同じ画像を以下のように入力できます:

  • "image": "data:image/png;base64,iVBORw0…"
  • "image_url": "https://…"
  • "input_images": ["https://…", "https://…"]: 最初の画像は編集対象の画像で、残りは参照画像です。エントリは{"url": "…", "role": "reference"}にすることもできます。
  • "images": [{"image_url": "https://…"}]、OpenAI SDKが送信する形式

プレーンなbase64も機能し、"input_image"は"image"として読み取られます。

または、OpenAIの画像編集のようにファイルをアップロードします:

curl https://api.martllm.com/v1/images/edits \
  -H "Authorization: Bearer $UBERLLM_API_KEY" \
  -F model=google/nano-banana-pro-edit -F prompt="make the sky a sunset" \
  -F [email protected]

ソース画像がない編集は400 image_requiredで拒否されます。マスク(インペインティング)はサポートされていません。

画像を一度アップロード

画像を/v1/filesにアップロードすると、各リクエストで送信する代わりに、24時間好きなだけ多くのリクエストでその画像を使用できます。

curl https://api.martllm.com/v1/files \
  -H "Authorization: Bearer $UBERLLM_API_KEY" \
  -F [email protected]
{ "id": "file_3f9c…", "object": "file", "bytes": 482113, "content_type": "image/png",
  "filename": "skyline.png", "created_at": 1792540800, "expires_at": 1792627200,
  "url": "https://api.martllm.com/v1/files/file_3f9c…/content" }

その後、ID、またはurlを、ソース画像が配置される場所ならどこにでも配置します。例えば、"image": "file_3f9c…"、"image": {"file_id": "file_3f9c…"}、"image_url": "file_3f9c…"、input_imagesのエントリ、または動画の開始フレームなどです。あなたのアカウントのみがそのファイルを使用できます。

  • PNG、JPEG、WebP、GIF、HEIC、またはAVIF形式で、各ファイル最大10 MB。アカウントごとに一度に最大500個まで保持されます。
  • 24時間保持され、その後削除されます。GET /v1/files/{id}で説明を確認し、GET /v1/files/{id}/contentでダウンロードし、DELETE /v1/files/{id}で今すぐ削除できます。

ビデオを作成する

ビデオの作成には1分以上かかるため、これは作業です:開始し、確認し、ダウンロードします。

1. 開始する

curl https://api.martllm.com/v1/video/generations \
  -H "Authorization: Bearer $UBERLLM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"model": "fal-ai/vidu/q3/text-to-video/turbo", "prompt": "a red ball bouncing on green grass",
       "duration_seconds": 5, "models": ["fal-ai/kling-video/v3/standard/text-to-video"]}'

modelsはオプションです:最初のモデルに現在無料のプロバイダーがない場合にのみ、バックアップモデルが順番に試行されます。これにより、混雑時でもリクエストが失敗することはありません(フォールバックモデル]を参照)。上記のビデオは約1分かかり、費用は約$0.33です。

画像から開始するには、画像からビデオへのモデルを使用し、image_urlを追加します:

  -d '{"model": "bytedance/seedance-2-0-image-to-video", "prompt": "slow push-in as the waves roll",
       "image_url": "https://example.com/first-frame.png", "duration_seconds": 5}'

2枚の画像をブレンドするモデルもend_image_url(最後のフレーム)を取ります。テキストのみからビデオを作成できない画像からビデオへのモデルまたは参照からビデオへのモデルは、リクエストに画像がない場合、課金される前に400 image_requiredで拒否されます。参照からビデオへのモデルは、画像をinput_imagesで受け取ります:

  -d '{"model": "pixverse/pixverse-c1-reference-to-video", "prompt": "the cat walks across the room",
       "input_images": [{"url": "https://example.com/cat.png", "role": "reference"}],
       "aspect_ratio": "16:9", "duration_seconds": 5}'

モデルが提供するその他のフィールド:resolution(480p、720p、1080p…)、aspect_ratio(16:9、9:16、1:1…)、およびaudio(true / false;サウンド設定のないモデルには送信されず、常に通りにクリップを作成します)。

スキーマにaspect_ratiosがリストされていない画像からビデオへのモデル(ほとんどのKling、Veo、Wan、Seedanceの画像からビデオへのモデル)は、ソース画像の形状でクリップを作成します。希望する形状の画像を送信し(縦型クリップの場合は9:16にトリミング)、aspect_ratioを省略してください。そのようなモデルに送信された形状は、課金される前に400 invalid_requestと回答されます("aspect_ratio": "auto"は受け入れられ、省略するのと同じ意味です)。

参照からビデオへのモデルは形状を必要とするため、aspect_ratioを省略すると16:9として送信されます(または、モデルが16:9を作成しない場合はその最初の形状);モデルのスキーマにそのデフォルトが表示されます。各モデルの選択肢はGET /v1/models/<model id>によってリストされています(各モデルのオプション]を参照)。

各モデルは特定のクリップの長さ、解像度、形状のみを作成します。作成できないものに対するリクエストは、課金される前に、作成できるものをリストしたメッセージとともに拒否されます。

HTTP 202:

{
  "id": "6f1c…",
  "object": "media.job",
  "kind": "video",
  "status": "queued",
  "model": "fal-ai/vidu/q3/text-to-video/turbo",
  "estimated_cost_usd": 0.32725,
  "estimated_cost_usdc": "327250",
  "max_cost_usd": 0.359975,
  "max_cost_usdc": "359975",
  "poll_url": "/v1/video/generations/6f1c…",
  "cancel_url": "/v1/video/generations/6f1c…"
}

modelはジョブを引き受けたモデルです(最初のモデルができなかった場合のmodelsからのバックアップ)。_usdcで終わる費用は100万分の1ドル単位です(327250 = $0.33)。estimated_cost_usdは予想される価格です。これは、リクエストしたものの表示価格から始まります(数値validateとPOST /v1/quoteはcost_usdとして回答します:現在のモデルの価格に、要求された解像度での秒数、画像、またはその他の単位を掛けたもの)。ジョブを引き受けた販売者が、あなたのリクエストに対してそれ以上の料金を請求すると予想する場合、代わりにestimated_cost_usdがその販売者の数値になります。通常はこの最初の返信から、遅くとも実行中のジョブの後のGETで(一部のジョブは開始後数秒で販売者が決まり、別の販売者に移動したジョブはその販売者の価格になります)。これは常に上昇するだけで、max_cost_usdを超えることはありません。ジョブはプロバイダーが請求した金額で課金されます。通常は見積もり以下ですが、まれにそれ以上になることもあります(販売者が終了時にのみ価格を設定する画像から作成されたクリップなど)。max_cost_usdはジョブのために残高から保留される金額です。実行中も終了後も同じ数値であり、ジョブに課金される最大額です。開始した販売者がジョブを失い、別の販売者が引き継いだ場合でも、これを超える金額が課金されることはありません。あなたのmax_cost_usdを超える費用がかかる販売者は使用されません。secondあたりの価格のビデオモデルは、クリップの秒数ごとに課金されます。jobあたりの価格のモデルは、ビデオごとにその費用がかかります。

2. 確認する 5~10秒ごとに:

curl -H "Authorization: Bearer $UBERLLM_API_KEY" \
  https://api.martllm.com/v1/video/generations/<job id>

ジョブの実行中はHTTP 202、終了後はHTTP 200:

{
  "id": "6f1c…",
  "status": "succeeded",
  "results": [{ "artifact_index": 0, "url": "https://api.martllm.com/v1/media/artifacts/6f1c…/0",
                "content_type": "video/mp4", "duration_seconds": 5 }],
  "usage": { "cost_usdc": "40000", "cost_usd": 0.04 }
}

モデルは、ファイルが準備できてから少し後、通常は30秒以内にジョブの正確な料金を報告します。それまでは、succeededジョブは"usage": { "cost_usd": null, "cost_pending": true }と表示されます。数秒後に再度問い合わせてください。料金が30分以内に届かない場合、ジョブは表示価格(estimated_cost_usd)で課金され、usage.cost_noteがその旨を伝えます。

3. ダウンロードする

curl -L -o video.mp4 -H "Authorization: Bearer $UBERLLM_API_KEY" \
  https://api.martllm.com/v1/media/artifacts/<job id>/0

不要になったジョブを停止するよう依頼します:DELETE /v1/video/generations/<job id>。プロバイダーに停止を依頼します。すでに作成されたジョブは通常通り課金され、停止されたジョブはcanceledで終了し、費用はかかりません。

Falビデオモデル

IDがfal-ai/で始まるモデルはFalで動作し、Falの正規料金よりも安くご利用いただけます。お客様はFalの料金から、現在マーケットプレイスで最も安いFal販売者の割引を差し引いた額をお支払いいただきます(2026年10月30日では15%オフ、その販売者が販売している場合は常に25%オフとなります)。料金は、お客様のご要望に応じて決定されます。具体的には、秒数 × 解像度ごとの料金、およびクリップに音声があるかどうかによって決まります。そのため、ジョブの開始時にその費用がわかり、請求される金額はestimated_cost_usdと全く同じです。失敗したジョブには費用はかかりません。ジョブの停止はベストエフォートです。Falがすでにクリップを作成している場合、その費用は請求されます。

curl https://api.martllm.com/v1/video/generations \
  -H "Authorization: Bearer $UBERLLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "fal-ai/wan/v2.7/text-to-video", "prompt": "a woman twirls at a garden party at night",
       "duration_seconds": 15, "resolution": "720p", "aspect_ratio": "9:16"}'

Falの正規料金(1秒あたり)(お客様の料金は、この正規料金からリアルタイム割引を差し引いたものです。各モデルのページ(GET /v1/modelsおよびPOST /v1/quote)で現在の正確な料金をご確認いただけます):

モデル 長さ(秒) Falの1秒あたりの料金(開始価格)
fal-ai/wan/v2.7/text-to-video, …/image-to-video 2–15 720p $0.10 · 1080p $0.15
fal-ai/kling-video/v3/standard/text-to-video, …/image-to-video 3–15 $0.084 · with sound $0.126
fal-ai/kling-video/v3/pro/text-to-video, …/image-to-video 3–15 $0.112 · with sound $0.168
fal-ai/kling-video/o3/standard/text-to-video, …/image-to-video 3–15 $0.084 · with sound $0.112
fal-ai/kling-video/v2.6/pro/text-to-video, …/image-to-video 5, 10 $0.07 · with sound $0.14
fal-ai/veo3.1/fast, fal-ai/veo3.1/fast/image-to-video 4, 6, 8 720p/1080p $0.10 · with sound $0.15 · 4k $0.30
fal-ai/veo3.1, fal-ai/veo3.1/image-to-video 4, 6, 8 720p/1080p $0.20 · with sound $0.40 · 4k $0.40
fal-ai/veo3.1/lite 4, 6, 8 720p $0.03 · with sound $0.05 · 1080p $0.05
fal-ai/ltx-2.3/text-to-video/fast, …/image-to-video/fast 6, 8, 10 1080p $0.06 · 1440p $0.12 · 2160p $0.24
fal-ai/ltx-2.3/text-to-video 6, 8, 10 1080p $0.08
fal-ai/minimax/hailuo-02/standard/text-to-video, …/image-to-video 6, 10 768P $0.045 · 512P (image) $0.017
fal-ai/vidu/q3/text-to-video/turbo, …/image-to-video/turbo 1–16 360p/540p $0.035 · 720p/1080p $0.077
fal-ai/vidu/q3/text-to-video, …/image-to-video 1–16 360p/540p $0.07 · 720p/1080p $0.154

各料金はFalの正規料金です。割引はジョブ開始時に適用されます。最も安い販売者がジョブを拒否した場合、より高価な販売者がそれを実行し、ジョブはその販売者の料金で請求されます。ただし、返信時のestimated_cost_usdを超えることはありません。

一部のモデルは、販売者の割引表示よりも当社にとって費用が安くなります。6時間ごとに、過去7日間にマーケットプレイスが各モデルに対して当社に請求した金額を、同じジョブに対するFalの料金と比較します。その期間に少なくとも20件のジョブがあったモデルは、その実際のシェアに5%を加えた価格で提供されます(それがより低い場合)。モデルページ、/v1/models、および請求書はすべて同じ料金を使用します。その数値が3日以上古い場合、販売者の割引が再度適用されます。

フィールドは当社独自のものです: duration_seconds, resolution, aspect_ratio, audio および image_url (または input_images)。Fal独自のスペル(duration, generate_audio, start_image_url)も機能します。Kling, Veo, および Kling 2.6 は、"audio": falseを送信しない限り音声を追加します。

ジョブステータス

status HTTP 意味
queued 202 受付完了。モデルの開始待ちです
running 202 生成中。モデルからの報告に応じてprogressが0から1へと進みます
succeeded 200 完了。results[].urlをダウンロードしてください
failed 200 生成されませんでした。error.messageに理由が、error.retryableに再試行で成功する可能性があるかが示されます
canceled 200 生成前に停止されました
expired 200 時間内に完了しませんでした

ステータスはこの6種類のみです。failed、canceled、expiredでは料金は発生しません。DELETEは停止のリクエストであり、確約ではありません。プロバイダー側でそのまま完了したジョブはsucceededとなり、請求対象となります。

混雑時は自動で再試行されます。 動画を生成できるプロバイダーに空きがない場合や一時的に混雑している場合、MartLLMは10分以内に最大2回まで自動でジョブを再開します。ジョブIDや上限料金はそのまま維持されます。ジョブの完了に少し時間がかかるだけです。すべての試行が失敗した場合にのみfailedが表示され、失敗したジョブには料金がかかりません。

完了を待つには。 callback_urlを送信すると、ジョブの終了時にお知らせします(コールバックを参照)。または、ポーリングURLへ5〜10秒おきに問い合わせることもできます。ほとんどの動画は1〜5分で完了しますが、長尺のものや4Kのジョブではそれ以上かかる場合があります。請求を確定させるために問い合わせを続ける必要はありません。確認されなかったジョブでもMartLLM側で完了・請求(または返金)が行われ、ダッシュボード → API Keys → API使用状況に表示されます。

コールバック

ビデオまたは音楽のジョブにcallback_urlを追加します。これは公開ホスト上のhttps://リンクです。 ジョブが完全に終了すると、MartLLMはジョブでGETが返すのと同じJSONを含めて、それにPOSTを送信します。

{ "model": "kling/kling-o3", "prompt": "a red ball bouncing", "duration_seconds": 5,
  "callback_url": "https://your-app.example/uberllm/jobs" }
  • いつ。 ジョブが終了し、請求が確定したときに一度だけ送信されます。usage.cost_usdが設定されたsucceeded(cost_pendingはなし)、またはfailed、canceled、expired(費用0)の場合です。費用が到着したときに再度送信されることはありません。これは、費用到着後にのみ送信されるためです。output_upload_urlの場合も、コールバックはアップロードが完了した後に届くため、output_upload.statusはすでにdeliveredまたはfailedになっています。
  • ヘッダー。 Content-Type: application/json、MartLLM-Event: job.succeeded(またはjob.failed、job.canceled、job.expired)、UberLLM-Event-Id: <job id>:<status>、およびUberLLM-Signature: t=<unix seconds>,v1=<hex>。
  • 再試行。 15秒以内に任意の2xxで応答してください。それ以外の応答、または応答がない場合は、30秒後、2分後、10分後、30分後、2時間後に再試行され、その後は諦められます。ジョブはいつでもポーリングできます。
  • 繰り返し。 メッセージは複数回届くことがあります(例えば、あなたの応答が失われた場合など)。イベントIDは同じままなので、すでに処理したものは破棄してください。
  • ステータス。 ジョブはどのように進行したかを示します: "callback": { "status": "delivered", "attempts": 1, "http_status": 200, "delivered_at": 1792540990 }。statusはpending、delivered、またはfailedです(errorは平易な言葉で)。
  • リンクは公開ホスト上のhttps://である必要があり、ユーザー名やパスワードを含めてはいけません。それは決して表示されず、コールバックが終了すると削除されます。webhook_urlは同じフィールドとして読み取られます。画像と音声はこれを受け取りません。それらは応答自体で返されます。

署名を確認する

すべてのメッセージは、あなたのアカウントのwebhook secretで署名されています。それはダッシュボード → API keys → Webhook signing secret]で見つけることができます。最初に開いたときに作成され、シークレットを置き換えるですぐに交換できます。

v1は、シークレット全体(whsec_…)をキーとする、<t>.<raw body>の16進HMAC-SHA256です。受信した生のバイト(JSONをパースする前)に対して計算し、定数時間で比較し、5分以上古いtは拒否してください。

Node.js (Express):

import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.UBERLLM_WEBHOOK_SECRET; // whsec_…

app.post("/uberllm/jobs", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("UberLLM-Signature") || "";
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=", 2)));
  const expected = crypto.createHmac("sha256", SECRET)
    .update(`${parts.t}.`).update(req.body).digest("hex");
  const ok = parts.v1 && parts.v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected)) &&
    Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  if (!ok) return res.status(400).send("bad signature");
  const job = JSON.parse(req.body);
  // Drop a repeat: req.get("UberLLM-Event-Id") is the same each time.
  console.log(job.id, job.status, job.usage?.cost_usd);
  res.sendStatus(204);
});

Python (Flask):

import hashlib, hmac, os, time
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["UBERLLM_WEBHOOK_SECRET"].encode()  # whsec_…

@app.post("/uberllm/jobs")
def uberllm_job():
    raw = request.get_data()  # the raw bytes, before any JSON parsing
    parts = dict(p.split("=", 1) for p in request.headers.get("UberLLM-Signature", "").split(",") if "=" in p)
    expected = hmac.new(SECRET, parts.get("t", "").encode() + b"." + raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(parts.get("v1", ""), expected) or abs(time.time() - int(parts.get("t", "0"))) > 300:
        abort(400)
    job = request.get_json()
    # Drop a repeat: request.headers["UberLLM-Event-Id"] is the same each time.
    print(job["id"], job["status"], job.get("usage", {}).get("cost_usd"))
    return "", 204

ウェブフックへのアラート

アラートメールはウェブフックにも送信できます。ダッシュボード → クレジット → 開発者向け: アラートもウェブフックに送信する]でリンクを設定するか、PUT /api/v1/billing/alerts {"alerts_webhook_url": "https://…"}(nullでオフになります)を設定してください。 メッセージはコールバックと同じ方法で署名され、再試行され、識別されます。ボディは次のとおりです。

{ "id": "evt_…", "object": "event", "type": "balance.low", "created": 1792540990,
  "data": { "balance_usd": 4.2, "threshold_usd": 5, "message": "Your balance is $4.20, below the $5.00 you set. Requests stop once it runs out.",
            "add_credits_url": "https://martllm.com/dashboard/credits" } }
  • balance.low: 残高が低残高メール用に設定した金額を下回りました。金額を下回るたびに一度送信されます。金額を設定するまでは何も送信されません。
  • hold.not_released: ジョブ終了後15分以上経過しても、ジョブのために確保された資金がまだ保留されています。data.jobsがそれら(id、kind、model、ended_at、held_usd)をリストし、data.held_usdが合計です。その資金はまだあなたのものです。弊社のチームには通知済みです。

ファイルの保持期間

結果が作成されたらすぐにダウンロードしてください。

  • 動画および音楽ファイルは、ジョブ終了後約3時間保持されます。
  • /v1/media/artifacts/…への画像リンクは約15分保持されます。/v1/files/…への画像リンクは24時間保持されます。回答内に画像を取得して自分で保持するには、"response_format": "b64_json"を要求してください。
  • /v1/filesにアップロードした画像は24時間保持されます。

その後、ダウンロードは404 artifact_expiredと応答します。

結果を独自のストレージに送信する

動画または音楽のジョブにoutput_upload_urlを追加します。これは、署名済みS3, R2やGoogle Cloud Storageのuploadリンクなど、HTTP PUTを受け入れるhttps://リンクです。ジョブが成功すると、MartLLMはファイルとそのcontent typeをそこにuploadします。複数のファイルを作成するジョブの場合、output_upload_urlsを送信します。これは、ファイルごとに1つのリンクを順番に指定するものです(最大4)。

{ "model": "kling/kling-o3", "prompt": "a red ball bouncing", "duration_seconds": 5,
  "output_upload_url": "https://my-bucket.s3.amazonaws.com/ball.mp4?X-Amz-Signature=…" }

その後のジョブのstatusにはoutput_uploadが含まれます。

"output_upload": { "status": "delivered", "attempts": 1, "delivered_at": 1792540990,
  "files": [{ "artifact_index": 0, "http_status": 200, "bytes": 5242880 }] }
  • statusはuploadが完了するまでpendingであり、その後deliveredまたはfailedになります(errorは平易な言葉で)。
  • 失敗したuploadは、30秒後、2, 10、および30分後に再試行され、その後failedとマークされます。ファイルは保持されている間、results[].urlから引き続きダウンロードできます。リンクは少なくとも1時間有効にしてください。
  • リンクは、ユーザー名やpasswordを含まず、public host上でhttps://である必要があります。それは決して表示されず、uploadが完了すると削除されます。
  • 画像はこれを受け入れません。画像は回答自体の中に返されます。

音楽

/v1/music/generationsと同じ3つのステップです。 curl -OJは、私たちが送信するファイル名でトラックを保存します。

音声

テキストを入力すると、音声ファイルが応答として返されます。

curl https://api.martllm.com/v1/audio/speech \
  -H "Authorization: Bearer $UBERLLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "x-ai/tts-xai-v1", "input": "Hello from MartLLM."}' \
  -o speech.mp3

voice、response_format(例えばmp3またはwav)、そしてspeedも送信できます。 各モデルには独自の音声があります(GET /v1/models/{id}に一覧があります)。 best-price:speechまたはfastest:speechを使用する場合、どのモデルが使用されるか事前にわからないため、音声はそれに合わせて調整されます。モデルが持つ音声は維持され、OpenAIの音声名は、モデルが対応する音声を持っている場合、それにマッピングされ(alloy → af_alloy)、その他の音声、または指定がない場合は、モデルの最初の音声が使用されます。モデル名を指定した場合、あなたの音声はそのまま送信されます。 inputの1K文字開始ごとに課金されます。応答は音声ファイルです。そのX-UberLLM-Cost-USDヘッダーには費用が記載されており、X-Request-Idはアクティビティに記載されているリクエストIDです。"validate": true、max_cost、metadata、models、およびprovider.max_priceは、画像の場合と同様に機能します(お支払いについて]を参照してください)。

録音をテキスト化する

録音をfileとmodelを含むフォームとして送信します:

curl https://api.martllm.com/v1/audio/transcriptions \
  -H "Authorization: Bearer $UBERLLM_API_KEY" \
  -F model=venice/whisper-large-v3 \
  -F [email protected]
{ "text": "Hello from MartLLM.", "duration": 4.2,
  "usage": { "type": "duration", "seconds": 5, "cost_usd": 0.00055, "max_cost_usd": 0.00726 } }

費用はusage.cost_usdです(X-UberLLM-Cost-USDヘッダーにも記載されており、text、srt、vttの回答はそこでのみ確認できます)。当社の独自のフィールドもフォームに含まれますが、モデルには送信されません:-F max_cost=0.10、-F "metadata[project]=podcast"、-F validate=true。

language、prompt、temperature、response_formatも送信できます:

response_format 得られるもの
json (デフォルト) { "text": …, "duration": …, "usage": … }
text プレーンテキストとして単語
srt タイミング情報付きのキャプションファイル (SubRip)。ビデオエディターや広告にすぐに使用できます
vtt WebVTTと同じキャプション
verbose_json jsonの回答に加えてsegments (id、start、end、text、秒単位) と、単語ごとにタイミングを計るモデルの場合はwords
curl https://api.martllm.com/v1/audio/transcriptions \
  -H "Authorization: Bearer $UBERLLM_API_KEY" \
  -F model=venice/whisper-large-v3 -F response_format=srt -F [email protected] -o captions.srt
1
00:00:00,330 --> 00:00:03,150
This serum is the one thing I use every morning.

2
00:00:03,300 --> 00:00:06,420
It took two weeks to see a change, now I never skip it.

venice/whisper-large-v3は1文につき1つのキャプションを提供します。elevenlabs/elevenlabs-scribe-v2はすべての単語のタイミングを計り、キャプションは最大42文字の行に分割され、各文の後に新しい行が開始されます。モデルが録音のタイミング情報を送信しない場合、srt、vtt、verbose_jsonは400 timestamps_unavailableと回答し、料金は発生しません。フォーマットに関わらず、音声の1分ごとに課金されます。ファイルは最大40 MBです。フォーマット (mp3, wav, ogg, flac, m4a/mp4, webm, aac) は、ファイル名ではなく録音自体から読み取られるため、tmp123.outという名前のアップロードでも機能します。

OpenAI SDKを使って

from openai import OpenAI

client = OpenAI(base_url="https://api.martllm.com/v1", api_key="<your MartLLM key>")

speech = client.audio.speech.create(model="x-ai/tts-xai-v1", voice="eve", input="Hello from MartLLM.")
speech.write_to_file("speech.mp3")

with open("speech.mp3", "rb") as f:
    text = client.audio.transcriptions.create(model="venice/whisper-large-v3", file=f)
print(text.text)

お支払いについて

  • 作成されたものの料金:プロバイダーが請求した金額で、MartLLMの手数料はかかりません。画像または文字起こしの回答、および完了したジョブには、usage.cost_usd (米ドル) として表示されます。何かを作成したすべての回答には、X-UberLLM-Cost-USD レスポンスヘッダーにも表示されます(音声の場合、回答はオーディオファイルであるため、ヘッダーが唯一の場所です)。これはダッシュボード → アクティビティで確認できます。保留された残りの金額は返金されます。
  • failed、canceled、expired のいずれかに該当するジョブ、または画像、音声、文字起こしリクエストが失敗した場合は、料金はかかりません。
  • お客様が要求されたものを正確に作成する最も安価な販売者。多くの画像および動画モデルには複数の販売者がいます。各リクエストは、お客様の設定で作成できる最も安価な販売者に送られ、それが受け付けられない場合は別の販売者に送られます。モデルリストと各モデルページには、現在利用可能な最も安価な販売者の価格が表示されます。
  • APIキーのルーティング設定(ダッシュボード → API keys)は、より高速な販売者がいる場合に販売者を選択します。Lowest priceは常に最も安価な販売者を選択します。デフォルトは、失敗し続ける場合や、最速の販売者の2倍以上遅い場合を除き、最も安価な販売者を選択します。Balancedは、最速の販売者より最大で20%遅い最も安価な販売者を選択します。そしてFastestは、モデルの表示価格までの範囲で、最も迅速な販売者を選択します。見積もりとジョブのestimated_cost_usdには、お客様の設定が選択した販売者の価格が表示されます。APIキーのルーティング設定]をご覧ください。
  • 残高と保留中の金額は、GET /v1/balance(下記)で確認できます。

利用前に料金を確認する

画像、動画、音楽、または音声のリクエストに"validate": trueを追加してください(文字起こしの場合、録音ファイルとともにフォームフィールドとしてvalidate=trueを送信してください)。リクエストは実際のものとしてチェックされ(モデル、オプション、ソース画像)、何も作成されず、料金も請求されません。HTTP 200は、表示価格(cost_usd、モデルページに表示されている価格。プロバイダーが請求した金額を支払うため、異なる場合があります)での費用と、実行中に保留される金額(max_cost_usd、最大請求額)を示します。

{ "object": "quote", "model": "bytedance/seedance-2-0-image-to-video", "kind": "video",
  "valid": true, "cost_usd": 0.2117, "max_cost_usd": 0.4235, "unit": "second", "units": 5, "duration_seconds": 5,
  "note": "Nothing was charged. …" }

モデルの販売者がお客様が省略した設定を必要とする場合(動画参照モデルがaspect_ratioを必要とする場合など)、送信されるデフォルト値はモデルのスキーマと見積もりでdefaults_appliedとして表示されます(例:"defaults_applied": {"aspect_ratio": "16:9"})。

拒否されるリクエストは、理由とともに同じ方法で拒否されます。

15分間、価格を保留する

POST /v1/quoteは、画像、動画、音楽、または音声リクエストと同じボディを受け取り、表示価格(cost_usd)、実行中に保留される金額(max_cost_usd、最大請求額)、およびquote_idを返します(文字起こしの場合、modelとduration_secondsを送信してください。文字起こし自体はquote_idを必要とせず、max_costを使用して上限を設定します)。

curl https://api.martllm.com/v1/quote \
  -H "Authorization: Bearer $UBERLLM_API_KEY" -H "Content-Type: application/json" \
  -d '{"model": "kling/kling-o3", "prompt": "a red ball bouncing", "duration_seconds": 5}'
{ "object": "quote", "id": "6f1c…", "quote_id": "6f1c…", "model": "kling/kling-o3",
  "kind": "video", "cost_usd": 0.225, "max_cost_usd": 0.495, "unit": "job", "units": 1,
  "expires_at": 1792541700, "note": "Nothing was charged. …" }

15分以内に"quote_id": "6f1c…"と同じリクエストを送信すると、プロバイダーが請求した金額が、最大でmax_cost_usdまで請求されます。開始時に保留する必要がある金額がmax_cost_usdを超える場合、料金はかからずにキャンセルされます。見積もり自体には料金は請求されず、金額も保留されません。

  • 1つの見積もりは1つのリクエストを開始します。再度使用すると409 quote_usedが返されます。モデルに到達しなかったジョブは見積もりを返します。
  • リクエストは同じ内容を要求する必要があります:同じモデルと、同じ設定(プロンプト、サイズ、クリップ長、ソース画像など)。それ以外は400 quote_mismatchで拒否されます。max_cost、metadata、output_upload_urlは異なる場合があります。
  • 15分後には400 quote_expiredが返されます。チャットモデルはトークンごとに課金され、見積もりはありません。provider.max_priceで上限を設定してください。

フォールバックモデルと価格上限

"models": ["model-b", "model-c"]は、最初のモデルが現在サービスを提供できない(no_available_provider)場合や、お客様のprovider.max_priceを超える場合に、試行するモデルを順番に指定します。その他の拒否はすぐに回答されます。回答のmodelは、それを作成したモデルの名前を示します(音声回答はオーディオファイル自体です。アクティビティでそのモデルが表示されます)。quote_idを含むリクエストはmodelsを必要とせず、文字起こしはどちらも必要としません。

"provider": {"max_price": 0.05}は、1ユニット(モデルの料金設定unit:画像、秒、メガピクセル、分、1K文字、またはリクエスト)が米ドルでかかる最大費用です。これを超えるモデルは400 max_price_exceededで拒否され、リクエストはユニットのmax_price倍を超える金額で請求されることはありません。メディアリクエストの販売者選択はリクエストごとに制御できないため、他のproviderオプションは400 unsupported_routing_optionで拒否されます。

"model": "best-price:image"(またはimage-edit、text-to-video、image-to-video、music、speech、transcription)は、ジョブに最適な最も安価なライブモデルを選択します。fastest:は、測定された中で最も迅速なモデルを選択します。モデルエイリアス]をご覧ください。

タグ

"metadata": {"project": "spring-ads"}(最大16個のテキスト値)はジョブとともに保存され、そのステータスで返され、アクティビティおよびCSVエクスポートに表示され、モデルに送信されることはありません。文字起こしの場合、フォームフィールドとして送信してください:-F "metadata[project]=spring-ads"。タグ]をご覧ください。

上限を設定する

画像、動画、音楽、または音声のリクエスト(文字起こしの場合はフォームフィールド)とともに、"max_cost"(米ドル、例:0.50)を送信してください。それ以上の費用がかかる可能性がある場合、400 max_cost_too_lowで拒否され、料金は請求されません。動画または音楽のジョブの場合、正確な上限はジョブ開始時に設定されます。その後、お客様のmax_costを超えることが判明した場合、料金はかからずにジョブはキャンセルされます。"validate": trueを使用すると、見積もりにwithin_max_costが追加されます。

二重課金なしで再試行する

動画または音楽のジョブを開始する際に、Idempotency-Keyヘッダー(UUIDのような、最大255文字の一意の文字列)を送信してください。接続が切断され、24時間以内に同じキーで同じリクエストを再度送信した場合、2つ目のジョブではなく、同じジョブが返されます。異なるリクエストで同じキーを使用すると、409 idempotency_key_reusedで拒否されます。画像、音声、文字起こしのリクエストはキーを必要としません。失敗したものは課金されていないため、再度送信してください。

残高

curl -H "Authorization: Bearer $UBERLLM_API_KEY" https://api.martllm.com/v1/balance
{ "balance_usd": 12.40, "held_usd": 0.35, "available_usd": 12.05 }

held_usd は実行中のリクエストのために確保されています。それらが終了すると(実際にかかった費用を差し引いて)戻ってきます。available_usd は新しいリクエストが利用できる金額です。

各モデルのオプション

GET /v1/models?type=image(またはvideo、music、speech、transcription、 その両方ならaudio、chat、all。複数はカンマで区切ります。type を指定しない場合、一覧はチャットモデルのみです)は、今すぐ呼び出せるモデルを一覧表示します。各モデルには、それぞれの type、送信先の endpoints、そしてその pricing が付きます。GET /v1/models/<model id> は 1 つのモデルを返し、メディアモデルの場合は、受け付けるクリップの長さ、解像度、アスペクト比、サイズ、必要なソース画像を示すリクエストボディの JSON Schema である parameters オブジェクトを返します。

curl -H "Authorization: Bearer $UBERLLM_API_KEY" \
  https://api.martllm.com/v1/models/pixverse/pixverse-c1-reference-to-video

pricing には usd(現在、1 つの unit にかかる最高額)と list_usd(モデル提供元自身の価格)があります。チャットモデルには input_usd、output_usd、およびそれらの list_ 価格(1M tokens あたり)があります。

usd は、そのモデルへの通常のリクエストに現在提示される価格です。キーをバランス(デフォルト)に設定したときにリクエストが向かう販売元の価格で、当社の手数料を含みます。一覧と見積もりは同じコードで計算され、販売元の一時停止、停止、価格変更に約 30 秒以内に追随します。

解像度ごとに価格が決まるモデルには resolutions もあります:解像度ごとに 1 行(動画なら 480p / 720p / 1080p、画像なら 1K / 2K / 4K)で、安い順に並び、各行には usd(その解像度で 1 秒、または 1 枚にかかる提示価格)と list_usd が付きます。上記の usd は最も安い行です。クリップは、要求した解像度の価格にその秒数を掛けて請求されます:

"pricing": {"usd": 0.100884, "unit": "second", "resolutions": [
  {"resolution": "480p", "usd": 0.100884, "list_usd": 0.1287},
  {"resolution": "720p", "usd": 0.2268, "list_usd": 0.289},
  {"resolution": "1080p", "usd": 0.56133, "list_usd": 0.7107}]}

販売元によっては、1 秒ではなくクリップ全体で価格を設定しています。そのような行には seconds も付きます:その usd が 1 秒あたりの価格となるクリップの長さです。これは最も高いレート(モデルの最短クリップ)なので、長いクリップの費用は usd × 秒数より安くなり、長さを指定しないリクエストには正確に usd × seconds が提示されます。seconds は、1 つの長さだけで解像度が販売されている場合にも表示されます。

{"resolution": "720p", "usd": 0.062344, "list_usd": 0.075, "seconds": 4}

1 秒あたりの価格は、最も近い $0.000001 に丸められます。リクエストの正確な価格については、見積もり("validate": true)を取得してください。

エラー

HTTP コード 意味
400 wrong_endpoint 例:画像モデルを/v1/video/generationsに送信した、チャットモデルを画像ルートに送信した、または音声モデルを/v1/audio/transcriptionsに送信した。メッセージには正しいパスが示されます。料金は請求されず、アクティビティには拒否として表示されます
400 invalid_request リクエストが間違っています(メッセージに理由が示されます。例:モデルが提供しない期間、またはソース画像がない場合)
400 image_required 編集、または画像から動画、参照から動画のモデルで、ソース画像がない場合
400 max_cost_too_low max_costを超える費用がかかる可能性があります。料金は請求されませんでした
400 timestamps_unavailable タイミングを送信しなかった文字起こしモデルにsrt、vtt、またはverbose_jsonを要求しました。料金は請求されませんでした
409 idempotency_key_reused そのIdempotency-Keyは別のリクエストに使用されました
400 quote_mismatch / quote_expired リクエストが見積もりと異なります、または見積もりが15分以上経過しています
404 quote_not_found あなたのアカウントに見積もりはありません
409 quote_used その見積もりはすでにリクエストを開始しています
400 max_price_exceeded このモデルは、provider.max_priceよりも単位あたりのコストが高くなります
400 unsupported_routing_option max_price以外のproviderオプション
404 file_not_found あなたのアカウントにそのようなアップロードファイルはありません、または期限切れです
413 file_too_large 10 MBを超えるアップロード
429 too_many_files すでに500個のアップロードが保持されています。一部を削除するか、期限切れになるまでお待ちください
503 files_unavailable 現在、アップロードは利用できません
413 request_too_large リクエストがサイズ制限(40 MB)を超えています。画像をhttps://リンクとして送信し、長い録音は分割してください
402 insufficient_credits 残高がジョブの最大コストをカバーできません。メッセージに必要な金額が示されます
404 model_not_found / not_found そのようなモデルはありません、またはあなたのアカウントにそのようなジョブはありません
404 artifact_expired ファイルは保持されていません(上記参照)
429 rate_limited Retry-Afterで示された秒数(存在しない場合は数秒)待ってから、再試行してください。X-RateLimit-Remainingは、この1分間に残っているリクエスト数を示します
503 no_available_provider 現在、どの販売者も作成できません。MartLLMはすでに他の販売者を試しました。メッセージには、現在機能している同種のモデルが示されます