curl --request POST \
  --url https://direct.evolink.ai/v1/responses \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "grok-4.5",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Describe this image in one sentence."
        },
        {
          "type": "input_image",
          "image_url": "https://example.com/photo.jpg"
        }
      ]
    }
  ],
  "max_output_tokens": 256
}
'

{
  "id": "55d44212-8d5e-90cc-975f-36d341ce21f5",
  "object": "response",
  "status": "completed",
  "model": "grok-4.7",
  "created_at": 1786538000,
  "output": [
    {
      "id": "<string>",
      "type": "web_search_call",
      "status": "completed",
      "content": [
        {}
      ],
      "encrypted_content": "<string>"
    }
  ],
  "usage": {
    "input_tokens": 10329,
    "output_tokens": 299,
    "total_tokens": 10628,
    "input_tokens_details": {
      "cached_tokens": 6016
    },
    "output_tokens_details": {
      "reasoning_tokens": 128
    },
    "num_server_side_tools_used": 2,
    "server_side_tool_usage_details": {
      "web_search_calls": 2,
      "x_search_calls": 0,
      "code_interpreter_calls": 0,
      "document_search_calls": 0,
      "file_search_calls": 0,
      "mcp_calls": 0,
      "x_posts_fetched": 0,
      "x_users_fetched": 0
    }
  }
}

{
  "error": {
    "code": 400,
    "message": "Invalid request parameters",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": 401,
    "message": "Invalid or expired token",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": 402,
    "message": "Insufficient quota",
    "type": "insufficient_quota_error",
    "fallback_suggestion": "https://evolink.ai/dashboard/credits"
  }
}

{
  "error": {
    "code": 429,
    "message": "Rate limit exceeded",
    "type": "rate_limit_error",
    "fallback_suggestion": "retry after 60 seconds"
  }
}

{
  "error": {
    "code": 500,
    "message": "Internal server error",
    "type": "internal_server_error",
    "fallback_suggestion": "try again later"
  }
}

{
  "error": {
    "code": 503,
    "message": "Service temporarily unavailable",
    "type": "service_unavailable_error",
    "fallback_suggestion": "retry after 30 seconds"
  }
}

Responses API

Grok All-Model API - Responses Reference

OpenAI-compatible Responses endpoint for xAI Grok text models; pick the model via the model parameter (see the table on the model parameter for all values)
500K-token context window; prompts of 200K tokens or more are billed at 2x for all token types
Prompt caching is automatic: cached prompt tokens are billed at the lower cached-input rate
Synchronous and streaming (SSE) modes
xAI server-side tools run on xAI infrastructure: web_search, x_search, code_execution, attachment_search, and collections_search. X Search is billed by posts and user profiles fetched; other tools are billed per successful call.
Regular function tools (client-side function calling) are also supported and carry no per-call fee
Under xAI’s official API contract, grok-4.7 returns reasoning items containing encrypted_content by default; the fields actually returned depend on the current route.

POST

responses

curl --request POST \
  --url https://direct.evolink.ai/v1/responses \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "grok-4.5",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Describe this image in one sentence."
        },
        {
          "type": "input_image",
          "image_url": "https://example.com/photo.jpg"
        }
      ]
    }
  ],
  "max_output_tokens": 256
}
'

{
  "id": "55d44212-8d5e-90cc-975f-36d341ce21f5",
  "object": "response",
  "status": "completed",
  "model": "grok-4.7",
  "created_at": 1786538000,
  "output": [
    {
      "id": "<string>",
      "type": "web_search_call",
      "status": "completed",
      "content": [
        {}
      ],
      "encrypted_content": "<string>"
    }
  ],
  "usage": {
    "input_tokens": 10329,
    "output_tokens": 299,
    "total_tokens": 10628,
    "input_tokens_details": {
      "cached_tokens": 6016
    },
    "output_tokens_details": {
      "reasoning_tokens": 128
    },
    "num_server_side_tools_used": 2,
    "server_side_tool_usage_details": {
      "web_search_calls": 2,
      "x_search_calls": 0,
      "code_interpreter_calls": 0,
      "document_search_calls": 0,
      "file_search_calls": 0,
      "mcp_calls": 0,
      "x_posts_fetched": 0,
      "x_users_fetched": 0
    }
  }
}

{
  "error": {
    "code": 400,
    "message": "Invalid request parameters",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": 401,
    "message": "Invalid or expired token",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": 402,
    "message": "Insufficient quota",
    "type": "insufficient_quota_error",
    "fallback_suggestion": "https://evolink.ai/dashboard/credits"
  }
}

{
  "error": {
    "code": 429,
    "message": "Rate limit exceeded",
    "type": "rate_limit_error",
    "fallback_suggestion": "retry after 60 seconds"
  }
}

{
  "error": {
    "code": 500,
    "message": "Internal server error",
    "type": "internal_server_error",
    "fallback_suggestion": "try again later"
  }
}

{
  "error": {
    "code": 503,
    "message": "Service temporarily unavailable",
    "type": "service_unavailable_error",
    "fallback_suggestion": "retry after 30 seconds"
  }
}

BaseURL: The default BaseURL is https://direct.evolink.ai, which has better support for text models and long-lived connections. https://api.evolink.ai is the primary endpoint for multimodal services and serves as a fallback address for text models.

Server-side tools are charged separately from tokens: web search / code execution cost USD 0.005 per successful call, attachment search USD 0.01 per call, and collections search USD 0.0025 per call. X Search costs USD 0.005 per post fetched and USD 0.01 per user profile fetched. Tool fees are not affected by the long-context multiplier.

Using Grok 4.7

Set model to grok-4.7. The context window is 500,000 tokens, and the knowledge cutoff is May 2026. Set reasoning depth with reasoning.effort: low, medium, high (default), or xhigh. Reasoning cannot be disabled. Under xAI’s encrypted reasoning contract, 4.7 returns reasoning items with encrypted_content in output by default, without an explicit include. When managing conversation history yourself, pass the complete reasoning items back unchanged in the next input, together with other historical output. Do not decode or alter the ciphertext. Check the fields present in the actual response.

X Search billing

The new X Search billing rules apply to Grok 4.5, 4.6, and 4.7. A search can fetch multiple posts and user profiles; parent and quoted posts also count. For example, fetching 30 posts and 3 user profiles costs 30 × USD 0.005 + 3 × USD 0.01 = USD 0.18 in tool fees, plus token fees. Check usage.server_side_tool_usage_details.x_posts_fetched and x_users_fetched for fetched-item counts. Responses missing both fields fall back to billing per successful call. x_search_calls is the call count; max_tool_calls is a call-count control value whose actual enforcement depends on the route. Neither is a fetched-item or spending cap. x_users_fetched is a usage field and requires no additional tool declaration.

image_generation is currently unavailable on Grok 4.5, 4.6, and 4.7: the declaration is accepted for compatibility, but the tool is removed before the request reaches the model. Unrecognized tools[].type values return 400.

Authorizations

Authorization

string

header

required

##All APIs require Bearer Token authentication##

Get API Key:

Visit API Key Management Page to get your API Key

Add to request header:

Authorization: Bearer YOUR_API_KEY

Body

application/json

model

enum<string>

required

Model to call:

Model ID	Positioning
`grok-4.7`	xAI reasoning and tool-use model; 500K-token context window; supports `xhigh`; knowledge cutoff: 2026-05
`grok-4.6`	xAI reasoning + tool-use model, 500K context window; adds the `xhigh` reasoning level; knowledge cutoff 2026-02-01
`grok-4.5`	xAI reasoning + tool-use model, 500K context window; reasoning levels up to `high` (`xhigh` is accepted but downgraded to `high`)

Available options:

grok-4.7,

grok-4.6,

grok-4.5

Example:

"grok-4.7"

input

required

Input for the model: a plain string, or an array of OpenAI Responses input items (e.g. {"role":"user","content":[...]}). Content blocks support input_text and input_image (image_url is a public URL or base64 data URL; jpg / png, up to 20MiB each) for image understanding.

Example:

"Search the web for the latest SpaceX launch and summarize it in one sentence."

stream

boolean

default:false

Whether to stream the response (SSE). Defaults to false. Read status and usage from the terminal response: completed means generation finished; output limits and similar conditions can produce incomplete. Do not wait exclusively for a response.completed event.

Example:

false

max_output_tokens

integer

Maximum number of tokens to generate (reasoning tokens included).

Example:

2048

reasoning

object

Reasoning depth is set with an object: {"effort": "low" | "medium" | "high" | "xhigh"}. The default is high; reasoning cannot be disabled. grok-4.7 and grok-4.6 support xhigh; grok-4.5 treats it as high. Reasoning tokens are billed as output tokens and reported in usage.output_tokens_details.reasoning_tokens.

Show child attributes

tools

object[]

Tool declarations. Server-side tool fees are charged in addition to tokens and are not affected by the long-context multiplier:

Tool type	Capability	Billing unit and price
`web_search`	Search and browse the web	USD 0.005 per successful call
`x_search`	Search X posts, accounts, and topics	USD 0.005 per post fetched + USD 0.01 per user profile fetched
`code_execution`	Run Python in a sandbox (alias: `code_interpreter`)	USD 0.005 per successful call
`attachment_search`	Search conversation attachments (may activate automatically for file inputs)	USD 0.01 per successful call
`collections_search`	Search uploaded document collections (alias: `file_search`)	USD 0.0025 per successful call

The X Search billing basis applies to grok-4.5, grok-4.6, and grok-4.7. A call can return multiple posts; parent and quoted posts returned by searches or thread fetches also count. See usage.server_side_tool_usage_details for actual usage. If both fetched-item count fields are absent, billing falls back to successful calls for compatibility.

Regular function tools are also supported (client-side function calls with no server-side tool-call fee).

Show child attributes

Example:

[{ "type": "web_search" }]

tool_choice

Controls tool selection: "auto" (default) / "none" / "required", or an object pinning a specific tool, e.g. {"type": "web_search"}.

Available options:

auto,

none,

required

prompt_cache_key

string

Optional cache routing key. Use a stable value for requests in the same conversation or sharing the same prompt prefix to improve the chance of a cache hit. Hits are not guaranteed, and cache billing rules do not change. Check cached_tokens in usage for actual cache hits.

Example:

"grok-session-001"

include

string[]

Additional response fields to request. For example, grok-4.6 can request encrypted reasoning with ["reasoning.encrypted_content"]. Under xAI's API contract, grok-4.7 returns it by default without an explicit include.

Example:

["reasoning.encrypted_content"]

max_tool_calls

integer

Tool-call count control value. The gateway forwards this value and uses it to estimate the tool-fee reservation; whether a route strictly enforces the count must be verified from its actual behavior. This value does not limit X posts or user profiles fetched and is not a spending cap.

Example:

1

Response

A response was returned; also check status: completed for finished generation, incomplete for cases such as output limits, and failed for failure. With stream=true, the response is an SSE stream; read status and usage from the terminal response.

string

Unique identifier for the response

Example:

"55d44212-8d5e-90cc-975f-36d341ce21f5"

object

enum<string>

Response type

Available options:

response

Example:

"response"

status

enum<string>

Response status

Available options:

completed,

incomplete,

failed

Example:

"completed"

model

string

Model name actually used

Example:

"grok-4.7"

created_at

integer

Creation timestamp

Example:

1786538000

output

object[]

Output items in generation order: reasoning items (which may contain encrypted reasoning), server-side tool-call items, function_call items, and message items containing output_text. Tool usage is determined by usage; one x_search call can incur fees for multiple posts and user profiles.

Show child attributes

usage

object

Token and tool usage statistics. Prompts of 200K tokens or more are billed at 2x for all token types; tool fees are unaffected by the multiplier.

Show child attributes

Image Series

Video Series

Audio Series

Text Series

Account Management

Task Management

File Management

Grok All-Model API - Responses Reference

Using Grok 4.7

X Search billing

Authorizations

Body

Response

​Using Grok 4.7

​X Search billing

Authorizations

Body

Response

Using Grok 4.7

X Search billing