Skip to main content
POST
/
v1
/
messages

​
Authorization

  • Auth Type: Bearer Auth (In: header)
  • Format: Authorization: Bearer <YOUR_API_KEY>
  • Description: Use Bearer <YOUR_API_KEY>. Format: Authorization: Bearer sk-xxxxxx.
  • API Key: where API Key is your AGCloud API KEY

​
Response Examples

​
Async Chat Response Field Description

FieldTypeRangeDescription
idstring-The current chat task id.
objectstring-The type of object returned by the API. In this case it is always task.
statusstringpending
processing
success
failed		Current status of the task.
created_atnumber-Unix timestamp (in seconds) indicating when the task was created.

​
Parameters

FieldTypeRequiredDefaultDescription
modelstring✅-The model ID to use for this request.
messagesarray<object>✅-An array of message objects representing the conversation history. See Messages Structure.
max_tokensinteger✅4096The maximum number of tokens the model can generate in the response. Range 1-32000
asyncboolean-falseWhether to return an asynchronous response. Only supported for non-streaming requests.
streamboolean-falseIf true, returns a stream of server-sent events (SSE) as the response is generated.
systemstring | array<object>--System prompt that sets the behavior and context for the assistant.
temperaturenumber-1.0Controls the randomness of the output. Lower values produce more focused responses, higher values produce more creative outputs. Range 0.0-1.0
top_pnumber-1.0Nucleus sampling parameter. The model considers tokens with top_p cumulative probability mass. Range 0.0-1.0
top_kinteger--Limits token selection to the K most probable tokens at each step.
stop_sequencesarray<string>--An array of strings that will stop generation when encountered.
If both stream and async are true, stream takes precedence.

​
Messages Array Structure

FieldTypeRequiredDescription
rolestring✅The role of the message. Can be: user or assistant
contentstring | array<object>✅The content of the message. Can be a simple string for text-only messages, or an array of content blocks for multimodal content.
>content.typestring✅The type of the content block. Detail see Content.Type
>content.textstring✅ if type=textThe text content of the message.
>content.sourceobject✅ if type not textThe source of the document or image. see Multimodal input
>>content.source.typestring✅The source type. Supported values: base64, url
>>content.source.media_typestring✅ if source.type=base64MIME type of the file. Supported values: application/pdf, text/plain, text/markdown, text/csv, image/png, image/jpeg, image/gif, image/webp
>>content.source.datastring✅ if source.type=base64The base64-encoded file data.
>>content.source.urlstring✅ if source.type=urlThe URL of the file to analyze.

​
Multimodal input

{
    "model": "claude-haiku-4-5-20251001",
    "max_tokens": 1024,
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "What is shown in this image?"
                },
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://robohash.org/13.png"
                    }
                }
            ]
        }
    ]
}

​
Content Type Description

FieldDescription
textPlain text content for the user message or assistant response. Use with the text field.
imageImage content provided via source. Supports base64-encoded data or a URL.
documentDocument file provided via source. Use for processing PDF, plain text, Markdown, or CSV files. Supports base64-encoded data or a URL.
fileGeneral file content provided via source. Automatically determines handling based on the media_type. Supports base64-encoded data or a URL.
file_dataInline file data using base64 encoding. Provide the file content directly via data and media_type fields without a source wrapper.