> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiandgpu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat - Response

> Create an chat message

export const OpenAIChatResponseRequest = ({model = "gpt-5.1", path = "/v1/responses"}) => {
  const curlExample = `curl --request POST \\
  --url https://aiandgpu.com${path} \\
  --header 'Authorization: Bearer <YOUR_API_KEY>' \\
  --header 'Content-Type: application/json' \\
  --data '{
    "model": "${model}",
    "input": [
        {
            "role": "user",
            "content": [
              {
                "type": "input_text", 
                "text": "Hello"
              }
            ]
        }
    ]
}'`;
  const pythonExample = `import requests

url = "https://aiandgpu.com${path}"

payload = {
    "model": "${model}",
    "input": [
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "Hello"
                }
            ]
        }
    ]
}

headers = {
    "Authorization": "Bearer <YOUR_API_KEY>",
    "Content-Type": "application/json",
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())`;
  const jsExample = `const response = await fetch('https://aiandgpu.com${path}', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <YOUR_API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: '${model}',
    input: [
      {
        role: 'user', 
        content: [
          {
            type: 'input_text', 
            text: 'Hello'
          }
        ]
      }
    ]
  })
});

const data = await response.json();
console.log(data);`;
  const goExample = `package main

import (
\t"fmt"
\t"io"
\t"net/http"
\t"strings"
)

func main() {
\turl := "https://aiandgpu.com${path}"

\tpayload := strings.NewReader("{\\"model\\": \\"${model}\\", \\"input\\": [{\\"role\\": \\"user\\", \\"content\\": [{\\"type\\": \\"input_text\\", \\"text\\": \\"Hello\\"}]}]}")

\treq, _ := http.NewRequest("POST", url, payload)

\treq.Header.Add("Authorization", "Bearer <YOUR_API_KEY>")
\treq.Header.Add("Content-Type", "application/json")

\tres, _ := http.DefaultClient.Do(req)
\tdefer res.Body.Close()

\tbody, _ := io.ReadAll(res.Body)
\tfmt.Println(string(body))
}`;
  const javaExample = `import java.net.http.*;
import java.net.URI;

HttpClient client = HttpClient.newHttpClient();

String body = """
{
  "model": "${model}",
  "input": [
    {
      "role": "user",
      "content": [{"type": "input_text", "text": "Hello"}]
    }
  ]
}
""";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://aiandgpu.com${path}"))
    .header("Authorization", "Bearer <YOUR_API_KEY>")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());`;
  const phpExample = `<?php

$curl = curl_init();

$payload = json_encode([
    'model' => '${model}',
    'input' => [
        [
            'role' => 'user',
            'content' => [
                ['type' => 'input_text', 'text' => 'Hello']
            ]
        ]
    ]
]);

curl_setopt_array($curl, [
    CURLOPT_URL => "https://aiandgpu.com${path}",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer <YOUR_API_KEY>",
        "Content-Type: application/json",
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;`;
  const csharpExample = `using System.Net.Http;
using System.Text;

var client = new HttpClient();

var payload = @"{
    ""model"": ""${model}"",
    ""input"": [
        {
            ""role"": ""user"",
            ""content"": [{""type"": ""input_text"", ""text"": ""Hello""}]
        }
    ]
}";

var request = new HttpRequestMessage(HttpMethod.Post, "https://aiandgpu.com${path}");
request.Headers.Add("Authorization", "Bearer <YOUR_API_KEY>");
request.Content = new StringContent(payload, Encoding.UTF8, "application/json");

var response = await client.SendAsync(request);
var content = await response.Content.ReadAsStringAsync();
Console.WriteLine(content);`;
  return <>
      <h2>Request Examples</h2>

      <CodeGroup>
        <CodeBlock language="shellscript" filename="cURL">
          {curlExample}
        </CodeBlock>
        <CodeBlock language="python" filename="Python">
          {pythonExample}
        </CodeBlock>
        <CodeBlock language="javascript" filename="JavaScript">
          {jsExample}
        </CodeBlock>
        <CodeBlock language="go" filename="Go">
          {goExample}
        </CodeBlock>
        <CodeBlock language="java" filename="Java">
          {javaExample}
        </CodeBlock>
        <CodeBlock language="php" filename="PHP">
          {phpExample}
        </CodeBlock>
        <CodeBlock language="csharp" filename="C#">
          {csharpExample}
        </CodeBlock>
      </CodeGroup>
    </>;
};

export const OpenAIApiResponse = ({successJson, successTitle = "200 - Success", streaming = false}) => {
  const error400 = `{
    "error": {
        "code": "invalid_params",
        "message": "parameter 'ARGUMENT' is required",
        "param": null,
        "type": "invalid_request_error"
    }
}`;
  const error401 = `{
    "error": {
        "code": "auth_invalid",
        "message": "Invalid API Key",
        "param": null,
        "type": "authentication_error"
    }
}`;
  const error402 = `{
    "error": {
        "code": "insufficient_quota",
        "message": "You exceeded your current quota, please check your plan and billing details.",
        "param": null,
        "type": "insufficient_quota_error"
    }
}`;
  const error403 = `{
    "error": {
        "code": "permission_error",
        "message": "You have no permission to access the model.",
        "type": "permission_error",
        "param": null
    }
}`;
  const error404 = `{
    "error": {
        "code": "invalid_request_error",
        "message": "Invalid URL",
        "param": null,
        "type": "invalid_request_error"
    }
}`;
  const error429 = `{
    "error": {
        "code": "rate_limit_exceeded",
        "message": "Rate limit reached",
        "param": null,
        "type": "rate_limit_error"
    }
}`;
  const error500 = `{
    "error": {
        "code": "server_error",
        "message": "Internal server error",
        "param": null,
        "type": "server_error"
    }
}`;
  return <>
      <h2>Response Examples</h2>

      <CodeGroup>
        <CodeBlock language={streaming ? "text" : "json"} filename={streaming ? "200 - Streaming Response (SSE)" : successTitle}>
          {successJson}
        </CodeBlock>
        <CodeBlock language="json" filename="400 - Bad Request">
          {error400}
        </CodeBlock>
        <CodeBlock language="json" filename="401 - Unauthorized">
          {error401}
        </CodeBlock>
        <CodeBlock language="json" filename="402 - Insufficient Balance">
          {error402}
        </CodeBlock>
        <CodeBlock language="json" filename="403 - Permission Denied">
          {error403}
        </CodeBlock>
        <CodeBlock language="json" filename="404 - Invalid URL">
          {error404}
        </CodeBlock>
        <CodeBlock language="json" filename="429 - Too Many Requests">
          {error429}
        </CodeBlock>
        <CodeBlock language="json" filename="500 - Internal Server Error">
          {error500}
        </CodeBlock>
      </CodeGroup>
    </>;
};

## 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 <strong>API Key</strong> is your <a href="https://developer.aiandgpu.com" target="_blank" rel="noopener noreferrer">AGCloud API KEY</a>

<OpenAIChatResponseRequest model="gpt-4.1" />

<OpenAIApiResponse
  successJson={`{
"id": "resp_00b60c3c229cdbe20069a6c911d57881908b4a565c719a44d8",
"object": "response",
"created_at": 1772538129,
"status": "completed",
"background": false,
"completed_at": 1772538131,
"content_filters": [
    {
        "blocked": false,
        "source_type": "completion",
        "content_filter_raw": [],
        "content_filter_results": {},
        "content_filter_offsets": {
            "start_offset": 0,
            "end_offset": 87,
            "check_offset": 0
        }
    }
],
"error": null,
"frequency_penalty": 0.0,
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"max_tool_calls": null,
"model": "gpt-4.1",
"output": [
    {
        "id": "msg_00b60c3c229cdbe20069a6c91335808190831476ba4f2113a6",
        "type": "message",
        "status": "completed",
        "content": [
            {
                "type": "output_text",
                "annotations": [],
                "logprobs": [],
                "text": "白天写码夜加班，  \n键盘一敲到天残。  \n产品一改重开干，  \n测试一过又返还。  \n\nBug如星满天漫，  \n需求似海没岸边。  \n人生苦短须尽欢，  \n能跑上线就算圆。"
            }
        ],
        "role": "assistant"
    }
],
"parallel_tool_calls": true,
"presence_penalty": 0.0,
"previous_response_id": null,
"prompt_cache_key": null,
"prompt_cache_retention": null,
"reasoning": {
    "effort": "none",
    "summary": null
},
"safety_identifier": null,
"service_tier": "default",
"store": true,
"temperature": 1.0,
"text": {
    "format": {
        "type": "text"
    },
    "verbosity": "medium"
},
"tool_choice": "auto",
"tools": [],
"top_logprobs": 0,
"top_p": 1.0,
"truncation": "disabled",
"usage": {
    "input_tokens": 17,
    "input_tokens_details": {
        "cached_tokens": 0
    },
    "output_tokens": 76,
    "output_tokens_details": {
        "reasoning_tokens": 0
    },
    "total_tokens": 93
},
"user": null,
"metadata": {}
}`}
/>

## Request Parameters

### Core Parameters

| Field            | Type                      | Required | Range                                                        | Description                                                                                                                           |
| :--------------- | :------------------------ | :------- | :----------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------ |
| `model`          | `string`                  | ✅        | -                                                            | The model ID                                                                                                                          |
| `input`          | `string \| array<object>` | ✅        | -                                                            | Input content for the model.                                                                                                          |
| `>input.role`    | `string`                  | ✅        | `user` <br /> `assistant` <br /> `system` <br /> `developer` | The role of the message input. One of user, assistant, system, or developer.                                                          |
| `>input.content` | `string \| array`         | ✅        | -                                                            | A text input to the model when string; a list of one or many input items to the model, containing different content types when array. |

### Multimodal Input

<CodeGroup>
  ```json Input text theme={null}
  {
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "Who are you?"
      }
    ]
  }
  ```

  ```json Input image theme={null}
  {
    "role": "user",
    "content": [
      {
        "type": "input_image",
        "image_url": "https://robohash.org/OYK.png"
      }
    ]
  }
  ```

  ```json Input file theme={null}
  {
    "role": "user",
    "content": [
      {
        "type": "input_file",
        "filename": "file.pdf",
        "file_url": "<Your remote pdf file url here>"
      }
    ]
  }
  ```
</CodeGroup>

### Input Parameters

| Field       | Type     | Required | Range         | Description                                                                      |
| :---------- | :------- | :------- | :------------ | :------------------------------------------------------------------------------- |
| `type`      | `string` | ✅        | -             | The type of content block. Supported: `input_text`, `input_image`, `input_file`. |
| `text`      | `string` | -        | `input_text`  | The text content of the input.                                                   |
| `image_url` | `string` | -        | `input_image` | The URL of the image to send to the model.                                       |
| `filename`  | `string` | -        | `input_file`  | The name of the file being uploaded.                                             |
| `file_url`  | `string` | -        | `input_file`  | The URL of the file to send to the model.                                        |

### Advanced Parameters

| Field                  | Type               | Required | Range                | Description                                                                                                                                     |
| :--------------------- | :----------------- | :------- | :------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------- |
| `instructions`         | `string`           | -        | -                    | System instructions that the model should follow when generating a response.                                                                    |
| `max_output_tokens`    | `integer`          | -        | -                    | The maximum number of tokens the model can generate in the response.                                                                            |
| `temperature`          | `number`           | -        | `0.0` - `2.0`        | Controls the randomness of the output. Lower values produce more focused responses, higher values produce more creative outputs.                |
| `top_p`                | `number`           | -        | `0.0` - `1.0`        | Nucleus sampling parameter. The model considers tokens with top\_p cumulative probability mass.                                                 |
| `stream`               | `boolean`          | -        | -                    | If `true`, returns a stream of server-sent events (SSE) as the response is generated.                                                           |
| `tools`                | `array<object>`    | -        | -                    | A list of tools the model may call. Use this to provide functions the model can generate JSON inputs for.                                       |
| `tool_choice`          | `string \| object` | -        | -                    | Controls which tool is called. `none`: no tool, `auto`: model decides, `required`: must call a tool.                                            |
| `reasoning`            | `object`           | -        | -                    | Configuration for reasoning effort. Controls how much reasoning the model performs before generating a response.                                |
| `previous_response_id` | `string`           | -        | -                    | The ID of a previous response to use as context for multi-turn conversations.                                                                   |
| `truncation`           | `string`           | -        | `auto` \| `disabled` | Truncation strategy. `auto`: automatically truncates input to fit context window; `disabled`: returns an error if input exceeds context window. |