Create a Messages response

curl --request POST \
  --url https://inference.magica.com/v1/messages \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "<string>",
  "max_tokens": 123,
  "messages": [
    {}
  ],
  "system": {},
  "stream": true,
  "tools": [
    {}
  ],
  "tool_choice": {}
}
'

import requests

url = "https://inference.magica.com/v1/messages"

payload = {
    "model": "<string>",
    "max_tokens": 123,
    "messages": [{}],
    "system": {},
    "stream": True,
    "tools": [{}],
    "tool_choice": {}
}
headers = {"Content-Type": "application/json"}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    model: '<string>',
    max_tokens: 123,
    messages: [{}],
    system: {},
    stream: true,
    tools: [{}],
    tool_choice: {}
  })
};

fetch('https://inference.magica.com/v1/messages', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://inference.magica.com/v1/messages",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'model' => '<string>',
    'max_tokens' => 123,
    'messages' => [
        [
                
        ]
    ],
    'system' => [
        
    ],
    'stream' => true,
    'tools' => [
        [
                
        ]
    ],
    'tool_choice' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://inference.magica.com/v1/messages"

	payload := strings.NewReader("{\n  \"model\": \"<string>\",\n  \"max_tokens\": 123,\n  \"messages\": [\n    {}\n  ],\n  \"system\": {},\n  \"stream\": true,\n  \"tools\": [\n    {}\n  ],\n  \"tool_choice\": {}\n}")

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

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://inference.magica.com/v1/messages")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"<string>\",\n  \"max_tokens\": 123,\n  \"messages\": [\n    {}\n  ],\n  \"system\": {},\n  \"stream\": true,\n  \"tools\": [\n    {}\n  ],\n  \"tool_choice\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://inference.magica.com/v1/messages")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model\": \"<string>\",\n  \"max_tokens\": 123,\n  \"messages\": [\n    {}\n  ],\n  \"system\": {},\n  \"stream\": true,\n  \"tools\": [\n    {}\n  ],\n  \"tool_choice\": {}\n}"

response = http.request(request)
puts response.read_body

POST

messages

Create a Messages response

curl --request POST \
  --url https://inference.magica.com/v1/messages \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "<string>",
  "max_tokens": 123,
  "messages": [
    {}
  ],
  "system": {},
  "stream": true,
  "tools": [
    {}
  ],
  "tool_choice": {}
}
'

import requests

url = "https://inference.magica.com/v1/messages"

payload = {
    "model": "<string>",
    "max_tokens": 123,
    "messages": [{}],
    "system": {},
    "stream": True,
    "tools": [{}],
    "tool_choice": {}
}
headers = {"Content-Type": "application/json"}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    model: '<string>',
    max_tokens: 123,
    messages: [{}],
    system: {},
    stream: true,
    tools: [{}],
    tool_choice: {}
  })
};

fetch('https://inference.magica.com/v1/messages', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://inference.magica.com/v1/messages",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'model' => '<string>',
    'max_tokens' => 123,
    'messages' => [
        [
                
        ]
    ],
    'system' => [
        
    ],
    'stream' => true,
    'tools' => [
        [
                
        ]
    ],
    'tool_choice' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://inference.magica.com/v1/messages"

	payload := strings.NewReader("{\n  \"model\": \"<string>\",\n  \"max_tokens\": 123,\n  \"messages\": [\n    {}\n  ],\n  \"system\": {},\n  \"stream\": true,\n  \"tools\": [\n    {}\n  ],\n  \"tool_choice\": {}\n}")

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

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://inference.magica.com/v1/messages")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"<string>\",\n  \"max_tokens\": 123,\n  \"messages\": [\n    {}\n  ],\n  \"system\": {},\n  \"stream\": true,\n  \"tools\": [\n    {}\n  ],\n  \"tool_choice\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://inference.magica.com/v1/messages")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model\": \"<string>\",\n  \"max_tokens\": 123,\n  \"messages\": [\n    {}\n  ],\n  \"system\": {},\n  \"stream\": true,\n  \"tools\": [\n    {}\n  ],\n  \"tool_choice\": {}\n}"

response = http.request(request)
puts response.read_body

Creates a Messages-style response from user and assistant turns. Content can be a string or an array of text, image, document, and tool blocks.

Authorization

Send either header:

string

Magica API key, such as gx_your_api_key.

string

Bearer form: Bearer gx_your_api_key.

Body

string

required

Model ID from the language-model catalog.

integer

Optional output-token ceiling. When omitted, Magica applies the selected model’s bounded gateway default when that model declares one.

array

required

User and assistant turns. Send the complete history needed for this answer. Models using the native Messages format also accept system turns after a user turn. Each system turn must contain nonempty text, either as a string or an array of text blocks. These turns retain their position in the conversation and cannot be translated to another model’s wire format.

string | array

Initial system instructions as text or content blocks. Use this field, not an initial system turn in messages, for instructions before the first user turn.

boolean

default:"false"

Omit or set false for one complete JSON object. Set true for named SSE events.

array

Tool definitions with name, optional description, and input_schema.

object

Controls automatic, required, disabled, or named tool use.

Direct JSON request

cURL
Node.js
Python

curl https://inference.magica.com/v1/messages \
  -H "x-api-key: $MAGICA_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "openai/gpt-5.4-mini",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Reply with exactly: hello"}]
  }'

const response = await fetch("https://inference.magica.com/v1/messages", {
  method: "POST",
  headers: {
    "x-api-key": process.env.MAGICA_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "openai/gpt-5.4-mini",
    max_tokens: 1024,
    messages: [{ role: "user", content: "Reply with exactly: hello" }],
  }),
});
if (!response.ok) throw new Error(await response.text());
const message = await response.json();
console.log(message.content[0].text);

import os, requests

response = requests.post(
    "https://inference.magica.com/v1/messages",
    headers={"x-api-key": os.environ["MAGICA_API_KEY"]},
    json={
        "model": "openai/gpt-5.4-mini",
        "max_tokens": 1024,
        "messages": [{"role": "user", "content": "Reply with exactly: hello"}],
    },
    timeout=120,
)
response.raise_for_status()
print(response.json()["content"][0]["text"])

Direct JSON response

{
  "id": "msg_123",
  "type": "message",
  "role": "assistant",
  "model": "openai/gpt-5.4-mini",
  "content": [{ "type": "text", "text": "hello" }],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": { "input_tokens": 20, "output_tokens": 1 }
}

Stream the response

Add "stream": true. A text response normally starts with message_start, emits content block events, reports its final stop reason and usage in message_delta, and ends with message_stop.

event: message_start
data: {"type":"message_start","message":{"id":"msg_123","type":"message","role":"assistant","content":[],"model":"openai/gpt-5.4-mini","usage":{"input_tokens":20,"output_tokens":0}}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"hello"}}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"output_tokens":1}}

event: message_stop
data: {"type":"message_stop"}

This stream does not use a [DONE] sentinel.

Images and PDFs

Image: {"type":"image","source":{"type":"url","url":"https://..."}}
PDF: {"type":"document","source":{"type":"url","url":"https://..."}}

Base64 image data and base64 PDF data are also accepted. Prefer HTTPS URLs for large attachments.

Errors

Errors use the Messages-style error object.

Status	Reason
`400`	Invalid request or unsupported content
`401`	Missing or invalid API key
`402`	Insufficient credits
`403`	Access token lacks the `llm:inference` scope
`404`	Model ID was not found
`413`	Request exceeds the direct transport or selected model limit
`429`	Rate limit reached; retry using `Retry-After`
`502`	Model service could not complete the request
`503`	Credit authorization is temporarily unavailable
`529`	Model service is temporarily overloaded

Overview

Models

Standalone Model Runs

LLM Gateway

Credits

Generated Media

Create a Messages response

Authorization

Body

Direct JSON request

Direct JSON response

Stream the response

Images and PDFs

Errors