DigitalOcean API (unofficial showcase)
POST/v1/messages

Create the next assistant message

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

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

15 body fields
modelstringrequired
Model ID (for example `claude-opus-4-6` or a serverless model id).
max_tokensintegerrequired
Maximum tokens to generate before stopping.
messagesarray<object>required
Conversation turns. Each item has `role` `user` or `assistant` and `content` as a string or an array of content blocks.
systemstringoptional
System prompt as plain text or as an array of text blocks.
stop_sequencesarray<string>optional
Custom strings that stop generation when produced.
streambooleanoptional
When true, the response is streamed using server-sent events (SSE).
Default:false
temperaturenumberoptional
Sampling temperature between 0.0 and 1.0.
top_pnumberoptional
Nucleus sampling; use either `temperature` or `top_p`, not both.
top_kintegeroptional
Top-K sampling cutoff.
toolsarray<object>optional
Tool definitions the model may invoke.
tool_choicestringoptional
Controls how the model uses tools: automatic selection, require any tool, force a specific tool, or a string form accepted by the service.
metadataobjectoptional
Optional request metadata.
reasoning_effortstringoptional
DigitalOcean extension for reasoning-capable models. Ignored by executors that do not support it.
Allowed:noneminimallowmediumhighxhigh
speedstringoptional
DigitalOcean extension for preferred inference speed. Ignored when not supported.
Allowed:standardfast
thinkingobjectoptional
Extended thinking configuration. Executors that do not support thinking may ignore this field.

6 status codes
200Successful generation. When `stream` is true, the body is `text/event-stream` with server-sent event (SSE) payloads; otherwise `application/json` with `CreateMessageResponse`.
idstringrequired
Unique identifier for this message object.
typestringrequired
Object type discriminator.
Allowed:message
rolestringrequired
Always `assistant` for this response.
Allowed:assistant
contentarray<object>required
Assistant output blocks (`text` and/or `tool_use`).
modelstringrequired
Model that produced the message.
stop_reasonstringrequired
Why generation stopped.
Allowed:end_turnmax_tokensstop_sequencetool_use
stop_sequencestringoptional
When `stop_reason` is `stop_sequence`, the sequence that matched.
usageobjectrequired
Token usage for a non-streaming `POST /v1/messages` response.
400Invalid request body, validation error, or policy rejection.
typestringrequired
Allowed:error
errorobjectrequired
401Authentication failed due to invalid credentials.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
429The API rate limit has been exceeded.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
500There was a server error.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
defaultThere was an unexpected error.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Error handling

A 400 is returned: Invalid request body, validation error, or policy rejection. A 401 is returned: Authentication failed due to invalid credentials. A 429 is returned: The API rate limit has been exceeded. A 500 is returned: There was a server error. Any other status is an error: There was an unexpected error.