Run vision and reasoning inference

Send an image and a question to POST /v3/chat/completions and read the model’s answer directly from the response. This example uses glm-5.3 for scene understanding. For image, video, and speech generation, use the separate asynchronous model-job quickstart.

Create a key and fund your wallet

Create an API key with chat:write access.
Fund the API wallet. It is separate from Studio subscription credits.
Set your key in the terminal where you will run the example:

export HEDRA_API_KEY="<key_id>:<secret>"

Keep the key server-side. If another integration uses the same environment variable, use a separate terminal for this example.

Check model capabilities

curl --fail-with-body https://api.hedra.com/v3/models/glm-5.3

Read chat.input_modalities, chat.max_images_per_request, input_schema, and chat.pricing. GLM-5.3 accepts text and image inputs; model limits and availability can change. The image URL must be accessible to the service. This example uses a public robot-lab image; replace it with an HTTPS image URL you want to analyze.

Understand a scene

Each example makes a billable request and prints the answer. It uses low reasoning effort and a 4,096-token output budget. Reasoning tokens count toward this budget.

Python
TypeScript
cURL

Install the OpenAI client:

python -m pip install openai

Save as quickstart.py and run python quickstart.py:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["HEDRA_API_KEY"],
    base_url="https://api.hedra.com/v3",
    timeout=130.0,
    max_retries=0,
)
response = client.chat.completions.create(
    model="glm-5.3",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "List the visible objects and their spatial relationships. Describe only what the image shows."},
            {"type": "image_url", "image_url": {"url": "https://imagedelivery.net/yn_JX_LzJpQI9TTynGwR_Q/www-redesign/training/hero-robot-lab-20261019/public"}},
        ],
    }],
    reasoning_effort="low",
    max_tokens=4096,
)
choice = response.choices[0]
if choice.finish_reason != "stop" or not choice.message.content:
    raise RuntimeError(f"No complete answer; finish_reason={choice.finish_reason}")
print(choice.message.content)

Use Node.js 20 or later. Install the OpenAI client and TypeScript runner:

npm install openai
npm install --save-dev tsx typescript @types/node

Save as quickstart.mts and run npx tsx quickstart.mts:

import OpenAI from "openai";

const apiKey = process.env.HEDRA_API_KEY;
if (!apiKey) throw new Error("Set HEDRA_API_KEY first");
const client = new OpenAI({
  apiKey,
  baseURL: "https://api.hedra.com/v3",
  timeout: 130_000,
  maxRetries: 0,
});
const response = await client.chat.completions.create({
  model: "glm-5.3",
  messages: [{
    role: "user",
    content: [
      { type: "text", text: "List the visible objects and their spatial relationships. Describe only what the image shows." },
      { type: "image_url", image_url: { url: "https://imagedelivery.net/yn_JX_LzJpQI9TTynGwR_Q/www-redesign/training/hero-robot-lab-20261019/public" } },
    ],
  }],
  reasoning_effort: "low",
  max_tokens: 4096,
});
const choice = response.choices[0];
if (choice?.finish_reason !== "stop" || !choice.message.content) {
  throw new Error(`No complete answer; finish_reason=${choice?.finish_reason}`);
}
console.log(choice.message.content);

Requires Bash, cURL with --fail-with-body support, and jq. Save as quickstart.sh and run bash quickstart.sh:

#!/usr/bin/env bash
set -euo pipefail
: "${HEDRA_API_KEY:?Set HEDRA_API_KEY first}"
RESPONSE=$(curl --fail-with-body --silent --show-error --max-time 130 \
  https://api.hedra.com/v3/chat/completions \
  -H "Authorization: Bearer $HEDRA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "glm-5.3",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "List the visible objects and their spatial relationships. Describe only what the image shows."},
      {"type": "image_url", "image_url": {"url": "https://imagedelivery.net/yn_JX_LzJpQI9TTynGwR_Q/www-redesign/training/hero-robot-lab-20261019/public"}}
    ]
  }],
  "reasoning_effort": "low",
  "max_tokens": 4096
}
JSON
)
printf '%s' "$RESPONSE" | jq -er '
  .choices[0] | if .finish_reason == "stop" and (.message.content | length) > 0
  then .message.content else error("No complete answer; inspect finish_reason") end
'

Expected result: a text description of the input image, returned in choices[0].message.content. The wording can vary. Check finish_reason; a length result can mean reasoning exhausted the output budget. See reasoning and output budgets. A model’s description is an interpretation of the image, not a measurement of the scene.

Reason over observations

For a text-only task, replace the message’s content with a string:

{
  "model": "glm-5.3",
  "messages": [{
    "role": "user",
    "content": "Observations: a box is on a workbench; its label is obscured; the shelf is empty. Summarize what is known and what additional observations are needed to identify the box."
  }],
  "reasoning_effort": "low",
  "max_tokens": 4096
}

This uses the same endpoint and response shape. For streaming, tool calls, errors, and compatibility details, continue with the chat guide.

Choose the next step

Choose a model

Compare supported inputs, limits, and pricing.

Run a model job

Submit, poll, and download image, video, or audio outputs.

Platform and availability

Understand managed inference, World Model Runtime, and research previews.

Connect an AI client

Use the tools exposed by the Hedra MCP server.

Start here

Managed inference

Production operations

SDKs and tools

Language API reference

API Reference

Resources

Run vision and reasoning inference

Create a key and fund your wallet

Check model capabilities

Understand a scene

Reason over observations

Choose the next step

Choose a model

Run a model job

Platform and availability

Connect an AI client

​Create a key and fund your wallet

​Check model capabilities

​Understand a scene

​Reason over observations

​Choose the next step

Choose a model

Run a model job

Platform and availability

Connect an AI client

Create a key and fund your wallet

Check model capabilities

Understand a scene

Reason over observations

Choose the next step