BRASILTradução de apoio para consulta. Código e identificadores técnicos preservados. Consultar referência original ↗
Incorporação multimodal DashScope
API de incorporação multimodal
Converta texto, imagens e vídeo em vetores numéricos em um espaço semântico unificado para recuperação intermodal, pesquisa por similaridade e classificação de conteúdo.
Antes de começar: obtenha uma chave de API, defini-lo como uma variável de ambiente e instalar o SDK do DashScope se você usar o SDK.
Ponto final
-HTTP: POST https://maas.qwencloudapi.com/api/v1/services/embeddings/multimodal-embedding/multimodal-embedding
-SDK base_http_api_url: https://maas.qwencloudapi.com/api/v1
Visão geral do modelo
| Modelo | Modalidades | Dimensões | Limite de texto | Limite de imagem | Limite de vídeo |
|---|---|---|---|---|---|
| tongyi-incorporação-vision-plus | Texto, imagem, vídeo, multi-imagens | 1152 (fixo) | 1.024 fichas | 3 MB por imagem, máximo de 8 imagens | 10 MB |
| tongyi-incorporação-visão-flash | Texto, imagem, vídeo, multi-imagens | 768 (fixo) | 1.024 fichas | 3 MB por imagem, máximo de 8 imagens | 10 MB |
Os modelos tongyi-embedding-vision têm dimensões fixas e não suportam o dimension parâmetro.
Notas
- Limite de texto: 1.024 tokens por solicitação.
- Entrada de imagem: URL público ou URI de dados Base64 (
data:image/{format};base64,{data}). Formatos suportados: JPG, PNG, BMP (URL ou Base64 suportado). Máximo de 3 MB por imagem. - Multi-imagens: Chave
multi_images. O valor é uma lista de URLs de imagens, no máximo 8 imagens. Cada imagem não deve ter mais de 3 MB. - Entrada de vídeo: deve ser um URL público. Formatos suportados: MP4, MPEG, AVI, MOV, MPG, WEBM, FLV, MKV (somente URL). Máximo de 10 MB por arquivo de vídeo. Use o
fpsparâmetro emparameterspara controlar a taxa de amostragem de quadros (intervalo [0, 1], padrão 1,0).
OpenAPI
openapi: 3.1.0
info:
title: QwenCloud Image API
description: DashScope Image APIs for image generation, editing, specialized image tasks, and multimodal embeddings.
version: 1.0.0
servers:
- url: https://maas.qwencloudapi.com/api/v1
description: Singapore
security:
- BearerAuth: []
paths:
/services/embeddings/multimodal-embedding/multimodal-embedding:
post:
operationId: createMultimodalEmbedding
summary: Create multimodal embedding
description: Convert text, images, and video into a unified vector space. Use cases include cross-modal retrieval, semantic similarity, and content classification. All modalities share the same semantic space — you can compare vectors across modalities directly using cosine similarity.
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/MultimodalEmbeddingRequest"
responses:
"200":
description: Multimodal embedding result
content:
application/json:
schema:
$ref: "#/components/schemas/MultimodalEmbeddingResponse"
"400":
description: Invalid request parameters
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
"401":
description: Authentication failed — invalid or missing API Key
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
"429":
description: Rate limit exceeded
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
x-codeSamples:
- lang: curl
label: cURL (Independent Vectors)
source: |-
curl --location --request POST \
'https://maas.qwencloudapi.com/api/v1/services/embeddings/multimodal-embedding/multimodal-embedding' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "tongyi-embedding-vision-plus",
"input": {
"contents": [
{"text": "Multimodal embedding model"},
{"image": "https://example.com/image.jpg"},
{"video": "https://example.com/video.mp4"}
]
}
}'
- lang: curl
label: cURL (Fused Vector)
source: |-
curl --location --request POST \
'https://maas.qwencloudapi.com/api/v1/services/embeddings/multimodal-embedding/multimodal-embedding' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "tongyi-embedding-vision-plus",
"input": {
"contents": [
{
"text": "Test text for generating a fused multimodal vector",
"image": "https://example.com/image.png",
"video": "https://example.com/video.mp4"
}
]
},
"parameters": {
"dimension": 1024
}
}'
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: DashScope API Key. Create one in the [QwenCloud console](https://home.qwencloud.com/api-keys). Alternatively, you can pass the API Key via the `X-DashScope-ApiKey` request header.
schemas:
SyncImageRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: Model name. Use `wan2.6-t2i` for text-to-image generation, `wan2.6-image` for image editing and interleaved output, or `z-image-turbo` for lightweight fast generation.
enum:
- wan2.6-t2i
- wan2.6-image
- z-image-turbo
example: wan2.6-t2i
input:
type: object
required:
- messages
description: Input data containing the messages array.
properties:
messages:
type: array
description: Single-turn only. One message with role `user`.
minItems: 1
maxItems: 1
items:
$ref: "#/components/schemas/ImageMessage"
parameters:
$ref: "#/components/schemas/SyncImageParameters"
ImageMessage:
type: object
required:
- role
- content
properties:
role:
type: string
enum:
- user
description: Must be `user`.
content:
type: array
description: Array of content items. Must contain exactly one text object. For image editing (`wan2.6-image`), may also contain 1-4 image objects (editing mode) or 0-1 image objects (interleaved mode).
items:
$ref: "#/components/schemas/ImageContentPart"
ImageContentPart:
type: object
description: A content part in the message. Provide either `text` or `image`, not both in the same object.
properties:
text:
type: string
description: Prompt text for the image. Max 2100 characters for `wan2.6-t2i`, max 2000 characters for `wan2.6-image`, max 800 characters for `z-image-turbo`. Only one text object allowed per content array.
maxLength: 2100
image:
type: string
description: "Reference image URL (HTTP/HTTPS) or Base64 data URI (`data:{MIME_type};base64,{data}`). For image editing mode only (`wan2.6-image` with `enable_interleave=false`): 1-4 images required. For interleaved mode: 0-1 images. Supported formats: JPEG, JPG, PNG, BMP, WEBP. Resolution: [384, 5000]px per side. Max 10 MB."
SyncImageParameters:
type: object
description: Generation parameters.
properties:
size:
type: string
description: "Output resolution as `width*height`. For `wan2.6-t2i`: total pixels in [1280x1280, 1440x1440], ratio [1:4, 4:1]. Default: `1280*1280`. For `wan2.6-image`: total pixels in [768x768, 1280x1280], ratio [1:4, 4:1]. Default: `1280*1280`. For `z-image-turbo`: total pixels in [512x512, 2048x2048]. Default: `1024*1536`."
default: 1280*1280
example: 1280*1280
n:
type: integer
description: "Number of images to generate. Range 1-4. Default: 4. Billed per image. In interleaved mode, must be 1."
minimum: 1
maximum: 4
default: 4
prompt_extend:
type: boolean
description: "Enable smart prompt rewriting. Adds 3-4s latency. Available for `wan2.6-t2i`, `wan2.6-image` (editing mode only), and `z-image-turbo`. For `z-image-turbo`, enabling this costs more (see pricing). Default: `true` for wan2.6, `false` for z-image-turbo."
default: true
watermark:
type: boolean
description: 'Add an "AI Generated" watermark to the output image. Default: `false`.'
default: false
negative_prompt:
type: string
description: Elements to exclude from the generated image. For `wan2.6-t2i` only.
enable_interleave:
type: boolean
description: "For `wan2.6-image` only. `false` (default): image editing mode. `true`: interleaved text-image output mode (requires streaming)."
default: false
max_images:
type: integer
description: "For `wan2.6-image` interleaved mode only. Maximum number of images per response. Range 1-5. Default: 5. Actual count is determined by the model."
minimum: 1
maximum: 5
default: 5
stream:
type: boolean
description: "Enable streaming output. Required (`true`) for interleaved mode (`enable_interleave=true`). Default: `false`."
default: false
AsyncImageRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: Model name for asynchronous image generation.
enum:
- wan2.6-t2i
- wan2.5-t2i-preview
- wan2.2-t2i-flash
- wan2.2-t2i-plus
- wanx2.1-t2i-turbo
- wanx2.1-t2i-plus
- flux-schnell
- flux-dev
- flux-merged
example: wan2.6-t2i
input:
type: object
required:
- messages
description: Input data containing the messages array.
properties:
messages:
type: array
description: Single-turn only. One message with role `user`.
minItems: 1
maxItems: 1
items:
$ref: "#/components/schemas/ImageMessage"
parameters:
$ref: "#/components/schemas/AsyncImageParameters"
AsyncImageParameters:
type: object
description: Generation parameters for async image creation.
properties:
size:
type: string
description: "Output resolution as `width*height`. Supported values vary by model. For Wan models: see model constraints. For FLUX models: `512*1024`, `768*512`, `768*1024`, `1024*576`, `576*1024`, `1024*1024`. Default: `1280*1280` (Wan) or `1024*1024` (FLUX)."
example: 1280*1280
n:
type: integer
description: "Number of images to generate. Range 1-4. Default: 4 (Wan) or 1 (FLUX)."
minimum: 1
maximum: 4
prompt_extend:
type: boolean
description: "Enable smart prompt rewriting. Adds 3-4s latency. Default: `true`."
default: true
watermark:
type: boolean
description: 'Add an "AI Generated" watermark to the output image. Default: `false`.'
default: false
negative_prompt:
type: string
description: Elements to exclude from the generated image.
SpecializedImageRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: Model name for the specialized image task.
enum:
- wanx-style-repaint-v1
- image-expansion
- wanx-poster-generation-v1
- image-inpainting
- person-segmentation
- wanx-sketch-to-image-v1
- aitryon-v1
- aitryon-v2
- virtual-model
- shoe-model
example: aitryon-v2
input:
type: object
description: Model-specific input data. The structure varies by model. See the endpoint description above for model-specific parameter details.
properties:
person_image_url:
type: string
description: URL of the person image. Used by `aitryon-v1`, `aitryon-v2`.
garment_image_url:
type: string
description: URL of the garment image. Used by `aitryon-v1`, `aitryon-v2`.
base_image_url:
type: string
description: URL of the foreground/product image.
prompt:
type: string
description: Text prompt describing the desired output.
parameters:
$ref: "#/components/schemas/SpecializedImageParameters"
SpecializedImageParameters:
type: object
description: Parameters for specialized image tasks. Available parameters vary by model.
properties:
n:
type: integer
description: Number of images to generate. Range 1-4. Default varies by model.
minimum: 1
maximum: 4
resolution:
type: integer
description: "Output resolution (short side in pixels). Used by virtual try-on models. Default: 768."
default: 768
WordArtRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: Model name for WordArt generation.
enum:
- wordart-deformation-v1
example: wordart-deformation-v1
input:
type: object
required:
- text
- prompt
description: Input data for WordArt generation.
properties:
text:
type: object
required:
- text_content
- font_name
description: Text configuration.
properties:
text_content:
type: string
description: Text to render. Max 6 characters.
maxLength: 6
example: AI
font_name:
type: string
description: Font name for the base text.
example: dongfangdakai
prompt:
type: string
description: Style description for the texture effect.
example: Flames and fire, burning effect
parameters:
type: object
description: Generation parameters.
properties:
n:
type: integer
description: "Number of images to generate. Default: 4."
default: 4
MultimodalEmbeddingRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: Model name for multimodal embedding.
enum:
- tongyi-embedding-vision-plus
- tongyi-embedding-vision-flash
example: tongyi-embedding-vision-plus
input:
type: object
required:
- contents
description: Input data containing the content items.
properties:
contents:
type: array
description: Content items. Each item is an object with one or more modality keys (`text`, `image`, `video`, `multi_images`). For independent vectors, use one modality per object. For fused vectors, combine modalities in a single object.
items:
$ref: "#/components/schemas/MultimodalContentItem"
parameters:
$ref: "#/components/schemas/MultimodalEmbeddingParameters"
MultimodalContentItem:
type: object
description: A content item for multimodal embedding. Include one or more modality keys. For independent vectors, use one key per object. For fused vectors, combine keys in a single object.
properties:
text:
type: string
description: Text content to embed.
image:
type: string
description: Image URL (public HTTP/HTTPS) or Base64 data URI (`data:image/{format};base64,{data}`).
video:
type: string
description: Video URL (must be a public URL).
multi_images:
type: array
description: List of image URLs for multi-image embedding. Max 8 images. Only supported by `tongyi-embedding-vision-plus` and `tongyi-embedding-vision-flash`.
items:
type: string
maxItems: 8
MultimodalEmbeddingParameters:
type: object
description: Parameters for multimodal embedding.
properties:
output_type:
type: string
description: Output format. Only `dense` is supported.
enum:
- dense
default: dense
dimension:
type: integer
description: Output vector dimension. Supported values vary by model. See the model overview table for defaults and options.
fps:
type: number
description: "Video frame sampling rate. Range [0, 1]. Default: 1.0."
minimum: 0
maximum: 1
default: 1
instruct:
type: string
description: Custom task instruction. English recommended. Typically yields 1-5% improvement in retrieval tasks.
SyncImageResponse:
type: object
description: Synchronous image generation or editing response.
properties:
output:
type: object
properties:
choices:
type: array
description: List of generated results.
items:
$ref: "#/components/schemas/ImageChoice"
finished:
type: boolean
description: Whether the task completed.
usage:
$ref: "#/components/schemas/ImageUsage"
request_id:
type: string
description: Unique request identifier.
example: 815505c6-7c3d-49d7-b197-xxxxx
ImageChoice:
type: object
properties:
finish_reason:
type: string
description: "`stop` on normal completion. `null` during streaming."
example: stop
message:
type: object
properties:
role:
type: string
description: Always `assistant`.
enum:
- assistant
content:
type: array
description: Array of content items. Each item contains either an image URL or text (in interleaved mode).
items:
$ref: "#/components/schemas/ImageResponseContentPart"
ImageResponseContentPart:
type: object
description: A content part in the response message.
properties:
type:
type: string
description: "Content type: `image` or `text` (text only in interleaved mode)."
enum:
- image
- text
image:
type: string
description: Generated image URL (PNG). **Valid for 24 hours.** Present when `type` is `image`.
text:
type: string
description: Generated text content. Present when `type` is `text` (interleaved mode).
ImageUsage:
type: object
description: Usage statistics for image generation.
properties:
image_count:
type: integer
description: Number of images generated.
input_tokens:
type: integer
description: Input tokens consumed. 0 in editing mode; actual count in interleaved mode.
output_tokens:
type: integer
description: Output tokens consumed. 0 in editing mode; actual count in interleaved mode.
size:
type: string
description: Output resolution.
example: 1280*1280
total_tokens:
type: integer
description: Total tokens (input_tokens + output_tokens).
AsyncTaskSubmitResponse:
type: object
description: Response from an asynchronous task submission.
properties:
request_id:
type: string
description: Unique request identifier.
output:
type: object
properties:
task_id:
type: string
description: Task ID for polling status. Use with `GET /tasks/{task_id}`.
task_status:
type: string
description: Initial task status, typically `PENDING`.
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
AsyncTaskStatusResponse:
type: object
description: Async task status and results.
properties:
request_id:
type: string
description: Unique request identifier.
output:
type: object
properties:
task_id:
type: string
description: Task ID.
task_status:
type: string
description: Current task status.
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
results:
type: array
description: Generated image results. Present when `task_status` is `SUCCEEDED`.
items:
$ref: "#/components/schemas/AsyncTaskResult"
task_metrics:
$ref: "#/components/schemas/TaskMetrics"
usage:
type: object
description: Usage statistics.
properties:
image_count:
type: integer
description: Number of successfully generated images.
AsyncTaskResult:
type: object
description: A single result from an async task.
properties:
url:
type: string
description: URL of the generated image. **Valid for 24 hours.**
TaskMetrics:
type: object
description: Task completion metrics.
properties:
TOTAL:
type: integer
description: Total number of images requested.
SUCCEEDED:
type: integer
description: Number of images successfully generated.
FAILED:
type: integer
description: Number of images that failed to generate.
MultimodalEmbeddingResponse:
type: object
description: Multimodal embedding response.
properties:
output:
type: object
properties:
embeddings:
type: array
description: List of embedding results.
items:
$ref: "#/components/schemas/MultimodalEmbeddingData"
usage:
type: object
description: "Token usage statistics. Fields vary by model: `tongyi-embedding-vision-*` models return `input_tokens` (combined text and image token count), `input_tokens_details`, `output_tokens`, and `total_tokens`; other models may return different fields — see individual field descriptions."
properties:
input_tokens:
type: integer
description: Number of input tokens consumed. For `tongyi-embedding-vision-*` models, this value includes both text and image/video tokens.
input_tokens_details:
type: object
description: Detailed breakdown of input tokens. Only returned by `tongyi-embedding-vision-*` models.
properties:
image_tokens:
type: integer
description: Number of tokens consumed by visual content (images or video) in the input, excluding text (see `text_tokens` for text). Image token consumption depends on input image resolution — higher resolution consumes more tokens. For video input, the system extracts frames and calculates tokens based on the extracted frames.
text_tokens:
type: integer
description: Number of tokens consumed by text content in the input (excluding images, video, and other visual content).
output_tokens:
type: integer
description: Number of output tokens. Only returned by `tongyi-embedding-vision-*` models.
total_tokens:
type: integer
description: Total token count (input_tokens + output_tokens).
image_tokens:
type: integer
description: Number of tokens consumed by visual content (images or video) in the input, excluding text. Image token consumption depends on input image resolution. For video input, the system extracts frames (up to a system-configured limit) and calculates tokens based on the extracted frames. Only returned as a top-level field by `qwen3-vl-embedding`, `qwen2.5-vl-embedding`, and `multimodal-embedding-v1`. For `tongyi-embedding-vision-*` models, image tokens are included in `input_tokens_details.image_tokens`.
request_id:
type: string
description: Unique request identifier.
example: 1fff9502-a6c5-9472-9ee1-73930fdd04c5
MultimodalEmbeddingData:
type: object
description: A single embedding result.
properties:
index:
type: integer
description: Position index in the input contents list.
embedding:
type: array
description: Vector of floating-point numbers.
items:
type: number
type:
type: string
description: Content type of this embedding.
enum:
- text
- image
- video
DashScopeErrorResponse:
type: object
description: DashScope API error response.
properties:
request_id:
type: string
description: Unique request identifier.
code:
type: string
description: Error code (e.g., `InvalidParameter`, `Throttling`, `Unauthorized`).
example: InvalidParameter
message:
type: string
description: Human-readable error message.
example: num_images_per_prompt must be 1