tencent cloud

LLM Service TokenHub

DokumentasiLLM Service TokenHubAPI Integration GuideLanguage ModelImage Understanding

Image Understanding

Unduh
Mode fokus
Ukuran font
Terakhir diperbarui: 2026-11-04 12:10:59
Diterjemahkan oleh AI

Overview

Image understanding supports the analysis of image content and can be used in scenarios such as image description, object detection, visual question answering, and chart data interpretation.

Models and APIs

Supported Models

TokenHub provides multiple models with image understanding capabilities, including dedicated multimodal models and language models with multimodal capabilities. For the complete model list and capability descriptions, see Model List.

Supported APIs

Protocol
Parameter Description
Detailed Parameter and Call Example Description
OpenAI Chat Completions
(/v1/chat/completions)
Content block type=image_url
image_url.url: Supports public network https://URL or a Base64 data URL.
image_url.detail: Supports auto, low, high, and original.
OpenAI Responses
(/v1/responses)
Content block type=input_image
image_url: Supports a public network https://URL or a Base64 data URL.
detail: Supports auto, low, high, and original.
Anthropic
(/v1/messages)
Content block type=image
source.type: Supports url and base64.
source.url: Public network https://URL.
source.media_type:image/jpeg,image/png,image/webp,image/gif
source.data: Pure Base64 encoding without the data: prefix.

Image Input Methods (URL/Base64)

Images can be passed in two ways: via URL or Base64. In the Chat Completions protocol, image data is placed in the url field of image_url. In the Responses protocol, image data is placed in the image_url field of input_image. The key differences between the two methods are as follows:
Writing back
URL Method
Base64 Method
Scenario
The image is stored in a publicly accessible location, such as COS or CDN.
The image is stored locally or on a private network, or is temporarily generated by a program.
Request body size
Extremely small (contains only the image URL)
Approximately 1.33 times the size of the original file.
Public network accessibility requirement
Must be publicly accessible
No requirements
Transmission time
Faster (only a short URL is sent), but TokenHub needs to download the image additionally, which is affected by the response speed of the image server.
Slower (the request body is approximately 1.33 times the size of the original image), but no external network access is required, making it suitable for private network/local environments.

Method 1: Passing Image URL

This applies to scenarios where images are already stored in publicly accessible locations.
Attention:
The image URL must be a publicly accessible address. For private storage, use a presigned URL or switch to Base64 encoding.
For limits such as the maximum size of a single image and the number of images per request, see Usage Instructions below.
Request structure (Chat Completions protocol):
{
  "type": "image_url",
  "image_url": {
    "url": "https://example.com/photo.jpg"
  }
}
Request structure (Responses protocol):
{
  "type": "input_image",
  "image_url": "https://example.com/photo.jpg"
}
Request structure (Anthropic protocol):
{
  "type": "image",
  "source": {
      "type": "url",
      "url": "https://example.com/photo.jpg"
      }
}

Method 2: Passing Image Base64

This applies to scenarios where images cannot be accessed over a public network. Read the image as binary data, encode it in Base64, and fill it into image_url.url in the format data:<mime>;base64,<encoded data>. Common image MIME types: image/jpeg, image/png, image/webp.
Attention:
Base64 increases the request body size by about 33%. For large images, use the URL method.
For limits such as the number of images per request, see Usage Instructions below.
Request structure (Chat Completions protocol):
{
  "type": "image_url",
  "image_url": {
    "url": "data:image/jpeg;base64,<BASE64_DATA>"
  }
}
Request structure (Responses protocol):
{
  "type": "input_image",
  "image_url": "data:image/jpeg;base64,<BASE64_DATA>"
}
Request structure (Anthropic protocol):
{
  "type": "image",
  "source": {
      "type": "base64",
      "media_type": "image/jpeg",
      "data": "<BASE64_DATA>"
      }
}

Call Example

The following examples use the OpenAI Chat Completions protocol (POST /v1/chat/completions) with the hy4 model. Images are passed in through the image_url type block in content, supporting both single-image and multi-image inputs.

Single-Image Input

cURL (Single Image URL)
Python (Single Image URL)
Python (Single Image Base64)
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/chat/completions' \\
  -H 'Authorization: Bearer YOUR_API_KEY' \\
  -H 'Content-Type: application/json' \\
  -d '{
    "model": "hy4",
    "messages": [{"role": "user", "content": [
      {"type": "image_url", "image_url": {"url": "YOUR_IMAGE_URL"}},
      {"type": "text", "text": "Please describe the content of this image and state how many animals are in it."}
    ]}],
    "stream": false
  }'
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://tokenhub-intl.tencentcloudmaas.com/v1",
)

response = client.chat.completions.create(
    model="hy4",
    messages=[{
        "role": "user",
        "content": [
            {"type": "image_url", "image_url": {"url": "YOUR_IMAGE_URL"}},
            {"type": "text", "text": "Please describe the content of this image and state how many animals are in it."},
        ],
    }],
)

print(response.choices[0].message.content)
import base64
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://tokenhub-intl.tencentcloudmaas.com/v1",
)

# Replace example.jpg with the path to your local image
with open("example.jpg", "rb") as f:
    base64_image = base64.b64encode(f.read()).decode("utf-8")

response = client.chat.completions.create(
    model="hy4",
    messages=[{
        "role": "user",
        "content": [
            {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{base64_image}"}},
            {"type": "text", "text": "Please describe the content of this image and state how many animals are in it."},
        ],
    }],
)

print(response.choices[0].message.content)
Response Example (Single Image):
{
  "id": "REPLACED_ID",
  "object": "chat.completion",
  "model": "hy4",
  "created": 1787628534,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "There are three orange kittens in this image, lying on the windowsill and basking in the sun, with a clear sky in the background."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1158,
    "completion_tokens": 36,
    "total_tokens": 1194
  }
}

Multi-Image Input

To input multiple images, place multiple image_url blocks side by side in the content array. The maximum number of input images is constrained by the context window, with no hard limit on the number of images.
cURL (Multi-Image URL)
Python (Multi-Image URL)
Python (Multi-Image Base64)
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/chat/completions' \\
  -H 'Authorization: Bearer YOUR_API_KEY' \\
  -H 'Content-Type: application/json' \\
  -d '{
    "model": "hy4",
    "messages": [{"role": "user", "content": [
      {"type": "image_url", "image_url": {"url": "YOUR_IMAGE_URL"}},
      {"type": "image_url", "image_url": {"url": "YOUR_IMAGE_URL_2"}},
      {"type": "text", "text": "Please describe the content of these two images separately"}
    ]}],
    "stream": false
  }'
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://tokenhub-intl.tencentcloudmaas.com/v1",
)

response = client.chat.completions.create(
    model="hy4",
    messages=[{
        "role": "user",
        "content": [
            {"type": "image_url", "image_url": {"url": "YOUR_IMAGE_URL"}},
            {"type": "image_url", "image_url": {"url": "YOUR_IMAGE_URL_2"}},
            {"type": "text", "text": "Please describe the content of these two images separately"},
        ],
    }],
)

print(response.choices[0].message.content)
import base64
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://tokenhub-intl.tencentcloudmaas.com/v1",
)

def load_b64(path):
    # Replace the path with your local image
    with open(path, "rb") as f:
        return base64.b64encode(f.read()).decode("utf-8")

# Replace example_a.jpg / example_b.jpg with the paths to your local images
image_a = load_b64("example_a.jpg")
image_b = load_b64("example_b.jpg")

response = client.chat.completions.create(
    model="hy4",
    messages=[{
        "role": "user",
        "content": [
            {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{image_a}"}},
            {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{image_b}"}},
            {"type": "text", "text": "Please describe the content of these two images separately"},
        ],
    }],
)

print(response.choices[0].message.content)
Response Example (Multiple Images):
{
  "id": "REPLACED_ID",
  "object": "chat.completion",
  "model": "hy4",
  "created": 1787628932,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "### Image 1\\n- Color: This image consists of two solid colors. The upper half is blue (a pure or vivid blue with high saturation and brightness), and the lower half is red (a pure or vivid red with high saturation and brightness).\\n- Composition: It uses a horizontal two-part composition (top-bottom split). The entire image is divided by a horizontal straight line (approximately at the vertical midpoint of the image) into two equal rectangular areas. The upper area is filled with blue, and the lower area is filled with red. The two color areas are roughly equal in size, creating a simple top-bottom color separation effect.\\n\\n\\n### Image 2\\n- Color: This image also consists of two solid colors. The left half is green (a vivid green or grass green with high saturation), and the right half is yellow (a bright yellow or lemon yellow with high saturation).\\n- Composition: It uses a vertical two-part composition (left-right split). The entire image is divided by a vertical straight line (approximately at the horizontal midpoint of the image) into two equal rectangular areas. The left area is filled with green, and the right area is filled with yellow. The two color areas are roughly equal in size, creating a simple left-right color separation effect.\\n"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 569,
    "completion_tokens": 231,
    "total_tokens": 800
  }
}
Note:
Before making API calls, install the OpenAI Python SDK first: pip install openai.
Text and images can be mixed: the order of text and image_url in the content array is the order in which the model receives them.
The response structure is the same for multi-image Base64 and multi-image URL input methods, with the only difference being how the images are passed in.

Usage Instructions

Supported Image Formats

Supported formats are four common image formats: JPEG, PNG, WEBP, and non-animated GIF.
If you need to use image formats other than the four listed above, verify them through your own testing before integration, and use them in production only after confirming that the model can parse them properly.

Image Quantity Description

The number of images that can be passed in a single request is limited by the context window of the selected model. When the total input tokens (text + all images + output) exceed the model's context window, the information is truncated or the request is rejected.
For the model context window, see Model List.
Example (using a 16k context window):
When the image resolution is high (such as 1024×1024), each image consumes approximately 1,058 tokens, and the number of images that can be passed in a single request is approximately:
16000 ÷ 1058 ≈ 15 images
When the image resolution is medium (such as 768×768), each image consumes approximately 602 tokens, and the number that can be passed in a single request is approximately:
16000 ÷ 602 ≈ 26 images
Note:
The quality of model responses is affected by the amount of information in the input images. Too many images can degrade response quality, so keep the number of images per request within a reasonable range.
The above quantity estimates are based on the image Token consumption logic of the HY-Vision model series. Third-party vision models may use different image Token algorithms and have their own image quantity limits. The actual number of images that can be passed should be verified through testing with the corresponding model.
Specific limits on the number, size, and format of images vary by model and may change with version updates. Verify them through testing before integration.

Image File Size

Transfer Method
Recommended Size per Image
Request Body Size Limit
URL method
Recommended not to exceed 10 MB
Not exceed 100 MB
Base64 method
Recommended not to exceed 10 MB
Not exceed 100 MB (Base64 encoding increases the data size by about 1.33 times. In multi-image scenarios, pay attention to the accumulated size.).
Note:
TokenHub does not impose special restrictions on image uploads. It only limits the size of a single file to no more than 100 MB. Therefore, the upper limits on image dimensions, quantity, and format generally come from the model side, including the model's context window and its own constraints. For the actual usable range, refer to the official documentation of the selected model and the actual response returned by the API.
For specific limits of third-party vision models (Kimi / DeepSeek / MiniMax / GLM, and so on), see the corresponding model's API guide or its official documentation.


Topik sebelumnya: Preserved ThinkingTopik selanjutnya: Responses API Compatibility Mode

Bantuan dan Dukungan

Apakah halaman ini membantu?

masukan

Search
    Enter keywords to search documentation