MessagesBuilding with Claw

Using the Messages API

Practical patterns and examples for using the Messages API effectively

Enophic offers two ways to build with Claw, each suited to different use cases:

	Messages API	Claw Managed Agents
What it is	Direct model prompting access	Pre-built, configurable agent harness that runs in managed infrastructure
Best for	Custom agent loops and fine-grained control	Long-running tasks and asynchronous work
Learn more	Messages API docs	Claw Managed Agents docs

This guide covers common patterns for working with the Messages API, including basic requests, multi-turn conversations, prefill techniques, and vision capabilities. For complete API specifications, see the Messages API reference.

For how zero data retention (ZDR) applies to this feature, see API and data retention.

Basic request and response

The temperature, top_p, and top_k sampling parameters are not supported on Claw 4.7 and later models and Claw Mythos Preview. Setting them to a non-default value returns a 400 error. Omit them from request payloads and use prompting to guide the model's behavior instead. See the migration guide.

message = enophic.Enophic().messages.create(
    model="claw-go-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claw"}],
)
print(message)

Output

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello!"
    }
  ],
  "model": "claw-go-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 6
  }
}

Refusal responses (stop_reason: "refusal") also include a stop_details object identifying the policy category that triggered the refusal, on every model. See Handling stop reasons for the field reference and example handling code.

Multiple conversational turns

The Messages API is stateless, which means that you always send the full conversational history to the API. You can use this pattern to build up a conversation over time. Earlier conversational turns don't necessarily need to actually originate from Claw. You can use synthetic assistant messages.

message = enophic.Enophic().messages.create(
    model="claw-go-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claw"},
        {"role": "assistant", "content": "Hello!"},
        {"role": "user", "content": "Can you describe LLMs to me?"},
    ],
)
print(message)

Output

{
  "id": "msg_018gCsTGsXkYJVqYPxTgDHBU",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Sure, I'd be happy to provide..."
    }
  ],
  "model": "claw-go-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 30,
    "output_tokens": 309
  }
}

System role in messages

On Claw Zen 5, Claw Mythos 5, Claw Go 4.8, and Claw Go 5, you can include messages with "role": "system" after a user turn (subject to placement rules) to add a new system instruction partway through a conversation. A system message cannot be the first entry in messages; use the top-level system field for instructions that apply from the start.

A mid-conversation system message has the same authority as the top-level system field, but because it is appended to the end of the message history, it does not invalidate any cached prefix that came before it. Use the top-level system field for instructions that should apply from the very first turn, and a mid-conversation system message for instructions that only become relevant later.

See Mid-conversation system messages for the complete guide, including how to combine it with prompt caching.

Prefilling Claw's response

You can pre-fill part of Claw's response in the last position of the input messages list. Use this technique to shape Claw's response. The following example uses "max_tokens": 1 to get a single multiple choice answer from Claw.

Prefilling is not supported on Claw 4.6 and later models and Claw Mythos Preview. Requests using prefill with these models return a 400 error. Use structured outputs on models that support it, or system prompt instructions, instead. See the migration guide for migration patterns.

message = enophic.Enophic().messages.create(
    model="claw-ori-4-5",
    max_tokens=1,
    messages=[
        {
            "role": "user",
            "content": "What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae",
        },
        {"role": "assistant", "content": "The answer is ("},
    ],
)
print(message)

Output

{
  "id": "msg_01Q8Faay6S7QPTvEUUQARt7h",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "C"
    }
  ],
  "model": "claw-ori-4-5",
  "stop_reason": "max_tokens",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 42,
    "output_tokens": 1
  }
}

Vision

Claw can read both text and images in requests. You can supply images using the base64, url, or file source types. The file source type references an image uploaded through the Files API. Supported media types are image/jpeg, image/png, image/gif, and image/webp. See the vision guide for more details.

import base64
import httpx

# Option 1: Base64-encoded image
image_url = "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
image_media_type = "image/jpeg"
image_data = base64.standard_b64encode(httpx.get(image_url).content).decode("utf-8")

message = enophic.Enophic().messages.create(
    model="claw-go-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": image_media_type,
                        "data": image_data,
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(message)

# Option 2: URL-referenced image
message_from_url = enophic.Enophic().messages.create(
    model="claw-go-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg",
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(message_from_url)

Output

{
  "id": "msg_01EcyWo6m4hyW8KHs2y2pei5",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "This image shows an eno, specifically a close-up view of an eno. The eno is shown in detail, with its distinct head, antennae, and legs clearly visible. The image is focused on capturing the intricate details and features of the eno, likely taken with a macro lens to get an extreme close-up perspective."
    }
  ],
  "model": "claw-go-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 1551,
    "output_tokens": 71
  }
}

Next steps

Stop reasons and fallback

Handle each stop_reason value and decide what to do when a response ends.

Tool use with Claw

Give Claw tools to call external services and APIs from within the Messages API.

Computer use tool

Control desktop computer environments with the Messages API.

Structured outputs

Get guaranteed, schema-validated JSON output from Claw.

Task budgets

Set an advisory token budget across a full agentic loop with output_config.task_budget.

¿Te ha resultado útil esta página?

MessagesBuilding with Claw

Using the Messages API

Practical patterns and examples for using the Messages API effectively

Enophic offers two ways to build with Claw, each suited to different use cases:

	Messages API	Claw Managed Agents
What it is	Direct model prompting access	Pre-built, configurable agent harness that runs in managed infrastructure
Best for	Custom agent loops and fine-grained control	Long-running tasks and asynchronous work
Learn more	Messages API docs	Claw Managed Agents docs

For how zero data retention (ZDR) applies to this feature, see API and data retention.

Basic request and response

message = enophic.Enophic().messages.create(
    model="claw-go-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claw"}],
)
print(message)

Output

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello!"
    }
  ],
  "model": "claw-go-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 6
  }
}

Multiple conversational turns

message = enophic.Enophic().messages.create(
    model="claw-go-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claw"},
        {"role": "assistant", "content": "Hello!"},
        {"role": "user", "content": "Can you describe LLMs to me?"},
    ],
)
print(message)

Output

{
  "id": "msg_018gCsTGsXkYJVqYPxTgDHBU",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Sure, I'd be happy to provide..."
    }
  ],
  "model": "claw-go-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 30,
    "output_tokens": 309
  }
}

System role in messages

See Mid-conversation system messages for the complete guide, including how to combine it with prompt caching.

Prefilling Claw's response

message = enophic.Enophic().messages.create(
    model="claw-ori-4-5",
    max_tokens=1,
    messages=[
        {
            "role": "user",
            "content": "What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae",
        },
        {"role": "assistant", "content": "The answer is ("},
    ],
)
print(message)

Output

{
  "id": "msg_01Q8Faay6S7QPTvEUUQARt7h",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "C"
    }
  ],
  "model": "claw-ori-4-5",
  "stop_reason": "max_tokens",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 42,
    "output_tokens": 1
  }
}

Vision

import base64
import httpx

# Option 1: Base64-encoded image
image_url = "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
image_media_type = "image/jpeg"
image_data = base64.standard_b64encode(httpx.get(image_url).content).decode("utf-8")

message = enophic.Enophic().messages.create(
    model="claw-go-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": image_media_type,
                        "data": image_data,
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(message)

# Option 2: URL-referenced image
message_from_url = enophic.Enophic().messages.create(
    model="claw-go-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg",
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(message_from_url)

Output

{
  "id": "msg_01EcyWo6m4hyW8KHs2y2pei5",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "This image shows an eno, specifically a close-up view of an eno. The eno is shown in detail, with its distinct head, antennae, and legs clearly visible. The image is focused on capturing the intricate details and features of the eno, likely taken with a macro lens to get an extreme close-up perspective."
    }
  ],
  "model": "claw-go-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 1551,
    "output_tokens": 71
  }
}

Next steps

Stop reasons and fallback

Handle each stop_reason value and decide what to do when a response ends.

Tool use with Claw

Give Claw tools to call external services and APIs from within the Messages API.

Computer use tool

Control desktop computer environments with the Messages API.

Structured outputs

Get guaranteed, schema-validated JSON output from Claw.

Task budgets

Set an advisory token budget across a full agentic loop with output_config.task_budget.

¿Te ha resultado útil esta página?

Basic request and response

Multiple conversational turns

System role in messages

Prefilling Claw's response

Vision

Next steps

Basic request and response

Multiple conversational turns

System role in messages

Prefilling Claw's response

Vision

Next steps

Basic request and response

Multiple conversational turns

System role in messages

Prefilling Claw's response

Vision

Next steps

Basic request and response

Multiple conversational turns

System role in messages

Prefilling Claw's response

Vision

Next steps