API Endpoints

Comprehensive reference for all Martian Gateway API endpoints, including required and optional parameters.

Chat Completions

The /v1/chat/completions endpoint supports most of the parameters available in the OpenAI Chat Completions API.

Endpoint

POST https://api.withmartian.com/v1/chat/completions

Required Parameters

Name
model
Type
string
Description
Specify creator/model-name. For example: openai/gpt-5.4-nano
See Available Models for the complete list.
Name
messages
Type
array
Description
A list of messages comprising the conversation so far.
- Name
  role
  Type
  string
  Description
  The role of the message sender (e.g., user, assistant, system).
- Name
  content
  Type
  string
  Description
  The content of the message.

Optional Parameters

Name
frequency_penalty
Type
number
Description
Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far.
Name
logit_bias
Type
object
Description
Modify the likelihood of specified tokens appearing in the completion.
Name
max_completion_tokens
Type
integer
Description
The maximum number of tokens to generate in the chat completion.
Name
metadata
Type
object
Description
Object containing additional information about the request for logging, analytics, or monitoring purposes.
Name
martian_metadata
Type
object
Description
Martian-specific key-value data for providing request tracking, application-based metadata, feedback signals, and other information to Martian. Each value may be any JSON type. Martian does not send this metadata to the upstream model provider. See an example.
Name
parallel_tool_calls
Type
boolean
Description
Whether to enable parallel function calling during tool use.
Name
presence_penalty
Type
number
Description
Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far.
Name
reasoning_effort
Type
string
Description
Amount of reasoning effort to use. Only available on OpenAI reasoning models (e.g., o1, o3-mini).
Values: low, medium, high
Name
response_format
Type
object
Description
An object specifying the format that the model must output. Setting to { "type": "json_object" } enables JSON mode.
Name
safety_identifier
Type
string
Description
Unique identifier for content safety and moderation tracking.
Name
stream
Type
boolean
Description
If set, partial message deltas will be sent as server-sent events.
Name
temperature
Type
number
Description
What sampling temperature to use, between 0 and 2. Higher values make output more random, lower values more deterministic.
Name
tool_choice
Type
string | object
Description
Controls which (if any) function is called by the model. Options: none, auto, required, or specify a function.
Name
tools
Type
array
Description
A list of tools the model may call. Currently, only functions are supported as a tool.
Name
top_p
Type
number
Description
An alternative to sampling with temperature, called nucleus sampling. The model considers the results of the tokens with top_p probability mass.
Name
verbosity
Type
string
Description
Control the verbosity level of the response.

Martian Gateway does not support the n parameter for generating multiple responses from a single prompt. If you need multiple responses, make separate API calls.

Example Request

curl https://api.withmartian.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MARTIAN_API_KEY" \
  -d '{
    "model": "openai/gpt-5.4-nano",
    "messages": [
      {
        "role": "user",
        "content": "Explain quantum computing in simple terms."
      }
    ],
    "temperature": 0.7,
    "max_completion_tokens": 500,
    "martian_metadata": {
      "organization_id": "org-123",
      "environment": "production",
      "request_id": "request-123"
    }
  }'

Responses

The /v1/responses endpoint supports most of the parameters available in the OpenAI Responses API.

Endpoint

POST https://api.withmartian.com/v1/responses

Required Parameters

Name
model
Type
string
Description
Specify creator/model-name. For example: openai/gpt-5.4-nano
See Available Models for the complete list.
Name
input
Type
string | array
Description
Text, images, files, or other input items used to generate a response.

Martian Parameters

Name
martian_metadata
Type
object
Description
Martian-specific key-value data for providing request tracking, application-based metadata, feedback signals, and other information to Martian. Each value may be any JSON type. Martian does not send this metadata to the upstream model provider. See an example.

Example Request

curl https://api.withmartian.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MARTIAN_API_KEY" \
  -d '{
    "model": "openai/gpt-5.4-nano",
    "input": "Explain quantum computing in simple terms.",
    "martian_metadata": {
      "organization_id": "org-123",
      "environment": "production",
      "request_id": "request-123"
    }
  }'

Messages

The /v1/messages endpoint supports most of the parameters available in the Anthropic Messages API.

Endpoint

POST https://api.withmartian.com/v1/messages

Required Parameters

Name
model
Type
string
Description
Specify creator/model-name. For example: anthropic/claude-sonnet-4-6
See Available Models for the complete list.
Name
messages
Type
array
Description
Input messages comprising the conversation so far.
- Name
  role
  Type
  string
  Description
  The role of the message sender (e.g., user or assistant).
- Name
  content
  Type
  string | array
  Description
  The content of the message. Can be a string or an array of content blocks.
Name
max_tokens
Type
integer
Description
The maximum number of tokens to generate before stopping.

Optional Parameters

Name
container
Type
object
Description
Configuration for the container in which the model operates.
Name
context_management
Type
object
Description
Settings for how the model manages conversation context.
Name
metadata
Type
object
Description
An object describing metadata about the request for logging, analytics, or monitoring purposes.
Name
martian_metadata
Type
object
Description
Martian-specific key-value data for providing request tracking, application-based metadata, feedback signals, and other information to Martian. Each value may be any JSON type. Martian does not send this metadata to the upstream model provider. See an example.
Name
stop_sequences
Type
array
Description
Custom text sequences that will cause the model to stop generating.
Name
stream
Type
boolean
Description
Whether to incrementally stream the response using server-sent events.
Name
system
Type
string | array
Description
System prompt to guide the model's behavior.
Name
temperature
Type
number
Description
Amount of randomness injected into the response. Ranges from 0.0 to 1.0.
Name
tool_choice
Type
object
Description
How the model should use the provided tools.
Name
tools
Type
array
Description
Definitions of tools that the model may use.
Name
top_k
Type
integer
Description
Only sample from the top K options for each subsequent token.
Name
top_p
Type
number
Description
Use nucleus sampling with the specified probability mass.

Example Request

curl https://api.withmartian.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MARTIAN_API_KEY" \
  -d '{
    "model": "anthropic/claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "Explain the importance of biodiversity."
      }
    ],
    "martian_metadata": {
      "organization_id": "org-123",
      "environment": "production",
      "request_id": "request-123"
    }
  }'

List Models

The /v1/models endpoint returns a JSON object containing all models currently supported by the Martian Gateway.

Endpoint

GET https://api.withmartian.com/v1/models

Response

Returns a JSON object with a data array containing all available models with their pricing, timestamps, and metadata.

Example Request

curl https://api.withmartian.com/v1/models \
  -H "Authorization: Bearer $MARTIAN_API_KEY"

Example Response

{
  "data": [
    {
      "id": "openai/gpt-4.1-nano",
      "pricing": {
        "prompt": "0.0000001",
        "completion": "0.0000004",
        "image": "0",
        "request": "0",
        "web_search": "0.01",
        "internal_reasoning": "0"
      },
      "added_at": "2024-05-13T00:00:00+00:00",
      "updated_at": "2025-01-15T10:30:00+00:00",
      "reliability_tier": 1,
      "max_completion_tokens": 32768
    },
    {
      "id": "anthropic/claude-sonnet-4-20250514",
      "pricing": {
        "prompt": "0.000003",
        "completion": "0.000015",
        "image": "0.0048",
        "request": "0",
        "web_search": "0",
        "internal_reasoning": "0"
      },
      "added_at": "2025-05-14T00:00:00+00:00",
      "updated_at": "2025-05-14T00:00:00+00:00",
      "reliability_tier": 1,
      "max_completion_tokens": 64000
    },
    {
      "id": "google/gemini-2.5-flash",
      "pricing": {
        "prompt": "0.0000003",
        "completion": "0.0000025",
        "image": "0",
        "request": "0",
        "web_search": "0",
        "internal_reasoning": "0"
      },
      "added_at": "2024-12-01T00:00:00+00:00",
      "updated_at": "2025-02-20T14:22:00+00:00",
      "reliability_tier": 2,
      "max_completion_tokens": 65536
    },
    // ... more models
  ]
}

Pricing values are strings representing the cost in USD per token (not per million). Multiply by 1,000,000 to get the cost per million tokens. A value of "0" indicates the feature is free or not available for that model.

For a complete list of available models with pricing information, see the Available Models page.

API Endpoints

Chat Completions

Endpoint

Required Parameters

Optional Parameters

Example Request

Responses

Endpoint

Required Parameters

Martian Parameters

Example Request

Messages

Endpoint

Required Parameters

Optional Parameters

Example Request

List Models

Endpoint

Parameters

Response

Example Request

Example Response

Next Steps

Explore Advanced Features

Learn About Error Handling