埋め込み

Show: All versions v2 only

Schiftは、単一のエンドポイントセットを通じて複数のプロバイダー（OpenAI、Google、Voyage、Cloudflare、HuggingFaceなど）にプロキシする統一埋め込みAPIを提供します。すべての埋め込みはSchiftの標準投影レイヤーを通過するため、データを再埋め込みすることなくモデルを切り替えたり、次元を削減したりできます。

認証

すべての埋め込みエンドポイントには、AuthorizationヘッダーにBearerトークンが必要です：

Authorization: Bearer sch_xxxxxxxxxxxxxxxxxxxx

APIキーはSchiftダッシュボードのSettings > API Keysで管理します。

対応モデル

Model	Provider	Default dimension	Max tokens	Variable dimensions
schift-embed-1-small	Schift (auto)	1024	8,192	Yes
openai/text-embedding-3-small	OpenAI	1536	8,191	Yes
openai/text-embedding-3-large	OpenAI	3072	8,191	Yes
google/gemini-embedding-001	Google	3072	8,191	Yes
google/gemini-embedding-002	Google	3072	8,191	Yes
voyage/voyage-4-large	Voyage AI	1024	32,000	Yes
voyage/voyage-4	Voyage AI	1024	32,000	Yes
voyage/voyage-4-lite	Voyage AI	1024	32,000	Yes
dragonkue/bge-m3-ko	HuggingFace	1024	8,192	No
jinaai/jina-embeddings-v3	HuggingFace	1024	8,194	Yes
sbintuitions/sarashina-embedding-v2-1b	HuggingFace	1792	8,192	No

schift-embed-1-smallは自動ルーティングエイリアスです。Schiftは入力言語に基づいて最適な基礎モデルを選択し、結果を標準投影レイヤーを通して返します。解決されたモデルは、すべてのレスポンスのmodelフィールドに返されます。

Note: schift-embed-1-smallを使用した場合、内部バックエンドエイリアス（例：@cf/qwen/qwen3-embedding-0.6b）が解決されたモデルとして返されることがあります。

タスクタイプ

埋め込みエンドポイントはオプションでtask_typeを受け入れ、埋め込みがどのように使用されるかをSchiftに指示します。この値は、指示対応モデルに渡されるか、プレフィックススタイルモデルの内部プレフィックスに変換されます。

task_type	Use case
retrieval_query	検索クエリ埋め込み
retrieval_document	ドキュメント埋め込み
semantic_similarity	セマンティック類似性比較
question_answering	質問応答検索
clustering	クラスタリングまたはトピックグループ化
classification	分類
code_retrieval	コード検索
contradiction	矛盾または反証検索
factcheck	ファクトチェック証拠検索

POST /v1/embed

単一のテキスト文字列を埋め込みます。

Request body

Parameter	Type	Required	Default	Description
text	string	Yes	—	埋め込むテキスト。
model	string	No	Org routing config	カタログからのモデルID。
dimensions	integer	No	Model default	出力次元。可変次元を持つモデルのみサポート。
task_type	string	No	—	埋め込みの意図。Task typesを参照。

Response fields

Field	Type	Description
embedding	number[]	埋め込みベクトル。
model	string	実際に使用されたモデル。
dimensions	integer	埋め込みの出力次元。
usage.tokens	integer	消費されたトークン数。

Example request

curl https://api.schift.io/v1/embed \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d '{
    "text": "Schift enables seamless embedding model migration without re-embedding your data.",
    "model": "openai/text-embedding-3-large"
  }'

Example response

{
  "embedding": [-0.01225, 0.00207, 0.03060],
  "model": "openai/text-embedding-3-large",
  "dimensions": 3072,
  "usage": {"tokens": 14}
}

POST /v1/embed/batch

同期バッチ埋め込み。単一リクエストで最大100テキストを処理します。より大きな入力には、POST /v1/embed/jobsを使用してください。

Request body

Parameter	Type	Required	Default	Description
texts	string[]	Yes	—	埋め込むテキストのリスト（最大100）。
model	string	No	Org routing config	カタログからのモデルID。
dimensions	integer	No	Model default	出力次元。
task_type	string	No	—	埋め込みの意図。

Response fields

Field	Type	Description
embeddings	number[][]	各入力テキストに対する埋め込みベクトルのリスト。
model	string	使用されたモデル。
dimensions	integer	出力次元。
usage.tokens	integer	すべてのテキストにわたるトークンの合計。
usage.count	integer	埋め込まれたテキストの数。

Example request

curl https://api.schift.io/v1/embed/batch \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d '{
    "texts": [
      "The Mediterranean diet emphasizes fish, olive oil, and vegetables.",
      "Photosynthesis converts light energy into chemical energy.",
      "Shakespeare wrote Hamlet and A Midsummer Night'"'"'s Dream."
    ],
    "model": "voyage/voyage-4-large"
  }'

Example response

{
  "embeddings": [
    [-0.01225, 0.00207, 0.03060],
    [0.00898, -0.00298, 0.01546],
    [-0.06297, -0.04777, -0.10113]
  ],
  "model": "voyage/voyage-4-large",
  "dimensions": 1024,
  "usage": {"tokens": 38, "count": 3}
}

POST /v1/embed/jobs

非同期バルク埋め込みジョブを作成します。このエンドポイントは101から10,000テキストに使用します。

Request body

Parameter	Type	Required	Default	Description
texts	string[]	Yes	—	埋め込むテキストのリスト（最大10,000）。
model	string	No	Org routing config	カタログからのモデルID。
dimensions	integer	No	Model default	出力次元。
task_type	string	No	—	埋め込みの意図。

Response fields

Field	Type	Description
id	string	バルク埋め込みジョブID。
status	string	初期ステータス（queued）。
model	string	ジョブに選択されたモデル。
usage.tokens	integer	すべてのテキストにわたる検証済みトークンの合計。
usage.count	integer	提出されたテキストの数。
chunk_size	integer	ワーカーチャンクサイズ（現在100）。

Example request

curl https://api.schift.io/v1/embed/jobs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d '{
    "texts": ["doc 1", "doc 2", "doc 3"],
    "model": "schift-embed-1-small",
    "task_type": "retrieval_document"
  }'

Example response

{
  "id": "job_123",
  "status": "queued",
  "model": "schift-embed-1-small",
  "usage": {"tokens": 6, "count": 3},
  "chunk_size": 100
}

GET /v1/embed/jobs/{job_id}

バルク埋め込みジョブのステータスとメタデータを取得します。

Path parameters

Parameter	Type	Description
job_id	string	バルク埋め込みジョブID。

ジョブステータスライフサイクル

Status	Meaning
queued	ジョブが作成され、ワーカーを待っています。
embedding	ワーカーがテキストチャンクを埋め込んでいます。
indexing	結果が準備され、保存されています。
ready	結果が取得可能です。
failed	ジョブが失敗しました。
cancelled	ジョブが処理前にキャンセルされました。

Example request

curl https://api.schift.io/v1/embed/jobs/job_123 \
  -H "Authorization: Bearer $SCHIFT_API_KEY"

Example response

{
  "id": "job_123",
  "status": "ready",
  "org_id": "org_abc",
  "metadata": {
    "mode": "embed_bulk",
    "model": "schift-embed-1-small",
    "dimensions": null,
    "task_type": "retrieval_document",
    "input_count": 3,
    "chunk_size": 100,
    "token_count": 6,
    "completed_count": 3
  }
}

POST /v1/embed/jobs/{job_id}/cancel

キューに入っているバルク埋め込みジョブをキャンセルします。queuedステータスのジョブのみキャンセル可能です。

Path parameters

Parameter	Type	Description
job_id	string	バルク埋め込みジョブID。

Example request

curl -X POST https://api.schift.io/v1/embed/jobs/job_123/cancel \
  -H "Authorization: Bearer $SCHIFT_API_KEY"

Example response

{
  "status": "cancelled"
}

GET /v1/embed/jobs/{job_id}/result

完了したバルク埋め込みジョブのページネーションされた結果を取得します。

Path parameters

Parameter	Type	Description
job_id	string	バルク埋め込みジョブID。

Query parameters

Parameter	Type	Default	Description
offset	integer	0	スキップする結果の数。
limit	integer	100	返す結果の最大数（最大1,000）。

Response fields

Field	Type	Description
object	string	常にlist。
data	object[]	ページネーションされた埋め込み結果アイテム。
model	string	結果に使用されたモデル。
dimensions	integer	出力次元。
usage.count	integer	埋め込まれたアイテムの総数。
pagination.offset	integer	リクエストされたオフセット。
pagination.limit	integer	リクエストされた制限。
pagination.returned	integer	このページで返されたアイテムの数。
pagination.total	integer	結果アイテムの総数。
pagination.has_more	boolean	さらにページが残っているかどうか。

Example request

curl "https://api.schift.io/v1/embed/jobs/job_123/result?offset=0&limit=100" \
  -H "Authorization: Bearer $SCHIFT_API_KEY"

Example response

{
  "object": "list",
  "data": [
    {"object": "embedding", "index": 0, "embedding": [-0.01225, 0.00207]},
    {"object": "embedding", "index": 1, "embedding": [0.00898, -0.00298]},
    {"object": "embedding", "index": 2, "embedding": [-0.06297, -0.04777]}
  ],
  "model": "schift-embed-1-small",
  "dimensions": 1024,
  "usage": {"count": 3},
  "pagination": {
    "offset": 0,
    "limit": 100,
    "returned": 3,
    "total": 3,
    "has_more": false
  }
}

POST /v1/embed/image

画像を埋め込むには、まずビジョン-言語モデルでテキストを抽出し、次に抽出されたテキストを埋め込みます。リクエストごとに最大20のbase64エンコードされた画像を受け入れます。

Request body

Parameter	Type	Required	Default	Description
images	string[]	Yes	—	Base64エンコードされた画像データ。
model	string	No	Org routing config	カタログからのモデルID。
dimensions	integer	No	Model default	出力次元。

Response fields

Field	Type	Description
embeddings	number[][]	各画像に対する埋め込みベクトルのリスト。
model	string	使用されたモデル。
dimensions	integer	出力次元。
usage.image_count	integer	処理された画像の数。
usage.tokens	integer	消費されたトークンの合計。

Example request

curl https://api.schift.io/v1/embed/image \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d '{
    "images": ["iVBORw0KGgoAAAANSUhEUg..."],
    "model": "openai/text-embedding-3-large"
  }'

Example response

{
  "embeddings": [[-0.01225, 0.00207, 0.03060]],
  "model": "openai/text-embedding-3-large",
  "dimensions": 3072,
  "usage": {"image_count": 1, "tokens": 14}
}

POST /v1/embeddings

OpenAI互換の埋め込みエンドポイント。OpenAIの/v1/embeddingsと同じinput形式を受け入れ、OpenAI互換のレスポンス形式を返します。このエンドポイントは、/v1/embedおよび/v1/embed/batchと同じロジックの薄いラッパーです。

Note: 100以上の入力には、POST /v1/embed/jobsを使用してください。

Request body

Parameter	Type	Required	Default	Description
input	string | string[]	Yes	—	埋め込むテキストまたはテキストのリスト。
model	string	No	Org routing config	カタログからのモデルID。
dimensions	integer	No	Model default	出力次元。
task_type	string	No	—	Schift拡張：埋め込みの意図。
encoding_format	string	No	—	互換性のために受け入れられ、現在は未使用。
user	string	No	—	互換性のために受け入れられ、現在は未使用。

Response fields

Field	Type	Description
object	string	常にlist。
data	object[]	object、index、およびembeddingを含む埋め込みオブジェクト。
model	string	使用されたモデル。
usage.prompt_tokens	integer	消費されたトークンの合計。
usage.total_tokens	integer	消費されたトークンの合計。

Example request

curl https://api.schift.io/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d '{
    "input": "Schift enables seamless embedding model migration.",
    "model": "openai/text-embedding-3-large"
  }'

Example response

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [-0.01225, 0.00207, 0.03060]
    }
  ],
  "model": "openai/text-embedding-3-large",
  "usage": {
    "prompt_tokens": 8,
    "total_tokens": 8
  }
}

標準投影

Schiftによって返されるすべての埋め込みは、共有の標準潜在空間に投影されます。これにより、以下が可能になります：

• 再埋め込みなしでのモデル切り替え。 OpenAIからVoyageに移行しても、ベクトルストアに触れる必要はありません。
• クロスモデル検索。 あるモデルからのクエリベクトルで、別のモデルで埋め込まれたドキュメントを取得できます。
• 次元削減。 ソースモデルのネイティブ次元に関係なく、任意の出力次元を要求できます。

投影は透過的に行われます。通常通りAPIを呼び出せば、Schiftが処理します。

ルーティングとフェイルオーバー

組織はデフォルトの埋め込みモデルとオプションのフォールバックを設定できます。フェイルオーバーモードが有効な場合、Schiftはプライマリプロバイダーが利用できない場合に自動的にフォールバックモデルで再試行します。

ルーティングエンドポイントを使用してデフォルトを設定します：

curl -X PUT https://api.schift.io/v1/routing \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d '{
    "primary": "openai/text-embedding-3-large",
    "fallback": "voyage/voyage-4-large",
    "mode": "fallback"
  }'

すべての埋め込みエンドポイントからのレスポンスには、使用されたモデルを常に知ることができるようにmodelフィールドが含まれています。

レート制限とクォータ

レート制限は組織ごとに適用されます。使用状況はリアルタイムで追跡されます。埋め込みエンドポイントに対しては、以下の軸がチェックされます：

Endpoint	Quota axis
POST /v1/embed	embed
POST /v1/embed/batch	embed_batch
POST /v1/embed/image	embed_image
POST /v1/embed/jobs	embed_batch
POST /v1/embeddings	embed or embed_batch

現在の使用状況を取得するには：

curl https://api.schift.io/v1/usage/summary \
  -H "Authorization: Bearer $SCHIFT_API_KEY"

バルク埋め込みジョブは、組織のプランに基づいて優先順位が割り当てられます：

Plan	Priority
Enterprise	0
Business	1
Pro / Paid / Starter	2
Free	3

小さい数字が先に処理されます。

エラーコード

共通エラー

Status	Meaning
400	不正なリクエスト — 不明なモデル、無効な次元、空の入力、またはトークン制限超過。
401	無効または期限切れのAPIキー。
402	クレジット不足またはクォータ超過。
403	プランで利用できない機能または権利制限に達しました。
502	上流の埋め込みプロバイダーが失敗しました（プライマリとフォールバックの両方）。

バルクジョブエラー

Endpoint	Status	Meaning
POST /v1/embed/batch	400	同期リクエストで100以上のテキスト。POST /v1/embed/jobsを使用してください。
POST /v1/embed/jobs	400	空のテキスト、10,000以上のテキスト、またはテキストがモデルのmax_tokensを超えています。
GET /v1/embed/jobs/\{job_id\}	404	ジョブが見つからないか、他の組織に属しています。
POST /v1/embed/jobs/\{job_id\}/cancel	400	ジョブはすでに処理中または完了しています。
POST /v1/embed/jobs/\{job_id\}/cancel	409	ジョブはもはやキューにありません。
GET /v1/embed/jobs/\{job_id\}/result	404	ジョブまたは結果が見つかりません。
GET /v1/embed/jobs/\{job_id\}/result	409	結果がまだ準備できていません。

参照

• バケット
• Search
• Usage
• Routing