Embeddings
POST/api/v1/embeddings turns text and supported media into vectors for search and retrieval, with the OpenAI request and response shapes.
curl https://tokenhub-api.belive.sg/api/v1/embeddings \ -H "Authorization: Bearer $TOKENHUB_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "alibaba/text-embedding-v4", "input": ["hello world", "goodbye"] }'
r = client.embeddings.create( model="alibaba/text-embedding-v4", input=["hello world", "goodbye"], ) vectors = [d.embedding for d in r.data]
Request
| Field | Type | Notes |
|---|---|---|
model / models | string / array | An embedding model, or an ordered fallback list, as on chat completions. There is no workspace default here |
input | string or array, required | One string, an array of non-empty strings, or an array of multimodal {content: [...]} inputs. Media support depends on the model. Token arrays are refused with 400 unsupported_parameter |
dimensions | integer | Only on models that allow it (see the table below), and only up to the model's maximum |
encoding_format | string | float, or base64 where the model supports it |
provider | object | Routing preferences, as on chat completions. See Provider routing |
Multimodal inputs
Image, audio and video inputs use inline base64 parts. Remote media URLs and PDFs are not accepted on this route. Supported models and fusion rules differ: some models fuse parts, while Tongyi vision and Nova accept one part per input. Check this environment's catalogue before choosing a model.
{"model":"alibaba/tongyi-embedding-vision-flash","input":[{"content":[{"type":"text","text":"a red cube"}]}]}Gateway media formats are PNG/JPEG/WebP, MP3/WAV and MP4/MOV. Encoded parts are limited to 4 MiB for images, 8 MiB for audio and 16 MiB for video; the media request limit defaults to 20 MiB. Providers can impose lower limits. See Multimodal inputs for the separate Chat input protocol.
Models and limits
A request outside a model's limits is refused before it reaches the provider: too many inputs is 400 invalid_request, and dimensions or encoding_format: "base64" on a model that does not take it is 400 unsupported_parameter.
| Model | Default size | Inputs per request | dimensions | base64 |
|---|---|---|---|---|
alibaba/text-embedding-v4 | 1024 | 10 | Yes | No |
alibaba/tongyi-embedding-vision-flash | 768 | 10 | No | Yes |
alibaba/tongyi-embedding-vision-plus | 1152 | 10 | No | Yes |
qwen/qwen3.7-text-embedding | 1024 | 20 | Yes | No |
Nothing streams on this route: stream: true is 400, and preset is not accepted.
Response
{ "object": "list", "data": [ { "object": "embedding", "index": 0, "embedding": [0.0123, -0.0456, …] }, { "object": "embedding", "index": 1, "embedding": [0.0311, 0.0087, …] } ], "model": "alibaba/text-embedding-v4", "usage": { "prompt_tokens": 35, "total_tokens": 35 } }
A text embeddings request uses input-token pricing; media requests may use modality-specific token rates or per-image/per-second meters, so usage has no completion_tokens. AI Hub passes the vectors through without truncating or padding them.
Find embedding models in GET /v1/models: their architecture has output_modalities: ["embedding"] and their endpoint route is embeddings.
Support and limits
Use an embedding model with the input shape its schema allows. Vector dimensions, batch size and input modalities are listed per model on the Embeddings page. Embeddings return vectors, not Chat deltas.
Gateway validation, defaults and response forms are in the operation index and the OpenAPI schemas.
Error codes and recovery are in Errors and recovery. Keep the request or job ID from each response: it identifies the call in Activity and for support.