OpenAlchemyOpenAlchemy
ドキュメント

API リファレンス

オープンなプロバイダーネットワーク上で動く OpenAI 互換の推論。任意の OpenAI SDK をベース URL に向けるだけで、既存のコードはそのまま、使った分だけクレジットで支払えます。

はじめに

#

主要なエンドポイントは OpenAI の /v1/* 形式と 1 対 1 で対応しています。OpenAI の Python / Node SDK の base_url を差し替えるだけで、アプリケーションの他の部分は変更不要です。OpenAlchemy 独自の拡張(ボイス、音声透かし、画像、動画、OCR、衣服セグメンテーション)はその旨を明記しています。

OpenAI との違いは 3 点です。

  • 支払いはクレジットで行います(1 クレジット = 0.001 米ドル)。チャージは /billing から。機能ごとの料金は料金ページに掲載しています。
  • すべての JSON レスポンスに x_openalchemy ブロックが含まれ、リクエスト ID、ワーカー ID、エンジンのレイテンシ、使用量の内訳がわかります。デバッグやコストの把握に役立ちます。
  • 推論は、実際の GPU を動かす独立したプロバイダーが処理します。/models のモデルカタログで、モデルごとの現在の稼働状況を確認できます。

認証

#

API はBearer トークンで認証します。キーは /api-keys で発行してください。キーは作成時に一度だけ表示され、当社はソルト付きハッシュのみを保存します。パスワードと同様に扱ってください。

すべてのリクエストに Authorization ヘッダーが必要です。キーは利用できるモデルを限定でき、範囲外のモデルへのリクエストは 403 model_not_allowed を返します。

有効なキーをブラウザのバンドル、モバイルアプリ、公開 Git リポジトリに含めないでください。キーが漏えいした場合は、ただちに /api-keys で失効させてください。

ヘッダー
Authorization: Bearer $OPENALCHEMY_API_KEY

ベース URL

#

必要なネットワークエンドポイントはこれだけです。

HTTPShttps://api.openalchemy.io

API を呼び出すには /v1/… を付けます。サーバーがワーカーを選んでリクエストを送り、結果を返し、完了時に課金します。すべて同じレスポンスの中で完結します。

Python SDK
# Python — works for chat, vision, embeddings, audio.
from openai import OpenAI
client = OpenAI(
    base_url="https://api.openalchemy.io/v1",
    api_key=os.environ["OPENALCHEMY_API_KEY"],
)

レスポンスのメタデータ

#

すべての JSON レスポンスには x_openalchemy ブロックが含まれます。標準の SDK は未知のフィールドを無視するため既存のコードには影響しませんが、デバッグ時にまず確認すべき場所です。

  • request_id ── 問い合わせの際にお伝えください。
  • worker_id ── 処理したプロバイダー。
  • engine_latency_ms ── ネットワークを除いた GPU の処理時間。
  • usage.cost ── 引き落とされたクレジット(固定小数点の文字列)。

/logs ページでは同じフィールドが記録されており、リクエストを横断して検索できます。

レスポンスの構造
{
  "id": "cmpl-…",
  "object": "chat.completion",
  "model": "llama-3.1-70b-instruct",
  "choices": [ … ],
  "usage": { "prompt_tokens": 24, "completion_tokens": 19, "total_tokens": 43 },
  "x_openalchemy": {
    "request_id": "req_01HG…",
    "tier": "m",
    "worker_id": "wrk_4f…",
    "engine_request_id": "vllm-…",
    "engine_latency_ms": 412,
    "upstream_latency_ms": 438,
    "usage": {
      "input_tokens": 24,
      "output_tokens": 19,
      "total_tokens": 43,
      "cost": "0.000086"
    }
  }
}

エンドポイント一覧

#

公開しているすべてのエンドポイントです。各パスをベース URLの後ろに付けて呼び出します。下の各エンドポイントの説明に移動するか、モデルカタログで各エンドポイントに対応するモデルを確認してください。

モデル一覧の取得

#
GET/v1/models

ネットワークが現在提供しているすべてのモデルを、稼働状況・ティア・機能のメタデータとともに返します。endpoint_type で絞り込み(chat / embedding / rerank / stt / tts / image / video など)、live_workers でフォールバックの判断ができます。

リクエスト
curl https://api.openalchemy.io/v1/models \
  -H "Authorization: Bearer $OPENALCHEMY_API_KEY"
レスポンス
{
  "object": "list",
  "data": [
    {
      "id": "llama-3.1-70b-instruct",
      "object": "model",
      "endpoint_type": "chat",
      "tier": "m",
      "family": "llama-3.1",
      "context_window": 131072,
      "params_b": 70,
      "live_workers": 4,
      "online": true
    },
    …
  ]
}

チャット補完

#
POST/v1/chat/completions

会話に対するモデルの応答を生成します。最も基本となる OpenAI 互換のエンドポイントです。

OpenAI v1 互換 ── 任意の OpenAI SDK で `base_url` とキーを差し替えるだけ。

リクエストボディ
名前型説明
model必須string/v1/models で取得したモデル ID。
messages必須array<{role, content}>会話のターン。role は system / user / assistant。
temperaturenumber 0–2
既定値 1
サンプリング温度。
top_pnumber 0–1
既定値 1
Nucleus サンプリングの累積確率。
max_tokensinteger
既定値 2048
生成する最大トークン数。
presence_penaltynumber -2…2
既定値 0
既に出現したトークンにペナルティを与えます。
frequency_penaltynumber -2…2
既定値 0
出現頻度に応じてトークンにペナルティを与えます。
stopstring | string[]生成を停止するシーケンス。
response_format{ type: 'text' | 'json_object' }JSON 出力を強制します。
streamboolean
既定値 false
Server-Sent Events でストリーミングします。最後のチャンクに usage が含まれます。
レスポンス
{
  "id": "cmpl-…",
  "object": "chat.completion",
  "model": "<model>",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "…" },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": N, "completion_tokens": N, "total_tokens": N },
  "x_openalchemy": {
    "request_id": "req_…",
    "tier": "s",
    "worker_id": "…",
    "engine_latency_ms": …,
    "usage": { "input_tokens": N, "output_tokens": N, "cost": "0.0008" }
  }
}
エラー
401invalid_api_keyBearer トークンがない、形式が不正、または失効しています。
402insufficient_balance見積もり費用が利用可能な残高を超えています。
403model_not_allowedこの API キーは指定したモデルの利用を許可されていません。
404model_not_foundモデル ID が登録されていません。
429rate_limitedキーごとの RPM または TPM の上限を超えました。
503no_workers_for_model現在このモデルを提供している Grid ワーカーがありません。
503model_not_pricedこのモデルのティアにはまだ料金が設定されていません。
502engine_unreachable推論エンジンに接続できないか、タイムアウトしました。
curl https://api.openalchemy.io/v1/chat/completions \
  -H "Authorization: Bearer $OPENALCHEMY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "llama-3.1-70b-instruct",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "Say hi in one sentence."
    }
  ],
  "temperature": 0.7,
  "max_tokens": 256
}'
プレイグラウンドで試す→
リクエストをその場で調整し、生成されたコードをコピーできます。

画像入力(Vision)

#
POST/v1/chat/completions

チャット補完と同じエンドポイントに画像パーツを含めて送ります。画像入力に対応したモデルを使ってください。

OpenAI Vision 形式 ── /v1/models から画像入力に対応したモデルを選んでください。

リクエストボディ
名前型説明
model必須string画像入力に対応したモデル ID。
messages必須array<{role, content: (string | ContentPart[])}>各パーツは {type:'text', text} または {type:'image_url', image_url:{url, detail}}。
image_url.urlstringhttps://… の URL または data:image/...;base64,…(base64 後で 1 枚あたり約 6 MB まで)。
image_url.detail'low' | 'auto' | 'high'
既定値 'auto'
low:1 枚あたり一律 85 トークン。high:85 + 170 × タイル数(768×768 で約 765)。
temperaturenumber 0–2
既定値 0.2
チャットと同じ。
max_tokensinteger
既定値 1024
チャットと同じ。
レスポンス
// Same shape as /v1/chat/completions.
// x_openalchemy.usage.image_tokens is the per-request image token total.
エラー
401invalid_api_keyBearer トークンがない、形式が不正、または失効しています。
402insufficient_balance見積もり費用が利用可能な残高を超えています。
403model_not_allowedこの API キーは指定したモデルの利用を許可されていません。
404model_not_foundモデル ID が登録されていません。
429rate_limitedキーごとの RPM または TPM の上限を超えました。
503no_workers_for_model現在このモデルを提供している Grid ワーカーがありません。
503model_not_pricedこのモデルのティアにはまだ料金が設定されていません。
curl https://api.openalchemy.io/v1/chat/completions \
  -H "Authorization: Bearer $OPENALCHEMY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "qwen2.5-vl-72b",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What'\''s in this image?"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://images.example.com/cat.jpg",
            "detail": "auto"
          }
        }
      ]
    }
  ],
  "max_tokens": 512
}'
プレイグラウンドで試す→
リクエストをその場で調整し、生成されたコードをコピーできます。

埋め込み

#
POST/v1/embeddings

1 件または複数の文字列を、検索・クラスタリング・RAG 向けの密ベクトルに変換します。

OpenAI Embeddings v1 互換。

リクエストボディ
名前型説明
model必須string埋め込みモデル ID。
input必須string | string[]埋め込む文字列(1 件または配列)。
dimensionsintegerMatryoshka 学習済みモデルでは、ベクトルをこの次元数に切り詰めます。それ以外では無視されます。
encoding_format'float' | 'base64'
既定値 'float'
返却されるベクトルの形式。
レスポンス
{
  "object": "list",
  "data": [
    { "object": "embedding", "embedding": [0.0123, -0.045, …], "index": 0 },
    …
  ],
  "model": "<model>",
  "usage": { "prompt_tokens": N, "total_tokens": N },
  "x_openalchemy": { "usage": { "input_tokens": N, "cost": "…" } }
}
エラー
401invalid_api_keyBearer トークンがない、形式が不正、または失効しています。
402insufficient_balance見積もり費用が利用可能な残高を超えています。
403model_not_allowedこの API キーは指定したモデルの利用を許可されていません。
404model_not_foundモデル ID が登録されていません。
429rate_limitedキーごとの RPM または TPM の上限を超えました。
503no_workers_for_model現在このモデルを提供している Grid ワーカーがありません。
503model_not_pricedこのモデルのティアにはまだ料金が設定されていません。
curl https://api.openalchemy.io/v1/embeddings \
  -H "Authorization: Bearer $OPENALCHEMY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "nomic-embed-text-v1.5",
  "input": [
    "The quick brown fox",
    "jumps over the lazy dog"
  ]
}'
プレイグラウンドで試す→
リクエストをその場で調整し、生成されたコードをコピーできます。

リランク

#
POST/v1/rerank

クエリに対して N 件の候補文書を並べ替えます。Cohere 互換のリクエスト形式です。

Cohere /v2/rerank 互換(`model`、`query`、`documents`、`top_n`)。

リクエストボディ
名前型説明
model必須stringリランカーのモデル ID。
query必須string検索クエリ。
documents必須string[] | { text: string }[]並べ替える候補文書。
top_ninteger上位 N 件のみ返します。省略時はすべて。
return_documentsboolean
既定値 false
レスポンスに各文書のテキストを含めます。
レスポンス
{
  "results": [
    { "index": 2, "relevance_score": 0.97 },
    { "index": 0, "relevance_score": 0.81 },
    …
  ],
  "x_openalchemy": {
    "usage": {
      "query_tokens": Q,
      "document_tokens": Σ,
      "total_tokens": Q + Σ,
      "cost": "…"
    }
  }
}
エラー
401invalid_api_keyBearer トークンがない、形式が不正、または失効しています。
402insufficient_balance見積もり費用が利用可能な残高を超えています。
403model_not_allowedこの API キーは指定したモデルの利用を許可されていません。
404model_not_foundモデル ID が登録されていません。
429rate_limitedキーごとの RPM または TPM の上限を超えました。
503no_workers_for_model現在このモデルを提供している Grid ワーカーがありません。
503model_not_pricedこのモデルのティアにはまだ料金が設定されていません。
curl https://api.openalchemy.io/v1/rerank \
  -H "Authorization: Bearer $OPENALCHEMY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "bge-reranker-v2-m3",
  "query": "What is OpenAlchemy?",
  "documents": [
    "OpenAlchemy is a distributed inference network where independent providers run open models for credits.",
    "Cats are popular household pets.",
    "Workers connect to the grid and serve OpenAI-compatible traffic."
  ],
  "top_n": 2
}'
プレイグラウンドで試す→
リクエストをその場で調整し、生成されたコードをコピーできます。

音声認識(文字起こし)

#
POST/v1/audio/transcriptions

音声からテキストへ。音声ファイルを multipart でアップロードし、Whisper 互換のレスポンスを返します。

OpenAI Whisper v1 互換。multipart/form-data。

フォームフィールド(multipart/form-data)
名前型説明
file必須binarymp3 / wav / m4a / webm / flac。1 リクエスト 25 MB まで。
model必須string音声認識モデル ID。
languagestringISO-639-1(例:'en'、'ja')。省略時は自動判定。
promptstring認識を寄せるための任意のテキスト。専門用語に有効です。
response_format'json' | 'text' | 'srt' | 'vtt' | 'verbose_json'
既定値 'json'
出力形式。
temperaturenumber 0–1
既定値 0
サンプリング温度(通常は不要)。
レスポンス
// json:
{ "text": "…transcript…" }

// verbose_json (adds duration + segments):
{ "text": "…", "duration": 12.34, "language": "en", "segments": [ … ] }

// srt / vtt: plain text subtitle file in the matching format.
エラー
401invalid_api_keyBearer トークンがない、形式が不正、または失効しています。
402insufficient_balance見積もり費用が利用可能な残高を超えています。
403model_not_allowedこの API キーは指定したモデルの利用を許可されていません。
404model_not_foundモデル ID が登録されていません。
429rate_limitedキーごとの RPM または TPM の上限を超えました。
503no_workers_for_model現在このモデルを提供している Grid ワーカーがありません。
503model_not_pricedこのモデルのティアにはまだ料金が設定されていません。
curl https://api.openalchemy.io/v1/audio/transcriptions \
  -H "Authorization: Bearer $OPENALCHEMY_API_KEY" \
  -F file=@/path/to/audio.mp3 \
  -F model=whisper-large-v3 \
  -F response_format=json
プレイグラウンドで試す→
リクエストをその場で調整し、生成されたコードをコピーできます。

音声合成

#
POST/v1/audio/speech

テキストから音声へ。音声バイナリを返し、使用量のメタデータはレスポンスヘッダーに入ります。

OpenAI TTS v1 互換。現在の出力は WAV です。

リクエストボディ
名前型説明
model必須string音声合成モデル ID。
input必須string合成するテキスト。
voicestringボイス ID ── 組み込みボイスまたは自分のクローンボイス。GET /v1/audio/voices で一覧できます。
response_format'wav' | 'mp3' | 'opus'
既定値 'wav'
音声コンテナ。mp3 / opus はエンジン側の変換対応まで 501 を返します。
speednumber 0.5–2.0
既定値 1
再生速度の倍率。
streamboolean
既定値 false
生成しながらチャンク WAV を返します(低遅延再生)。途中で切断しても生成済みの分は課金されます。
レスポンス
// Body is binary audio (Content-Type: audio/wav).
// Inspect the response headers:
//   X-Openalchemy-Request-Id
//   X-Openalchemy-Audio-Seconds
//   X-Openalchemy-Cost
//   X-Engine-Request-Id   (pass to /v1/audio/speech/cancel)
エラー
401invalid_api_keyBearer トークンがない、形式が不正、または失効しています。
402insufficient_balance見積もり費用が利用可能な残高を超えています。
403model_not_allowedこの API キーは指定したモデルの利用を許可されていません。
404model_not_foundモデル ID が登録されていません。
429rate_limitedキーごとの RPM または TPM の上限を超えました。
503no_workers_for_model現在このモデルを提供している Grid ワーカーがありません。
503model_not_pricedこのモデルのティアにはまだ料金が設定されていません。
curl https://api.openalchemy.io/v1/audio/speech \
  -H "Authorization: Bearer $OPENALCHEMY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "cosyvoice2",
  "input": "Hello from OpenAlchemy.",
  "voice": "en_alice",
  "response_format": "wav"
}' \
  --output speech.wav
プレイグラウンドで試す→
リクエストをその場で調整し、生成されたコードをコピーできます。

音声合成のキャンセル

#
POST/v1/audio/speech/cancel

進行中の /v1/audio/speech の合成を止め、ワーカーの GPU を解放します。ベストエフォートで、常に 202 を返します。送信済みの音声分は課金されます。

OpenAlchemy 独自拡張(OpenAI のエンドポイントではありません)。

リクエストボディ
名前型説明
request_id必須string/v1/audio/speech が返した X-Engine-Request-Id(またはその呼び出しで指定した X-Request-Id)。
レスポンス
// 202 Accepted (empty body)
エラー
401invalid_api_keyBearer トークンがない、形式が不正、または失効しています。
cURL
curl -X POST https://api.openalchemy.io/v1/audio/speech/cancel \
  -H "Authorization: Bearer $OPENALCHEMY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"request_id": "<X-Engine-Request-Id>"}'

ボイス

#
POST/v1/audio/voices

組み込みボイスと自分のクローンボイスの一覧、短い参照音声からのボイスクローン作成(ゼロショット、すぐに利用可能)、クローンの参照音声の取得、クローンの削除を行います。

OpenAlchemy 独自拡張。クローンボイスは自分のアカウントでのみ利用できます。

エンドポイント
GET/v1/audio/voices組み込みボイスとクローンボイスの一覧:{data: [{id, name, kind, language}]}。
POST/v1/audio/voicesボイスをクローンします(multipart のフィールドは下表)。
GET/v1/audio/voices/{voice_id}/clipクローンボイスの参照音声(audio_b64)と書き起こし。自分のクローンのみ。
DELETE/v1/audio/voices/{voice_id}自分のクローンボイスを削除します。組み込みボイスは削除できません。
フォームフィールド(multipart/form-data)
名前型説明
file必須binary参照音声(WAV または MP3、20 MB まで)。
name必須string1〜64 文字(英数字、_、-)。これがボイス ID になります。
language必須stringzh、en、ja、zh_en、ja_en、zh_ja のいずれか。
reference_text必須string参照音声の正確な書き起こし。
レスポンス
// GET /v1/audio/voices
{ "data": [
  { "id": "en_alice", "name": "en_alice", "kind": "builtin", "language": "en" },
  { "id": "my_voice", "name": "my_voice", "kind": "cloned",  "language": "ja" }
] }

// POST /v1/audio/voices
{ "id": "my_voice", "name": "my_voice", "kind": "cloned", "language": "ja", "status": "ready" }
エラー
401invalid_api_keyBearer トークンがない、形式が不正、または失効しています。
400invalid_namename が 1〜64 文字の英数字・_・- ではありません。
400invalid_languagelanguage が対応している値ではありません。
404not_foundその ID のクローンボイスがアカウントにありません。
cURL
curl https://api.openalchemy.io/v1/audio/voices \
  -H "Authorization: Bearer $OPENALCHEMY_API_KEY" \
  -F file=@reference.wav \
  -F name=my_voice \
  -F language=ja \
  -F reference_text="こんにちは、今日はいい天気ですね。"

音声透かし

#
POST/v1/audio/watermark/embed

音声に聞こえない 16 ビットの透かしを埋め込む/検出します(AudioSeal)。音声の秒数で課金します。

OpenAlchemy 独自拡張(OpenAI のエンドポイントではありません)。

エンドポイント
POST/v1/audio/watermark/embed透かし入りのファイルそのものを、送信と同じ形式(audio/mpeg または audio/wav)で返します。リクエスト ID・message・費用はレスポンスヘッダーに入ります。
POST/v1/audio/watermark/detect透かしの有無、確信度、復号した message を返します。
リクエストボディ
名前型説明
audio_b64必須stringWAV または MP3 音声の base64(50 MB まで)。data: URL も可。
messageinteger 0–65535embed でのみ使用(embed では必須):埋め込む 16 ビットの値。コンテンツとの対応付けは利用者側で行います。
レスポンス
// embed → audio bytes; headers:
//   X-OpenAlchemy-Request-Id, X-OpenAlchemy-Cost,
//   X-Watermark-Message, X-Audio-Seconds

// detect →
{ "watermarked": true, "confidence": 0.98, "message": 4242,
  "x_openalchemy": { "request_id": "req_…", "worker_id": "…",
                     "usage": { "audio_seconds": 12, "cost": "…" } } }
エラー
400missing_audioaudio_b64 が指定されていないか空です。
400bad_messageembed:message は 0〜65535 の整数である必要があります。
401invalid_api_keyBearer トークンがない、形式が不正、または失効しています。
402insufficient_balance見積もり費用が利用可能な残高を超えています。
413audio_too_large音声が 50 MB を超えています。
cURL
curl https://api.openalchemy.io/v1/audio/watermark/embed \
  -H "Authorization: Bearer $OPENALCHEMY_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"audio_b64\": \"$(base64 -w0 song.mp3)\", \"message\": 4242}" \
  -o song.watermarked.mp3

画像生成

#
POST/v1/images/local/generations

Grid 上の GPU で PNG を 1 枚生成します。生成が終わると JSON を返します(ストリーミングなし)。

OpenAI Images 形式のリクエスト/レスポンスを独自パスで提供します。SDK では client.post('/images/local/generations', …) を使ってください(images.generate() は別のパスを呼びます)。

リクエストボディ
名前型説明
modelstring/v1/models の画像モデル(endpoint_type=image)。
prompt必須string画像の説明(1〜32,000 文字)。
ninteger
既定値 1
1 のみ(1 リクエストにつき 1 枚)。
sizestring
既定値 1024x1024
WIDTHxHEIGHT。16 の倍数で、各辺 1536 まで。
response_formatstring
既定値 b64_json
b64_json のみ。data[0].b64_json をデコードすると PNG が得られます。
seedinteger0〜4294967295。省略時はランダム。
stepsinteger
既定値 4
サンプリングステップ数(1〜50)。
guidance_scalenumber
既定値 4
ガイダンススケール(0〜30)。
レスポンス
{
  "created": 1713833628,
  "data": [{ "b64_json": "<base64 PNG>" }],
  "x_openalchemy": {
    "request_id": "…", "worker_id": "…", "provider": "local",
    "usage": { "images": 1, "cost": "…" }
  }
}
エラー
401invalid_api_keyBearer トークンがない、形式が不正、または失効しています。
402insufficient_balance見積もり費用が利用可能な残高を超えています。
403model_not_allowedこの API キーは指定したモデルの利用を許可されていません。
404model_not_foundモデル ID が登録されていません。
422validation_error未対応または不正なパラメーター(quality、background、output_format、stream、mask は非対応)。
502engine_unreachable推論エンジンに接続できないか、タイムアウトしました。
cURL
curl https://api.openalchemy.io/v1/images/local/generations \
  -H "Authorization: Bearer $OPENALCHEMY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a lighthouse at dusk, watercolor", "size": "1024x1024"}'

画像編集

#
POST/v1/images/local/edits

参照画像 1 枚とプロンプトから PNG を生成します。multipart/form-data で送信し、編集のたびに参照画像をアップロードします。

OpenAI Images の編集機能のうち参照画像 1 枚の部分のみを独自パスで提供します。mask と複数画像には非対応です。

フォームフィールド(multipart/form-data)
名前型説明
image必須filePNG / JPEG / WebP を 1 枚、25 MiB まで(フィールド名 image)。
modelstring/v1/models の画像モデル(endpoint_type=image)。
prompt必須string画像の説明(1〜32,000 文字)。
ninteger
既定値 1
1 のみ(1 リクエストにつき 1 枚)。
sizestring
既定値 1024x1024
WIDTHxHEIGHT。16 の倍数で、各辺 1536 まで。
response_formatstring
既定値 b64_json
b64_json のみ。data[0].b64_json をデコードすると PNG が得られます。
seedinteger0〜4294967295。省略時はランダム。
stepsinteger
既定値 4
サンプリングステップ数(1〜50)。
guidance_scalenumber
既定値 4
ガイダンススケール(0〜30)。
レスポンス
{
  "created": 1713833628,
  "data": [{ "b64_json": "<base64 PNG>" }],
  "x_openalchemy": {
    "request_id": "…", "worker_id": "…", "provider": "local",
    "usage": { "images": 1, "cost": "…" }
  }
}
エラー
401invalid_api_keyBearer トークンがない、形式が不正、または失効しています。
402insufficient_balance見積もり費用が利用可能な残高を超えています。
403model_not_allowedこの API キーは指定したモデルの利用を許可されていません。
404model_not_foundモデル ID が登録されていません。
422validation_error未対応または不正なパラメーター(quality、background、output_format、stream、mask は非対応)。
502engine_unreachable推論エンジンに接続できないか、タイムアウトしました。
400empty_image参照画像が空です。
413image_too_large参照画像が 25 MiB を超えています。
cURL
curl https://api.openalchemy.io/v1/images/local/edits \
  -H "Authorization: Bearer $OPENALCHEMY_API_KEY" \
  -F image=@input.png \
  -F prompt="same scene, at night"

動画生成

#
POST/v1/videos

Grid の GPU で動画ショットを 1 本生成します。モデル:minimax-h3(音声付き 4〜15 秒、768P。still: true で PNG キーフレーム 1 枚)、wan2.2-s2v(キーフレーム+音声から歌唱・発話ショット、480P / 576P / 720P)、wan2.2-i2v(キーフレームがプロンプトどおりに動く、2〜10 秒・16 fps、480P / 576P / 720P)、wan2.2-animate(キーフレームのキャラクターが参照動画の動きを演じる、480P)、latentsync-1.6(完成したクリップの口を新しい音声に合わせ直す)。minimax-h3 も audio_url を受け取れます(mode ref では声、t2v / i2v ではサウンドトラック)。非同期処理です。POST は 202 と id を返すので、status が succeeded になるまで GET /v1/videos/{id} をポーリングし、output.url または GET /v1/videos/{id}/content から取得します。

Kie の MiniMax H3 API に合わせた形の OpenAlchemy 独自拡張。モデル・解像度ごとの単価で出力秒数に課金します(still は 1 枚ごと)。送信時に見積額全額を確保し、失敗またはキャンセル時に解放します。ベータ版。

エンドポイント
POST/v1/videosショットを送信 → 202 {id, status: "queued"}。オンラインのワーカーがない場合は即座に 503 no_video_worker を返し、課金されません。
GET/v1/videosこのプロジェクトでの自分のショット(新しい順)。クエリ:limit(1〜100、既定 20)、after(前ページの last_id)、status。
GET/v1/videos/availability?model=今すぐショットを開始できるか:available、workers_online、workers_free、queue_depth。model は minimax-h3(mode ref では minimax-h3-ref)、wan2.2-s2v、wan2.2-i2v、wan2.2-animate、latentsync-1.6。
GET/v1/videos/{id}status、stage、progress(サンプリングの進捗 0〜100%)、credits、成功後は短時間有効な output.url を含む output。
GET/v1/videos/{id}/content短時間有効な署名付き mp4 URL へ 302 リダイレクト。成功するまでは 409、保存期間(既定 7 日)を過ぎると 410。
POST/v1/videos/{id}/cancel待機中または実行中のショットをキャンセルします。確保したクレジットは全額解放されます。
リクエストボディ
名前型説明
modelstring
既定値 "minimax-h3"
minimax-h3、wan2.2-s2v、wan2.2-i2v、wan2.2-animate、latentsync-1.6。
modestring
既定値 "t2v"
minimax-h3:t2v(プロンプトのみ)、i2v(先頭・末尾フレーム)、ref(参照画像 1〜9 枚。プロンプト内で <Picture 1>、<Picture 2>… として参照)。wan2.2-s2v:s2v。wan2.2-i2v:i2v。wan2.2-animate:animate。latentsync-1.6:lipsync。
prompt必須stringショットの内容(音も含む)。8,000 文字まで。latentsync-1.6 では使いません。
durationinteger 4–15
既定値 5
minimax-h3:長さ(秒、24 fps)。still では省略。wan2.2-s2v:省略(長さは音声に一致、2〜45 秒)。wan2.2-i2v:2〜10 秒(既定 5、16 fps)。wan2.2-animate:任意。参照動画の先頭から N 秒(既定はクリップ全体、2〜30 秒)。latentsync-1.6:省略(長さは音声に一致)。
resolutionstring
既定値 "768P"
minimax-h3:768P のみ(2K は 422)。wan2.2-s2v:480P(既定)、576P、720P(解像度ごとに秒単価が異なります)。wan2.2-i2v:480P(既定)、576P、720P。wan2.2-animate:480P。latentsync-1.6:省略(入力動画のサイズのまま)。
aspect_ratiostring
既定値 "16:9"
t2v と ref で使用。i2v はフレームの比率に従います。
seedinteger固定すると同じ出力を再現できます。省略時はランダム。
first_frame_urlstringi2v(minimax-h3、wan2.2-i2v)、s2v、animate:開始フレーム(PNG/JPEG)の https URL、base64、または data: URL。
last_frame_urlstringi2v:終了フレーム。
reference_image_urlsstring[] (1–9)ref:参照画像(https、base64、または data: URL)。
stillboolean
既定値 false
minimax-h3 の t2v / ref:動画の代わりに PNG キーフレームを 1 枚生成(1 枚ごとの課金)。control_image_url(ポーズ・深度・線画テンプレート)と control_strength 0〜2 を任意で指定できます。
audio_urlstringwan2.2-s2v:駆動音声(wav / mp3 / aac、https または data: URL、50 MB 以下、2〜45 秒)。first_frame_url がキーフレーム。音声は 16 fps の出力に多重化されます。latentsync-1.6:新しい音声(wav / mp3 / aac / m4a、20 MB 以下、0.5 秒以上、動画より 0.5 秒を超えて長くしない)。minimax-h3(30 秒以下、still では不可):mode ref ではプロンプトで <Audio 1> と呼ぶ声、t2v / i2v では最初のフレームから合わせるサウンドトラックのガイド(最終的な音声は H3 が生成)。クリップの長さは duration のまま。
driving_video_urlstringwan2.2-animate:演じさせる動き(mp4 / mov / webm、https または data: URL、50 MB 以下)。出力と同じアスペクト比が必要(異なると 422 driving_aspect_mismatch)。first_frame_url がキャラクター。出力に音声はありません。
video_urlstringlatentsync-1.6:口を合わせ直すクリップ(mp4 / mov / webm、https または data: URL、50 MB 以下、30 秒以下)。映像はそのままで口の部分だけが変わります。出力は 25 fps で audio_url の音声を多重化。
stepsinteger 1–50モデル既定値の代わりに使うサンプリングステップ数(minimax-h3 8、mode ref 4、wan2.2-s2v 4(turbo false では 20)、wan2.2-i2v 6、wan2.2-animate 4)。生成時間と品質が変わりますが、価格は変わりません。
turboboolean
既定値 true
wan2.2-s2v のみ:false で 4 ステップ蒸留 LoRA を使わずに生成します(フルサンプラー、20 ステップ、CFG 6。数倍遅くなりますがベースモデルに近い画質)。他のモデルで false は 400 turbo_not_supported。
レスポンス
// POST /v1/videos → 202
{ "id": "video_…", "object": "video", "status": "queued", "model": "minimax-h3",
  "mode": "t2v", "duration": 5, "resolution": "768P", "estimated_credits": "…" }

// GET /v1/videos/{id}
{ "id": "video_…", "object": "video",
  "status": "running",      // queued | running | uploading | succeeded | failed | cancelled
  "stage": "rendering",     // queued | evicting | uploading_frames | rendering | decoding | storing; null once finished
  "progress": 37,           // sampling percent 0–100 (0 until sampling starts, 100 when succeeded)
  "credits": null,          // settled credits once succeeded
  "output": null,           // when succeeded:
  //  { "mime_type": "video/mp4", "duration": 5, "width": 1344, "height": 768, "fps": 24,
  //    "has_audio": true, "bytes": 2400000, "seed": 7, "expires_at": 1760600000,
  //    "url": "https://…signed…", "url_expires_in": 900 }
  "error": null }           // { "code", "message" } when failed / cancelled

// GET /v1/videos?limit=20&after=video_…&status=succeeded
{ "object": "list", "data": [ /* same shape as GET /v1/videos/{id} */ ],
  "has_more": true, "first_id": "video_…", "last_id": "video_…" }

// GET /v1/videos/availability?model=minimax-h3
{ "object": "video.availability", "model": "minimax-h3",
  "available": true, "workers_online": 2, "workers_free": 1, "queue_depth": 0 }
エラー
400invalid_durationduration が 4〜15 秒の範囲外です。
400invalid_modemode が t2v / i2v / ref のいずれでもありません。
400missing_promptprompt が空です。
400invalid_stepssteps が 1〜50 の範囲外です。
400turbo_not_supportedwan2.2-s2v 以外のモデルに turbo: false が指定されました。
400invalid_resolutionモデルが対応していない resolution です(resolution を参照)。
422driving_aspect_mismatchwan2.2-animate:参照動画のアスペクト比が aspect_ratio と異なります。
400audio_needs_s2vstill: true と一緒に、または音声を受け取らないモデルに audio_url が指定されました。
400audio_longer_than_videolatentsync-1.6:音声が動画より 0.5 秒を超えて長いです。
400invalid_after一覧:after が自分の動画の ID ではありません。
401invalid_api_keyBearer トークンがない、形式が不正、または失効しています。
402insufficient_balance見積額に対してクレジットが不足しています。
403model_not_allowedこの API キーは指定したモデルの利用を許可されていません。
404not_foundこのアカウントで動画生成がまだ有効になっていないか、ID が存在しません。
409video_not_readyショットの成功前にコンテンツを要求しました。
410video_expired出力の保存期間を過ぎています。
422resolution_not_supported2K が指定されました。768P のみ対応しています。
422reference_video_not_supportedreference_video_urls にはまだ対応していません。
503no_video_worker現在このモデル/モードに対応する GPU ワーカーがオンラインではありません。即座に返され、課金されません。
cURL
# 1. Submit
curl https://api.openalchemy.io/v1/videos \
  -H "Authorization: Bearer $OPENALCHEMY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "minimax-h3", "mode": "t2v", "prompt": "waves on a pebble beach, gulls calling", "duration": 5}'

# 2. Poll until "status": "succeeded"
curl https://api.openalchemy.io/v1/videos/video_… \
  -H "Authorization: Bearer $OPENALCHEMY_API_KEY"

# 3. Download
curl -L https://api.openalchemy.io/v1/videos/video_…/content \
  -H "Authorization: Bearer $OPENALCHEMY_API_KEY" -o shot.mp4

OCR(文字認識)

#
POST/v1/ocr

画像または PDF からテキストを抽出します。PDF はページごとに画像化して認識します(50 ページまで)。ページ単位で課金します。

OpenAlchemy 独自拡張(OpenAI のエンドポイントではありません)。画像について質問するには、画像対応モデルで /v1/chat/completions を使います。

リクエストボディ
名前型説明
modelstring
既定値 "paddleocr"
paddleocr(高速、行ごとのボックス付き)または /v1/models の画像対応モデル ID。
image_b64必須string画像(PNG/JPG/WebP)または PDF の base64。data: URL も可。別名:image。
langstringPaddleOCR の言語コード(ch、en、japan、korean など)。画像対応モデルでは無視されます。
レスポンス
{
  "text": "…full recognised text…",
  // PaddleOCR — per-line text, confidence and box:
  "lines": [ { "text": "…", "score": 0.99, "box": [[x0,y0],[x1,y1],[x2,y2],[x3,y3]] } ],
  "page_count": 1,
  // PDFs — one entry per page:
  "pages": [ { "page_num": 1, "text": "…" } ],
  "x_openalchemy": { "request_id": "req_…", "worker_id": "…", "usage": { "pages": 1, "cost": "…" } }
}
エラー
400missing_imageimage_b64(または image)が指定されていないか空です。
400bad_base64ペイロードが正しい base64 ではありません。
400bad_pdfPDF を開けませんでした。
401invalid_api_keyBearer トークンがない、形式が不正、または失効しています。
402insufficient_balance見積もり費用が利用可能な残高を超えています。
403model_not_allowedこの API キーは指定したモデルの利用を許可されていません。
413too_many_pagesPDF が 50 ページを超えています。
502engine_unreachable推論エンジンに接続できないか、タイムアウトしました。
cURL
curl https://api.openalchemy.io/v1/ocr \
  -H "Authorization: Bearer $OPENALCHEMY_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\": \"paddleocr\", \"lang\": \"japan\", \"image_b64\": \"$(base64 -w0 receipt.png)\"}"

衣服セグメンテーション

#
POST/v1/garment/segment

写真に写っている衣服とその位置を検出します(SegFormer による衣服パーシング)。衣服ごとにマスクの重心を 1 点返します。画像単位で課金します。

OpenAlchemy 独自拡張(OpenAI のエンドポイントではありません)。

リクエストボディ
名前型説明
modelstring
既定値 "segformer-b2-clothes"
segformer-b2-clothes(高速)または segformer-b3-clothes。
image_b64必須stringPNG/JPG/WebP 写真の base64(25 MB まで)。data: URL も可。別名:image。
min_area_rationumber 0–1マスク面積が画像に占める割合がこの値未満の衣服は返しません。
レスポンス
{
  "model": "segformer-b2-clothes",
  "width": 1000, "height": 1500,
  // label: Dress | Upper-clothes | Skirt | Pants | Bag | Shoes | Hat | Scarf | Belt
  "garments": [
    { "label": "Upper-clothes", "x": 473.2, "y": 739.5, "x_norm": 0.4732, "y_norm": 0.493,
      "area_ratio": 0.0417, "bbox": [376.3, 534.7, 578.3, 931.6] }
  ],
  "x_openalchemy": { "request_id": "req_…", "worker_id": "…", "usage": { "images": 1, "cost": "…" } }
}
エラー
400missing_imageimage_b64(または image)が指定されていないか空です。
400bad_base64ペイロードが正しい base64 ではありません。
401invalid_api_keyBearer トークンがない、形式が不正、または失効しています。
402insufficient_balance見積もり費用が利用可能な残高を超えています。
403model_not_allowedこの API キーは指定したモデルの利用を許可されていません。
413image_too_large画像が 25 MB を超えています。
502engine_unreachable推論エンジンに接続できないか、タイムアウトしました。
cURL
curl https://api.openalchemy.io/v1/garment/segment \
  -H "Authorization: Bearer $OPENALCHEMY_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"image_b64\": \"$(base64 -w0 outfit.jpg)\"}"

エラー

#

エラーは OpenAI と同じ形式で、message、type、code を持つ error オブジェクトの JSON を返します。同じ HTTP ステータスに複数のコードがあるため、分岐には HTTP ステータスではなく code を使ってください。

401invalid_api_keyBearer トークンがない、形式が不正、または失効しています。
402insufficient_balance見積もり費用が利用可能な残高を超えています。
403model_not_allowedこの API キーは指定したモデルの利用を許可されていません。
404model_not_foundモデル ID が登録されていません。
429rate_limitedキーごとの RPM または TPM の上限を超えました。
503no_workers_for_model現在このモデルを提供している Grid ワーカーがありません。
503model_not_pricedこのモデルのティアにはまだ料金が設定されていません。
502engine_unreachable推論エンジンに接続できないか、タイムアウトしました。
エラーボディ
{
  "error": {
    "message": "Insufficient credit balance for this request.",
    "type": "billing_error",
    "code": "insufficient_balance"
  }
}

レート制限

#

レート制限は API キーごとに 2 つの軸で設定されます。RPM(1 分あたりのリクエスト数)と TPM(1 分あたりのトークン数、入力と出力の合計)です。どちらも既定では無料枠の上限が適用され、クレジットのチャージに応じて引き上げられます。

上限を超えると、Retry-After ヘッダー(秒)付きで 429 rate_limited を返します。OpenAI SDK は自動的にこれに従います。独自のクライアントでは、時間をおいて再試行してください。

特定のモデルで 503 no_workers_for_model が続く場合は、レート制限ではなく処理能力不足のサインです。/models から同等のモデルを選ぶか、プロバイダーを追加できるようお知らせください。

不足している情報がありますか?リクエストがうまくいかないときは /logs にメモを残してください。まずレスポンスの x_openalchemy.request_id をお伺いします。