Embeddings

/v1/embeddings is OpenAI-compatible and goes through the same routing and billing flow as chat. It has its own rate limiter (separate from chat/completions), so embedding traffic does not compete with chat traffic for RPM/TPM quota.

The platform currently has no live embedding models: the /v1/embeddings endpoint is ready, but any model you send right now returns 400 (unknown model). Once an embedding model is live, use the ID returned by GET /v1/models (see the model list). Because there is no callable model, this page has no runnable example; what follows is the interface contract.

Scenario overview

Scenarios follow OpenAI's Embeddings guide.

Scenario	Offered officially	Our status	Example
Single text embedding (`input` is a string)	Yes	Not connected: no live embedding model	—
Batch text embedding (`input` is an array of strings)	Yes	Not connected: same	—
Custom dimensions (`dimensions`)	Yes	Not connected: same; the parameter is forwarded to the upstream	—
`base64` encoded output (`encoding_format`)	Yes	Not connected: same; whether it takes effect depends on the upstream	—
Token-array input (`input` is an integer array)	Yes	Not connected: same; some upstreams only read strings and drop non-string elements	—
Multimodal embeddings (image, audio, video input)	No (not in the OpenAI API)	Not connected: same; the platform defines dedicated fields for a few upstreams, see below	—

None of these scenarios was verified with a real call: no embedding model was callable during this documentation review, so the sections below are based on code, not test results.

Request parameters

Field	Type	Notes
`model`	string	Required
`input`	string \| string[]	Required — a single string or a batch of strings
`encoding_format`	string	`float` (default) or `base64`
`dimensions`	integer	Desired output vector dimension; whether a given model supports it depends on the upstream, which decides whether to ignore or reject it
`user`	string	End-user identifier. The platform accepts it but does not forward it to any upstream

Some upstream-specific fields are also accepted at the top level of the request body: task_type + title (retrieval task type and title), input_type (input type for some multimodal models: text / image / video / audio), and output_s3_uri (asynchronous output location). Other upstream-specific parameters can only go in an object named extra_body in the request body (in curl, a literal "extra_body": {...}), and only some upstreams read it. The extra_body= argument of the OpenAI Python / Node SDK spreads its content into the top level of the request body, and this endpoint drops those unknown top-level fields, so it differs from Chat Completions.

Response

The response format is per the OpenAI docs (not tested):

{
  "object": "list",
  "model": "<embedding-model-id>",
  "data": [
    { "object": "embedding", "index": 0, "embedding": [0.0023, -0.009, "…"] },
    { "object": "embedding", "index": 1, "embedding": [0.0041, 0.002, "…"] }
  ],
  "usage": { "prompt_tokens": 12, "total_tokens": 12 }
}

embedding is a float array by default, and a base64-encoded string when encoding_format: "base64". Billing uses the input_token dimension, like chat.

Errors

While there is no embedding model, any model returns the 400 below (per code, not tested); invalid key (401), insufficient balance (402) and rate limit (429) have the same bodies as Chat Completions.

{"error":{"type":"invalid_request_error","message":"unknown model: <embedding-model-id>"}}

Full error codes and handling advice: Errors.

Unsupported or different parameters

The embeddings endpoint has no "pass unknown fields through": top-level fields in the request body that the platform does not define are dropped. (This differs from Chat Completions; the platform does not drop defined parameters against an allowlist, and defined parameters are handed to the upstream.)

Parameter	Behavior	Notes
`input`	Partial	A string or an array of strings. Some upstreams receive `input` as-is; others only read strings, and elements of the array that are not strings (token arrays, images, multimodal content blocks) are dropped
`encoding_format`	Partial	Some upstreams receive the field; some only recognize `base64`; some ignore it and always return float arrays
`dimensions`	Partial	Forwarded to the upstream; a few upstreams rename it to their own parameter
`user`	Not forwarded	Accepted but never sent to any upstream
`messages`, `continue_final_message`, `add_special_tokens`	Accepted but ignored	Chat-embeddings dialect fields of some open-source embedding servers, accepted for clients such as Dify; neither read nor forwarded
`extra_body`	Partial	Merged only by some upstreams; ignored by the others

Platform extensions

task_type, title, input_type, output_s3_uri are upstream-specific fields the platform accepts at the top level; see the note above.
Response usage.prompt_tokens_details (text_tokens, image_tokens, audio_tokens, video_tokens): appears when a multimodal embedding model reports per-modality usage; other models do not have it.
Response header X-Request-ID; 429 carries Retry-After. The embeddings endpoint has its own rate limiter.
The platform defines no separate request headers or cost fields for this endpoint.