Embeddings

Create OpenAI-compatible text embeddings and BytePlus ModelArk text, image, and video embeddings.

POST /v1/embeddings converts input into floating-point vectors. String input remains compatible with the OpenAI Embeddings API; a ModelArk multimodal embedding model accepts text, image, and video together in one array.

POST/v1/embeddingsHost: apirouter.pleum.aiAuth: API key

Connecting#

With the OpenAI SDK, set base_url to https://apirouter.pleum.ai/v1 and the API key to your plm_ key. The SDK appends /v1/embeddings.

OpenAI SDK (Python)

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["PLEUM_API_KEY"],
    base_url="https://apirouter.pleum.ai/v1",
)

response = client.embeddings.create(
    model="text-embedding-3-large",
    input=["The quick brown fox", "jumps over the lazy dog"],
)
print(response.data[0].embedding)

OpenAI SDK (TypeScript)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.PLEUM_API_KEY,
  baseURL: "https://apirouter.pleum.ai/v1",
});

const response = await client.embeddings.create({
  model: "text-embedding-3-large",
  input: ["The quick brown fox", "jumps over the lazy dog"],
});

console.log(response.data[0].embedding);

Request body#

Parameter	Type	Required	Description
model	string	Required	Embedding model ID, e.g. `text-embedding-3-large`. Select an active BytePlus ModelArk embedding model to use multimodal objects.
input	string \| array	Required	One string, or an array of strings and content objects. An empty array returns `400`. A token-ID array returns `400` on keys with PII masking (the default) and on ModelArk models, so send strings instead.
dimensions	integer	Optional	Optional. Truncated embedding width (1–10,000). Passed through to OpenAI-compatible providers; unsupported offerings surface an upstream error. ModelArk multimodal embeddings reject this parameter with `400`.
encoding_format	string	Optional	Optional. Accepts `"float"` (same as omitting) and `"base64"`. Either way, response embeddings are always float arrays.

model must be an active embedding model. Sending image or video objects to a chat model or a provider without multimodal embedding support returns 400 before the call.

text input

{
  "model": "text-embedding-3-large",
  "input": ["The quick brown fox", "jumps over the lazy dog"]
}

ModelArk multimodal input#

Use content objects only inside an array. Text is {"type":"text","text":"…"}, an image is {"type":"image_url","image_url":{"url":"https://…"}}, and a video is {"type":"video_url","video_url":{"url":"https://…"}}. URLs must be HTTP or HTTPS; PleumRouter forwards them to ModelArk without downloading the media.

ModelArk multimodal request

curl https://apirouter.pleum.ai/v1/embeddings \
  -H "Authorization: Bearer $PLEUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "skylark-embedding-vision-251215",
    "input": [
      {"type": "text", "text": "A ceramic mug on a desk"},
      {"type": "image_url", "image_url": {"url": "https://example.com/mug.png"}},
      {"type": "video_url", "video_url": {"url": "https://example.com/mug.mp4"}}
    ]
  }'

An array can contain at most 2,048 items. Strings and text content are limited to 100,000 characters per item. Text-only calls retain the existing OpenAI-compatible path.

Response#

The response returns OpenAI-style data entries (a vector and index) and usage. cost may be omitted when settlement is late. See Where to find cost.

200 OK

{
  "object": "list",
  "data": [
    {"object": "embedding", "embedding": [0.01, -0.02], "index": 0}
  ],
  "model": "skylark-embedding-vision-251215",
  "usage": {"prompt_tokens": 29, "total_tokens": 29}
}

Usage and billing#

A mixed ModelArk request is finally settled from the provider-reported input tokens for each modality. Public usage.prompt_tokens is the total input-token count.