TextClaudeClaude

Claude - Messages API

Send a structured list of input messages with text and/or image content, and the model will generate the next message in the conversation.

The Messages API can be used for either single queries or stateless multi-turn conversations.

<Note> **BaseURL**: The default BaseURL is `https://api.starmagic.ai`, which has better support for text models and long-lived connections. `https://api.starmagic.ai` is the primary endpoint for multimodal services and serves as a fallback address for text models. </Note>

Authorization

AuthorizationstringheaderRequired

##All APIs require Bearer Token authentication## **Get API Key:** Visit [API Key Management Page](https://starmagic.ai/app/api-keys) to get your API Key **Add to request header:** ``` Authorization: Bearer YOUR_API_KEY ```

Authorization: Bearer YOUR_API_KEY

Request body

application/json

The model that will complete your prompt.

"claude-haiku-4-5-20251001"

messagesobject[]Required

Input messages. Our models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn. Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages.

[
  {
    "content": null,
    "role": "user"
  }
]

max_tokensintegerRequired

The maximum number of tokens to generate before stopping. Note that our models may stop _before_ reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate.

inference_geostring

Specifies the geographic region for inference processing. If not specified, the workspace's `default_inference_geo` is used.

"string"

containerobject

Container identifier for reuse across requests.

context_managementobject

Context management configuration.

mcp_serversobject[]

MCP servers to be utilized in this request

[
  {
    "authorization_token": null,
    "name": "string",
    "tool_configuration": null,
    "type": "string",
    "url": "string"
  }
]

metadataobject

{
  "user_id": null
}

output_configobject

{
  "effort": "low",
  "format": {
    "schema": {},
    "type": "string"
  },
  "task_budget": {
    "remaining": 0,
    "total": 0,
    "type": "string"
  }
}

service_tierenum<auto | standard_only>

Determines whether to use priority capacity (if available) or standard capacity for this request.

"auto"

stop_sequencesstring[]

Custom text sequences that will cause the model to stop generating.

[
  "string"
]

streamboolean

Whether to incrementally stream the response using server-sent events.

true

systemobject

System prompt.

temperaturenumber

Amount of randomness injected into the response. Defaults to `1.0`. Ranges from `0.0` to `1.0`.

thinkingobject

Configuration for enabling Claude's extended thinking. `type: "enabled"` requires `budget_tokens`, with a minimum of 1,024, and counts against `max_tokens`. You can use `display` to control how thinking content appears. `type: "adaptive"` lets Claude decide when and how much extended thinking to use based on request complexity; you can also use `display` to control how thinking content appears. `type: "disabled"` turns off extended thinking.

tool_choiceobject

How the model should use the provided tools.

toolsobject[]

Definitions of tools that the model may use.

[
  null
]

top_kinteger

Only sample from the top K options for each subsequent token.

top_pnumber

Use nucleus sampling.

Response

application/json

成功

Response body

idstringRequired

Unique object identifier. The format and length of IDs may change over time.

"string"

typestringRequired

Object type. For Messages, this is always `"message"`.

"string"

rolestringRequired

Conversational role of the generated message. This will always be `"assistant"`.

"string"

contentobject[]Required

Content generated by the model. This is an array of content blocks, each of which has a `type` that determines its shape.

[
  null
]

The model that handled the request.

"claude-haiku-4-5-20251001"

The reason that we stopped.

"end_turn"

stop_sequencestringRequired

Which custom stop sequence was generated, if any.

"string"

usageobjectRequired

{
  "cache_creation": null,
  "cache_creation_input_tokens": null,
  "cache_read_input_tokens": null,
  "input_tokens": 0,
  "output_tokens": 0,
  "server_tool_use": null,
  "service_tier": null
}

context_managementobject

Context management response.

containerobject

Information about the container used in this request.

POST/v1/messages

curl --request POST \
  --url https://api.starmagic.ai/v1/messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "claude-sonnet-4-5-20250929",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Hello, world"
    }
  ]
}'

Response: 成功

{
  "model": "claude-haiku-4-5-20251001",
  "id": "msg_bdrk_017XLrAa77zWvfBGQ6ESvrxz",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "# Hey there! 👋\n\nHow's it going? What can I help you with today?"
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 8,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0,
    "output_tokens": 24
  }
}