API リファレンス
オープンなプロバイダーネットワーク上で動く OpenAI 互換の推論。任意の OpenAI SDK をベース URL に向けるだけで、既存のコードはそのまま、使った分だけクレジットで支払えます。
はじめに
#主要なエンドポイントは OpenAI の /v1/* 形式と 1 対 1 で対応しています。OpenAI の Python / Node SDK の base_url を差し替えるだけで、アプリケーションの他の部分は変更不要です。OpenAlchemy 独自の拡張(ボイス、音声透かし、画像、動画、OCR、衣服セグメンテーション)はその旨を明記しています。
OpenAI との違いは 3 点です。
認証
#API はBearer トークンで認証します。キーは /api-keys で発行してください。キーは作成時に一度だけ表示され、当社はソルト付きハッシュのみを保存します。パスワードと同様に扱ってください。
すべてのリクエストに Authorization ヘッダーが必要です。キーは利用できるモデルを限定でき、範囲外のモデルへのリクエストは 403 model_not_allowed を返します。
有効なキーをブラウザのバンドル、モバイルアプリ、公開 Git リポジトリに含めないでください。キーが漏えいした場合は、ただちに /api-keys で失効させてください。
Authorization: Bearer $OPENALCHEMY_API_KEYベース URL
#必要なネットワークエンドポイントはこれだけです。
https://api.openalchemy.ioAPI を呼び出すには /v1/… を付けます。サーバーがワーカーを選んでリクエストを送り、結果を返し、完了時に課金します。すべて同じレスポンスの中で完結します。
# 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の後ろに付けて呼び出します。下の各エンドポイントの説明に移動するか、モデルカタログで各エンドポイントに対応するモデルを確認してください。
/v1/chat/completionsストリーミングPOST/v1/chat/completions画像入力ベータGET/v1/models一覧POST/v1/embeddingsベクトルベータPOST/v1/rerankリランクベータPOST/v1/audio/transcriptions音声認識ベータPOST/v1/audio/speech音声合成ベータPOST/v1/audio/speech/cancelキャンセルベータGET/v1/audio/voicesボイスベータPOST/v1/audio/voicesクローンベータGET/v1/audio/voices/{voice_id}/clip参照音声ベータDELETE/v1/audio/voices/{voice_id}削除ベータPOST/v1/audio/watermark/embed透かし埋め込みベータPOST/v1/audio/watermark/detect透かし検出ベータPOST/v1/images/local/generations画像生成ベータPOST/v1/images/local/edits画像編集ベータPOST/v1/videos動画生成ベータGET/v1/videos一覧ベータGET/v1/videos/availability空き状況ベータGET/v1/videos/{id}ステータスベータGET/v1/videos/{id}/contentダウンロードベータPOST/v1/videos/{id}/cancelキャンセルベータPOST/v1/ocr文字認識ベータPOST/v1/garment/segment衣服検出ベータモデル一覧の取得
#/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
},
…
]
}チャット補完
#/v1/chat/completions会話に対するモデルの応答を生成します。最も基本となる OpenAI 互換のエンドポイントです。
OpenAI v1 互換 ── 任意の OpenAI SDK で `base_url` とキーを差し替えるだけ。
| 名前 | 型 | 説明 |
|---|---|---|
model必須 | string | /v1/models で取得したモデル ID。 |
messages必須 | array<{role, content}> | 会話のターン。role は system / user / assistant。 |
temperature | number 0–2既定値 1 | サンプリング温度。 |
top_p | number 0–1既定値 1 | Nucleus サンプリングの累積確率。 |
max_tokens | integer既定値 2048 | 生成する最大トークン数。 |
presence_penalty | number -2…2既定値 0 | 既に出現したトークンにペナルティを与えます。 |
frequency_penalty | number -2…2既定値 0 | 出現頻度に応じてトークンにペナルティを与えます。 |
stop | string | string[] | 生成を停止するシーケンス。 |
response_format | { type: 'text' | 'json_object' } | JSON 出力を強制します。 |
stream | boolean既定値 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" }
}
}invalid_api_keyBearer トークンがない、形式が不正、または失効しています。insufficient_balance見積もり費用が利用可能な残高を超えています。model_not_allowedこの API キーは指定したモデルの利用を許可されていません。model_not_foundモデル ID が登録されていません。rate_limitedキーごとの RPM または TPM の上限を超えました。no_workers_for_model現在このモデルを提供している Grid ワーカーがありません。model_not_pricedこのモデルのティアにはまだ料金が設定されていません。engine_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)
#/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.url | string | https://… の URL または data:image/...;base64,…(base64 後で 1 枚あたり約 6 MB まで)。 |
image_url.detail | 'low' | 'auto' | 'high'既定値 'auto' | low:1 枚あたり一律 85 トークン。high:85 + 170 × タイル数(768×768 で約 765)。 |
temperature | number 0–2既定値 0.2 | チャットと同じ。 |
max_tokens | integer既定値 1024 | チャットと同じ。 |
// Same shape as /v1/chat/completions.
// x_openalchemy.usage.image_tokens is the per-request image token total.invalid_api_keyBearer トークンがない、形式が不正、または失効しています。insufficient_balance見積もり費用が利用可能な残高を超えています。model_not_allowedこの API キーは指定したモデルの利用を許可されていません。model_not_foundモデル ID が登録されていません。rate_limitedキーごとの RPM または TPM の上限を超えました。no_workers_for_model現在このモデルを提供している Grid ワーカーがありません。model_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
}'埋め込み
#/v1/embeddings1 件または複数の文字列を、検索・クラスタリング・RAG 向けの密ベクトルに変換します。
OpenAI Embeddings v1 互換。
| 名前 | 型 | 説明 |
|---|---|---|
model必須 | string | 埋め込みモデル ID。 |
input必須 | string | string[] | 埋め込む文字列(1 件または配列)。 |
dimensions | integer | Matryoshka 学習済みモデルでは、ベクトルをこの次元数に切り詰めます。それ以外では無視されます。 |
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": "…" } }
}invalid_api_keyBearer トークンがない、形式が不正、または失効しています。insufficient_balance見積もり費用が利用可能な残高を超えています。model_not_allowedこの API キーは指定したモデルの利用を許可されていません。model_not_foundモデル ID が登録されていません。rate_limitedキーごとの RPM または TPM の上限を超えました。no_workers_for_model現在このモデルを提供している Grid ワーカーがありません。model_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"
]
}'リランク
#/v1/rerankクエリに対して N 件の候補文書を並べ替えます。Cohere 互換のリクエスト形式です。
Cohere /v2/rerank 互換(`model`、`query`、`documents`、`top_n`)。
| 名前 | 型 | 説明 |
|---|---|---|
model必須 | string | リランカーのモデル ID。 |
query必須 | string | 検索クエリ。 |
documents必須 | string[] | { text: string }[] | 並べ替える候補文書。 |
top_n | integer | 上位 N 件のみ返します。省略時はすべて。 |
return_documents | boolean既定値 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": "…"
}
}
}invalid_api_keyBearer トークンがない、形式が不正、または失効しています。insufficient_balance見積もり費用が利用可能な残高を超えています。model_not_allowedこの API キーは指定したモデルの利用を許可されていません。model_not_foundモデル ID が登録されていません。rate_limitedキーごとの RPM または TPM の上限を超えました。no_workers_for_model現在このモデルを提供している Grid ワーカーがありません。model_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
}'音声認識(文字起こし)
#/v1/audio/transcriptions音声からテキストへ。音声ファイルを multipart でアップロードし、Whisper 互換のレスポンスを返します。
OpenAI Whisper v1 互換。multipart/form-data。
| 名前 | 型 | 説明 |
|---|---|---|
file必須 | binary | mp3 / wav / m4a / webm / flac。1 リクエスト 25 MB まで。 |
model必須 | string | 音声認識モデル ID。 |
language | string | ISO-639-1(例:'en'、'ja')。省略時は自動判定。 |
prompt | string | 認識を寄せるための任意のテキスト。専門用語に有効です。 |
response_format | 'json' | 'text' | 'srt' | 'vtt' | 'verbose_json'既定値 'json' | 出力形式。 |
temperature | number 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.invalid_api_keyBearer トークンがない、形式が不正、または失効しています。insufficient_balance見積もり費用が利用可能な残高を超えています。model_not_allowedこの API キーは指定したモデルの利用を許可されていません。model_not_foundモデル ID が登録されていません。rate_limitedキーごとの RPM または TPM の上限を超えました。no_workers_for_model現在このモデルを提供している Grid ワーカーがありません。model_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音声合成
#/v1/audio/speechテキストから音声へ。音声バイナリを返し、使用量のメタデータはレスポンスヘッダーに入ります。
OpenAI TTS v1 互換。現在の出力は WAV です。
| 名前 | 型 | 説明 |
|---|---|---|
model必須 | string | 音声合成モデル ID。 |
input必須 | string | 合成するテキスト。 |
voice | string | ボイス ID ── 組み込みボイスまたは自分のクローンボイス。GET /v1/audio/voices で一覧できます。 |
response_format | 'wav' | 'mp3' | 'opus'既定値 'wav' | 音声コンテナ。mp3 / opus はエンジン側の変換対応まで 501 を返します。 |
speed | number 0.5–2.0既定値 1 | 再生速度の倍率。 |
stream | boolean既定値 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)invalid_api_keyBearer トークンがない、形式が不正、または失効しています。insufficient_balance見積もり費用が利用可能な残高を超えています。model_not_allowedこの API キーは指定したモデルの利用を許可されていません。model_not_foundモデル ID が登録されていません。rate_limitedキーごとの RPM または TPM の上限を超えました。no_workers_for_model現在このモデルを提供している Grid ワーカーがありません。model_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音声合成のキャンセル
#/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)invalid_api_keyBearer トークンがない、形式が不正、または失効しています。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>"}'ボイス
#/v1/audio/voices組み込みボイスと自分のクローンボイスの一覧、短い参照音声からのボイスクローン作成(ゼロショット、すぐに利用可能)、クローンの参照音声の取得、クローンの削除を行います。
OpenAlchemy 独自拡張。クローンボイスは自分のアカウントでのみ利用できます。
/v1/audio/voices組み込みボイスとクローンボイスの一覧:{data: [{id, name, kind, language}]}。/v1/audio/voicesボイスをクローンします(multipart のフィールドは下表)。/v1/audio/voices/{voice_id}/clipクローンボイスの参照音声(audio_b64)と書き起こし。自分のクローンのみ。/v1/audio/voices/{voice_id}自分のクローンボイスを削除します。組み込みボイスは削除できません。| 名前 | 型 | 説明 |
|---|---|---|
file必須 | binary | 参照音声(WAV または MP3、20 MB まで)。 |
name必須 | string | 1〜64 文字(英数字、_、-)。これがボイス ID になります。 |
language必須 | string | zh、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" }invalid_api_keyBearer トークンがない、形式が不正、または失効しています。invalid_namename が 1〜64 文字の英数字・_・- ではありません。invalid_languagelanguage が対応している値ではありません。not_foundその ID のクローンボイスがアカウントにありません。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="こんにちは、今日はいい天気ですね。"音声透かし
#/v1/audio/watermark/embed音声に聞こえない 16 ビットの透かしを埋め込む/検出します(AudioSeal)。音声の秒数で課金します。
OpenAlchemy 独自拡張(OpenAI のエンドポイントではありません)。
/v1/audio/watermark/embed透かし入りのファイルそのものを、送信と同じ形式(audio/mpeg または audio/wav)で返します。リクエスト ID・message・費用はレスポンスヘッダーに入ります。/v1/audio/watermark/detect透かしの有無、確信度、復号した message を返します。| 名前 | 型 | 説明 |
|---|---|---|
audio_b64必須 | string | WAV または MP3 音声の base64(50 MB まで)。data: URL も可。 |
message | integer 0–65535 | embed でのみ使用(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": "…" } } }missing_audioaudio_b64 が指定されていないか空です。bad_messageembed:message は 0〜65535 の整数である必要があります。invalid_api_keyBearer トークンがない、形式が不正、または失効しています。insufficient_balance見積もり費用が利用可能な残高を超えています。audio_too_large音声が 50 MB を超えています。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画像生成
#/v1/images/local/generationsGrid 上の GPU で PNG を 1 枚生成します。生成が終わると JSON を返します(ストリーミングなし)。
OpenAI Images 形式のリクエスト/レスポンスを独自パスで提供します。SDK では client.post('/images/local/generations', …) を使ってください(images.generate() は別のパスを呼びます)。
| 名前 | 型 | 説明 |
|---|---|---|
model | string | /v1/models の画像モデル(endpoint_type=image)。 |
prompt必須 | string | 画像の説明(1〜32,000 文字)。 |
n | integer既定値 1 | 1 のみ(1 リクエストにつき 1 枚)。 |
size | string既定値 1024x1024 | WIDTHxHEIGHT。16 の倍数で、各辺 1536 まで。 |
response_format | string既定値 b64_json | b64_json のみ。data[0].b64_json をデコードすると PNG が得られます。 |
seed | integer | 0〜4294967295。省略時はランダム。 |
steps | integer既定値 4 | サンプリングステップ数(1〜50)。 |
guidance_scale | number既定値 4 | ガイダンススケール(0〜30)。 |
{
"created": 1713833628,
"data": [{ "b64_json": "<base64 PNG>" }],
"x_openalchemy": {
"request_id": "…", "worker_id": "…", "provider": "local",
"usage": { "images": 1, "cost": "…" }
}
}invalid_api_keyBearer トークンがない、形式が不正、または失効しています。insufficient_balance見積もり費用が利用可能な残高を超えています。model_not_allowedこの API キーは指定したモデルの利用を許可されていません。model_not_foundモデル ID が登録されていません。validation_error未対応または不正なパラメーター(quality、background、output_format、stream、mask は非対応)。engine_unreachable推論エンジンに接続できないか、タイムアウトしました。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"}'画像編集
#/v1/images/local/edits参照画像 1 枚とプロンプトから PNG を生成します。multipart/form-data で送信し、編集のたびに参照画像をアップロードします。
OpenAI Images の編集機能のうち参照画像 1 枚の部分のみを独自パスで提供します。mask と複数画像には非対応です。
| 名前 | 型 | 説明 |
|---|---|---|
image必須 | file | PNG / JPEG / WebP を 1 枚、25 MiB まで(フィールド名 image)。 |
model | string | /v1/models の画像モデル(endpoint_type=image)。 |
prompt必須 | string | 画像の説明(1〜32,000 文字)。 |
n | integer既定値 1 | 1 のみ(1 リクエストにつき 1 枚)。 |
size | string既定値 1024x1024 | WIDTHxHEIGHT。16 の倍数で、各辺 1536 まで。 |
response_format | string既定値 b64_json | b64_json のみ。data[0].b64_json をデコードすると PNG が得られます。 |
seed | integer | 0〜4294967295。省略時はランダム。 |
steps | integer既定値 4 | サンプリングステップ数(1〜50)。 |
guidance_scale | number既定値 4 | ガイダンススケール(0〜30)。 |
{
"created": 1713833628,
"data": [{ "b64_json": "<base64 PNG>" }],
"x_openalchemy": {
"request_id": "…", "worker_id": "…", "provider": "local",
"usage": { "images": 1, "cost": "…" }
}
}invalid_api_keyBearer トークンがない、形式が不正、または失効しています。insufficient_balance見積もり費用が利用可能な残高を超えています。model_not_allowedこの API キーは指定したモデルの利用を許可されていません。model_not_foundモデル ID が登録されていません。validation_error未対応または不正なパラメーター(quality、background、output_format、stream、mask は非対応)。engine_unreachable推論エンジンに接続できないか、タイムアウトしました。empty_image参照画像が空です。image_too_large参照画像が 25 MiB を超えています。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"動画生成
#/v1/videosGrid の 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 枚ごと)。送信時に見積額全額を確保し、失敗またはキャンセル時に解放します。ベータ版。
/v1/videosショットを送信 → 202 {id, status: "queued"}。オンラインのワーカーがない場合は即座に 503 no_video_worker を返し、課金されません。/v1/videosこのプロジェクトでの自分のショット(新しい順)。クエリ:limit(1〜100、既定 20)、after(前ページの last_id)、status。/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。/v1/videos/{id}status、stage、progress(サンプリングの進捗 0〜100%)、credits、成功後は短時間有効な output.url を含む output。/v1/videos/{id}/content短時間有効な署名付き mp4 URL へ 302 リダイレクト。成功するまでは 409、保存期間(既定 7 日)を過ぎると 410。/v1/videos/{id}/cancel待機中または実行中のショットをキャンセルします。確保したクレジットは全額解放されます。| 名前 | 型 | 説明 |
|---|---|---|
model | string既定値 "minimax-h3" | minimax-h3、wan2.2-s2v、wan2.2-i2v、wan2.2-animate、latentsync-1.6。 |
mode | string既定値 "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 では使いません。 |
duration | integer 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:省略(長さは音声に一致)。 |
resolution | string既定値 "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_ratio | string既定値 "16:9" | t2v と ref で使用。i2v はフレームの比率に従います。 |
seed | integer | 固定すると同じ出力を再現できます。省略時はランダム。 |
first_frame_url | string | i2v(minimax-h3、wan2.2-i2v)、s2v、animate:開始フレーム(PNG/JPEG)の https URL、base64、または data: URL。 |
last_frame_url | string | i2v:終了フレーム。 |
reference_image_urls | string[] (1–9) | ref:参照画像(https、base64、または data: URL)。 |
still | boolean既定値 false | minimax-h3 の t2v / ref:動画の代わりに PNG キーフレームを 1 枚生成(1 枚ごとの課金)。control_image_url(ポーズ・深度・線画テンプレート)と control_strength 0〜2 を任意で指定できます。 |
audio_url | string | wan2.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_url | string | wan2.2-animate:演じさせる動き(mp4 / mov / webm、https または data: URL、50 MB 以下)。出力と同じアスペクト比が必要(異なると 422 driving_aspect_mismatch)。first_frame_url がキャラクター。出力に音声はありません。 |
video_url | string | latentsync-1.6:口を合わせ直すクリップ(mp4 / mov / webm、https または data: URL、50 MB 以下、30 秒以下)。映像はそのままで口の部分だけが変わります。出力は 25 fps で audio_url の音声を多重化。 |
steps | integer 1–50 | モデル既定値の代わりに使うサンプリングステップ数(minimax-h3 8、mode ref 4、wan2.2-s2v 4(turbo false では 20)、wan2.2-i2v 6、wan2.2-animate 4)。生成時間と品質が変わりますが、価格は変わりません。 |
turbo | boolean既定値 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 }invalid_durationduration が 4〜15 秒の範囲外です。invalid_modemode が t2v / i2v / ref のいずれでもありません。missing_promptprompt が空です。invalid_stepssteps が 1〜50 の範囲外です。turbo_not_supportedwan2.2-s2v 以外のモデルに turbo: false が指定されました。invalid_resolutionモデルが対応していない resolution です(resolution を参照)。driving_aspect_mismatchwan2.2-animate:参照動画のアスペクト比が aspect_ratio と異なります。audio_needs_s2vstill: true と一緒に、または音声を受け取らないモデルに audio_url が指定されました。audio_longer_than_videolatentsync-1.6:音声が動画より 0.5 秒を超えて長いです。invalid_after一覧:after が自分の動画の ID ではありません。invalid_api_keyBearer トークンがない、形式が不正、または失効しています。insufficient_balance見積額に対してクレジットが不足しています。model_not_allowedこの API キーは指定したモデルの利用を許可されていません。not_foundこのアカウントで動画生成がまだ有効になっていないか、ID が存在しません。video_not_readyショットの成功前にコンテンツを要求しました。video_expired出力の保存期間を過ぎています。resolution_not_supported2K が指定されました。768P のみ対応しています。reference_video_not_supportedreference_video_urls にはまだ対応していません。no_video_worker現在このモデル/モードに対応する GPU ワーカーがオンラインではありません。即座に返され、課金されません。# 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.mp4OCR(文字認識)
#/v1/ocr画像または PDF からテキストを抽出します。PDF はページごとに画像化して認識します(50 ページまで)。ページ単位で課金します。
OpenAlchemy 独自拡張(OpenAI のエンドポイントではありません)。画像について質問するには、画像対応モデルで /v1/chat/completions を使います。
| 名前 | 型 | 説明 |
|---|---|---|
model | string既定値 "paddleocr" | paddleocr(高速、行ごとのボックス付き)または /v1/models の画像対応モデル ID。 |
image_b64必須 | string | 画像(PNG/JPG/WebP)または PDF の base64。data: URL も可。別名:image。 |
lang | string | PaddleOCR の言語コード(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": "…" } }
}missing_imageimage_b64(または image)が指定されていないか空です。bad_base64ペイロードが正しい base64 ではありません。bad_pdfPDF を開けませんでした。invalid_api_keyBearer トークンがない、形式が不正、または失効しています。insufficient_balance見積もり費用が利用可能な残高を超えています。model_not_allowedこの API キーは指定したモデルの利用を許可されていません。too_many_pagesPDF が 50 ページを超えています。engine_unreachable推論エンジンに接続できないか、タイムアウトしました。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)\"}"衣服セグメンテーション
#/v1/garment/segment写真に写っている衣服とその位置を検出します(SegFormer による衣服パーシング)。衣服ごとにマスクの重心を 1 点返します。画像単位で課金します。
OpenAlchemy 独自拡張(OpenAI のエンドポイントではありません)。
| 名前 | 型 | 説明 |
|---|---|---|
model | string既定値 "segformer-b2-clothes" | segformer-b2-clothes(高速)または segformer-b3-clothes。 |
image_b64必須 | string | PNG/JPG/WebP 写真の base64(25 MB まで)。data: URL も可。別名:image。 |
min_area_ratio | number 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": "…" } }
}missing_imageimage_b64(または image)が指定されていないか空です。bad_base64ペイロードが正しい base64 ではありません。invalid_api_keyBearer トークンがない、形式が不正、または失効しています。insufficient_balance見積もり費用が利用可能な残高を超えています。model_not_allowedこの API キーは指定したモデルの利用を許可されていません。image_too_large画像が 25 MB を超えています。engine_unreachable推論エンジンに接続できないか、タイムアウトしました。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 を使ってください。
invalid_api_keyBearer トークンがない、形式が不正、または失効しています。insufficient_balance見積もり費用が利用可能な残高を超えています。model_not_allowedこの API キーは指定したモデルの利用を許可されていません。model_not_foundモデル ID が登録されていません。rate_limitedキーごとの RPM または TPM の上限を超えました。no_workers_for_model現在このモデルを提供している Grid ワーカーがありません。model_not_pricedこのモデルのティアにはまだ料金が設定されていません。engine_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 から同等のモデルを選ぶか、プロバイダーを追加できるようお知らせください。
x_openalchemy.request_id をお伺いします。