### Worked example usage response

Source: https://grokified.com/docs/pricing

Example usage response for a grok-4.7 call with 50,000 input and 10,000 output tokens. Shows the standard price of $0.16, the charged amount of $0.08 after the 50% discount, and the remaining balance.

```json
{
  "usage": {
    "cost_usd": 0.16,
    "grokified": {
      "list_usd": 0.16,
      "charged_usd": 0.08,
      "discount_usd": 0.08,
      "balance_usd": 3.92
    }
  }
}
```

--------------------------------

### Start a deferred completion and poll for the result (cURL + shell)

Source: https://grokified.com/docs/deferred-completions

Sends a POST /chat/completions request with "deferred": true and a reasoning_effort of "xhigh", extracts the request_id from the JSON response, then polls GET /chat/deferred-completion/{request_id} every 10 seconds up to 60 times. A 200 response contains the full completion body; a 202 with an empty body means it is still working. The result is printed with jq and the loop exits on success.

```shell
RESPONSE=$(curl -s https://api.grokified.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GROKIFIED_API_KEY" \
  -d '{
    "model": "grok-4.7",
    "reasoning_effort": "xhigh",
    "deferred": true,
    "messages": [{"role": "user", "content": "Prove there are infinitely many primes, step by step."}]
  }')
REQUEST_ID=$(echo "$RESPONSE" | jq -r '.request_id')
echo "Request ID: $REQUEST_ID"

for i in $(seq 1 60); do
  RESULT=$(curl -s -w "\n%{http_code}" https://api.grokified.com/v1/chat/deferred-completion/$REQUEST_ID \
    -H "Authorization: Bearer $GROKIFIED_API_KEY")
  CODE=$(echo "$RESULT" | tail -n1)
  BODY=$(echo "$RESULT" | sed '$d')
  if [ "$CODE" = "200" ]; then
    echo "$BODY" | jq -r '.choices[0].message.content'
    break
  fi
  sleep 10
done
```

--------------------------------

### GET /v1/video-generation-models

Source: https://grokified.com/docs/models

Returns a typed catalog of video generation models. Video models do not have per-model pricing; billing is per second of rendered output.

```APIDOC
## GET /v1/video-generation-models

### Description
Returns a typed catalog scoped to video models. Video models carry no per-model price field; billing is per second of rendered output regardless of model.

### Method
GET

### Endpoint
/v1/video-generation-models

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.

### Request Example
```
curl https://api.grokified.com/v1/video-generation-models \
  -H "Authorization: Bearer $GROKIFIED_API_KEY"
```

### Response
#### Success Response (200)
- **model** (string) - The model identifier.

#### Response Example
```
{
  "model": "grok-imagine-video"
}
```
```

--------------------------------

### GET /v1/image-generation-models

Source: https://grokified.com/docs/models

Returns a typed catalog of image generation models, with fields like `max_prompt_length` and `image_price` (scaled differently from token prices).

```APIDOC
## GET /v1/image-generation-models

### Description
Returns a typed catalog scoped to image models. Includes `max_prompt_length` and `image_price` fields instead of token pricing; `image_price` is scaled as 1/100,000,000ths of a USD cent.

### Method
GET

### Endpoint
/v1/image-generation-models

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.

### Request Example
```
curl https://api.grokified.com/v1/image-generation-models \
  -H "Authorization: Bearer $GROKIFIED_API_KEY"
```

### Response
#### Success Response (200)
- **model** (string) - The model identifier.
- **max_prompt_length** (integer) - Maximum prompt length.
- **image_price** (integer) - Price per image in 1/100,000,000ths of a USD cent.

#### Response Example
```
{
  "model": "grok-imagine-image-2.0",
  "max_prompt_length": 1000,
  "image_price": 200000000
}
```
```

--------------------------------

### Fetch file content with cURL (GET /files/{file_id}/content)

Source: https://grokified.com/docs/files-collections

Streams raw file bytes. Add ?format=text to get extracted plain text instead of the original file.

```bash
curl https://api.grokified.com/v1/files/file_a128090d-f0c9-4873-bd84-e499777e7417/content \
  -H "Authorization: Bearer $GROKIFIED_API_KEY" \
  --output handbook.pdf
```

--------------------------------

### List language models with cURL

Source: https://grokified.com/docs/models

Fetches the typed catalog from GET /v1/language-models. Returns more fields than GET /v1/models, including input/output modalities, a system fingerprint, cached-token pricing, and long-context rates. Covers chat and image-understanding models callable through /chat/completions or /responses.

```cURL
curl https://api.grokified.com/v1/language-models \
  -H "Authorization: Bearer $GROKIFIED_API_KEY"
```

--------------------------------

### Combine Tools in One Request

Source: https://grokified.com/docs/agent-tools

Shows how to make a single request that uses multiple tools, such as web_search and image_generation, and how to get the total tool-call count.

```APIDOC
## POST /v1/responses

### Description
Create a response that can use multiple tools in a single turn, allowing the model to chain tool calls together.

### Method
POST

### Endpoint
https://api.grokified.com/v1/responses

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **model** (string) - Required - The model identifier to use, e.g., "grok-4.7"
- **input** (string) - Required - The user input or prompt
- **tools** (array) - Required - List of tool objects, each with a type field (e.g., "web_search", "image_generation")

### Request Example
```json
{
  "model": "grok-4.7",
  "input": "Find out which team won the most recent FIFA World Cup, then generate a celebratory poster for that team, in a vintage travel-poster style.",
  "tools": [
    { "type": "web_search" },
    { "type": "image_generation" }
  ]
}
```

### Response
#### Success Response (200)
- **usage.num_server_side_tools_used** (integer) - Total number of tool calls made across all tools in the request

#### Response Example
```json
{
  "usage": {
    "num_server_side_tools_used": 2
  }
}
```
```

--------------------------------

### Python loop accumulating savings with already_billed check

Source: https://grokified.com/docs/usage-tracking

Python example using the OpenAI client to loop through prompts, extract the grokified block, and accumulate discount_usd only when already_billed is not set. Prevents double-counting discounts on replayed requests.

```python
import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["GROKIFIED_API_KEY"], base_url="https://api.grokified.com/v1")
prompts = ["Summarize this ticket.", "Classify this review.", "Draft a reply."]
total_saved = 0.0

for prompt in prompts:
    resp = client.chat.completions.create(
        model="grok-4.7",
        messages=[{"role": "user", "content": prompt}],
    )
    g = resp.model_dump()["usage"]["grokified"]
    # A replayed request is already_billed — don't count its discount twice
    if not g.get("already_billed"):
        total_saved += g["discount_usd"]

print(f"Saved ${total_saved:.4f} across {len(prompts)} calls")
```

--------------------------------

### List video-generation models with cURL

Source: https://grokified.com/docs/models

Fetches the video model catalog from GET /v1/video-generation-models. Video models carry no per-model price field here; video bills per second of rendered output regardless of which model rendered it.

```cURL
curl https://api.grokified.com/v1/video-generation-models \
  -H "Authorization: Bearer $GROKIFIED_API_KEY"
```

--------------------------------

### GET /files

Source: https://grokified.com/docs/files-collections

List all files uploaded by the authenticated user. Supports pagination, sorting, and filtering.

```APIDOC
## GET /files

### Description
List all files you've uploaded, paginated. Sort with `order` and `sort_by`, or narrow results with an AIP-160 `filter` expression.

### Method
GET

### Endpoint
https://api.grokified.com/v1/files

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Number of files to return.
- **order** (string) - Optional - Sort order, e.g., "desc".
- **sort_by** (string) - Optional - Field to sort by.
- **filter** (string) - Optional - AIP-160 filter expression, e.g., `content_type = "pdf"`.

### Request Example
```
curl "https://api.grokified.com/v1/files?limit=20&order=desc" \
  -H "Authorization: Bearer $GROKIFIED_API_KEY"
```

### Response
#### Success Response (200)
- **files** (array) - List of file objects.

#### Response Example
```
{
  "files": [
    {
      "file_id": "file_a128090d-f0c9-4873-bd84-e499777e7417",
      "content_type": "pdf"
    }
  ]
}
```
```

--------------------------------

### List voices with cURL (GET /tts/voices)

Source: https://grokified.com/docs/audio

Lists every built-in voice id you can pass as `voice_id`. A generated video can also use a preset voice through `reference_audios` on `grok-imagine-video-1.5`.

```bash
curl https://api.grokified.com/v1/tts/voices \
  -H "Authorization: Bearer $GROKIFIED_API_KEY"
```

--------------------------------

### List files with cURL (GET /files)

Source: https://grokified.com/docs/files-collections

Lists all uploaded files, paginated. Supports order, sort_by, and AIP-160 filter expressions like content_type = "pdf".

```bash
curl "https://api.grokified.com/v1/files?limit=20&order=desc" \
  -H "Authorization: Bearer $GROKIFIED_API_KEY"
```

--------------------------------

### POST /chat/completions (deferred)

Source: https://grokified.com/docs/deferred-completions

Starts a deferred chat completion. Instead of returning the completion directly, it returns a request_id that can be used later to retrieve the result.

```APIDOC
## POST /chat/completions

### Description
Starts a deferred chat completion. Add `"deferred": true` to a normal chat completion request. The response contains a `request_id` instead of the completion.

### Method
POST

### Endpoint
`https://api.grokified.com/v1/chat/completions`

### Parameters
#### Request Body
- **model** (string) - Required - The model to use, e.g., `grok-4.7`.
- **reasoning_effort** (string) - Optional - The reasoning effort level, e.g., `xhigh`.
- **deferred** (boolean) - Required - Set to `true` to enable deferred completion.
- **messages** (array) - Required - The conversation messages, each with `role` and `content`.

### Request Example
```json
{
  "model": "grok-4.7",
  "reasoning_effort": "xhigh",
  "deferred": true,
  "messages": [
    {
      "role": "user",
      "content": "Prove there are infinitely many primes, step by step."
    }
  ]
}
```

### Response
#### Success Response (200)
- **request_id** (string) - The ID to use for polling the result.

#### Response Example
```json
{
  "request_id": "..."
}
```
```

--------------------------------

### List image-generation models with cURL

Source: https://grokified.com/docs/models

Fetches the image model catalog from GET /v1/image-generation-models. Same shape as the language-models endpoint but scoped to image models. Note that image_price is scaled differently: 200000000 is $0.02 per image, not $2.

```cURL
curl https://api.grokified.com/v1/image-generation-models \
  -H "Authorization: Bearer $GROKIFIED_API_KEY"
```

--------------------------------

### List models with cURL

Source: https://grokified.com/docs/models

Fetches the current model catalog from GET /v1/models. The response reports the model that actually answered, so retired names show the replacement. Token prices are integers in USD cents per 100 million tokens.

```cURL
curl https://api.grokified.com/v1/models \
  -H "Authorization: Bearer $GROKIFIED_API_KEY"
```

--------------------------------

### Create a collection and attach a file with cURL (POST /collections)

Source: https://grokified.com/docs/files-collections

Creates a named collection with a search index, then attaches a previously uploaded file. All collection management runs through POST /collections on your regular Grokified key.

```bash
curl https://api.grokified.com/v1/collections \
  -H "Authorization: Bearer $GROKIFIED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"collection_name": "product-docs"}'

# Attach a file you already uploaded through /files
curl -X POST https://api.grokified.com/v1/collections/$COLLECTION_ID/documents/$FILE_ID \
  -H "Authorization: Bearer $GROKIFIED_API_KEY"
```

--------------------------------

### Realtime voice in the browser (wss://api.grokified.com/v1/realtime)

Source: https://grokified.com/docs/audio

Connects to the realtime voice endpoint from a browser. Because browsers can't set custom headers on a WebSocket handshake, the `gk_live_` key is passed as the first entry of `Sec-WebSocket-Protocol`. For public apps, have your backend hand the browser a short-lived credential instead of embedding the key directly. Billing is per minute of connection, rounding the trailing partial minute up on close.

```javascript
// Browsers can't set a header, so the key goes in as a subprotocol.
// For a public app, have your backend hand the browser a short-lived
// credential instead of embedding gk_live_ directly.
const ws = new WebSocket("wss://api.grokified.com/v1/realtime", ["gk_live_YOUR_KEY"]);
ws.onopen = () => ws.send(JSON.stringify({
  type: "session.update",
  session: { voice: "eve", instructions: "You are a helpful assistant." },
}));
ws.onmessage = (event) => console.log(JSON.parse(event.data).type);
```

--------------------------------

### Retrieve a stored response with GET /responses/{id}

Source: https://grokified.com/docs/responses-api

Fetches a previously created response by its id using the GET /responses/{id} endpoint. The response has the same shape as the one returned by POST /responses when the response was created.

```bash
curl https://api.grokified.com/v1/responses/resp_01j9k2m4n6p8q0r2s4t6u8v0w2 \
  -H "Authorization: Bearer $GROKIFIED_API_KEY"
```

--------------------------------

### POST /v1/videos/generations (Reference to video)

Source: https://grokified.com/docs/video

Creates a video generation using reference images. The reference images are not locked as the first frame; instead, they are used to maintain consistency of a person, product, or clothing in a new scene. The prompt is required and can reference the images using tags like `<IMAGE_0>`, `<IMAGE_1>`, etc.

```APIDOC
## [POST] /v1/videos/generations

### Description
Creates a video generation using reference images. The reference images are not locked as the first frame; instead, they are used to maintain consistency of a person, product, or clothing in a new scene. The prompt is required and can reference the images using tags like `<IMAGE_0>`, `<IMAGE_1>`, etc.

### Method
POST

### Endpoint
/v1/videos/generations

### Parameters
#### Request Body
- **model** (string) - Required - The model identifier, e.g., "grok-imagine-video-1.5".
- **prompt** (string) - Required - A text description of the desired scene, referencing images with tags like `<IMAGE_0>`.
- **reference_images** (array) - Required - An array of up to 3 image objects, each containing a `url` field.
- **duration** (number) - Optional - The duration of the video in seconds.

### Request Example
```
curl https://api.grokified.com/v1/videos/generations \
  -H "Authorization: Bearer $GROKIFIED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-imagine-video-1.5", "prompt": "The person from <IMAGE_0> wearing the jacket from <IMAGE_1>, walking down a rainy city street at night", "reference_images": [{"url": "https://example.com/person.png"}, {"url": "https://example.com/jacket.png"}], "duration": 6}'
```

### Response
#### Success Response (200)
- **request_id** (string) - The identifier for the generation request, used for polling.

#### Response Example
(Not provided in source)

```

--------------------------------

### GET /tts/voices

Source: https://grokified.com/docs/audio

Lists all built-in voice IDs available for text-to-speech.

```APIDOC
## GET /tts/voices

### Description
Lists every built-in voice id that can be passed as `voice_id`.

### Method
GET

### Endpoint
https://api.grokified.com/v1/tts/voices

### Request Example
```
curl https://api.grokified.com/v1/tts/voices \
  -H "Authorization: Bearer $GROKIFIED_API_KEY"
```

### Response
Returns a list of voice IDs.
```

--------------------------------

### POST /v1/videos/generations (Reference audio)

Source: https://grokified.com/docs/video

Adds a voice to the video generation using reference audio. Up to 3 entries, each naming a preset voice from the text-to-speech roster. Works only on `grok-imagine-video-1.5`. An unknown voice id returns a 400 with the list of valid ones.

```APIDOC
## [POST] /v1/videos/generations

### Description
Adds a voice to the video generation using reference audio. Up to 3 entries, each naming a preset voice from the text-to-speech roster. Works only on `grok-imagine-video-1.5`. An unknown voice id returns a 400 with the list of valid ones.

### Method
POST

### Endpoint
/v1/videos/generations

### Parameters
#### Request Body
- **model** (string) - Required - Must be "grok-imagine-video-1.5".
- **reference_audios** (array) - Required - An array of up to 3 objects, each containing a `voice_id` field.
- **prompt** (string) - Required - A text description of the desired scene.
- **reference_images** (array) - Optional - An array of image objects, each containing a `url` field.
- **duration** (number) - Optional - The duration of the video in seconds.

### Request Example
(Not provided in source)

### Response
#### Success Response (200)
- **request_id** (string) - The identifier for the generation request, used for polling.

#### Error Response (400)
- **error** (object) - Contains a list of valid voice IDs.

#### Response Example
(Not provided in source)

```

--------------------------------

### cURL: Switch from OpenAI to Grokified

Source: https://grokified.com/docs/migration

Shows the before and after cURL commands for migrating from OpenAI. Point the base URL to https://api.grokified.com/v1, swap the key, and swap the model to a Grokified model. Note that gpt-4o has no Grokified equivalent, so the model name must change.

```bash
# Before — api.openai.com
curl https://api.openai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}'

# After — api.grokified.com
curl https://api.grokified.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GROKIFIED_API_KEY" \
  -d '{"model": "grok-4.7", "messages": [{"role": "user", "content": "Hello"}]}'
```

--------------------------------

### GET /files/{file_id}/content

Source: https://grokified.com/docs/files-collections

Stream the raw bytes of a file. Optionally retrieve extracted plain text.

```APIDOC
## GET /files/{file_id}/content

### Description
Fetch the raw bytes of a file. Add `?format=text` to get extracted plain text instead of the original file.

### Method
GET

### Endpoint
https://api.grokified.com/v1/files/{file_id}/content

### Parameters
#### Path Parameters
- **file_id** (string) - Required - The ID of the file to fetch.

#### Query Parameters
- **format** (string) - Optional - Set to "text" to get extracted plain text.

### Request Example
```
curl https://api.grokified.com/v1/files/file_a128090d-f0c9-4873-bd84-e499777e7417/content \
  -H "Authorization: Bearer $GROKIFIED_API_KEY" \
  --output handbook.pdf
```

### Response
#### Success Response (200)
- **body** (binary) - The raw file content or extracted text.

#### Response Example
```
(binary file content)
```
```

--------------------------------

### Generate a batch with b64_json response

Source: https://grokified.com/docs/images

Combine n with response_format b64_json to get all variations inline without follow-up fetches.

```bash
curl https://api.grokified.com/v1/images/generations \
  -H "Authorization: Bearer $GROKIFIED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-imagine-image-2.0", "prompt": "A futuristic city skyline at night, neon reflections on wet streets", "n": 2, "response_format": "b64_json"}'
```

--------------------------------

### GET /responses/{id}

Source: https://grokified.com/docs/responses-api

Fetches a stored response by its id. The response shape is the same as that returned by POST /responses when the response was originally created.

```APIDOC
## GET /responses/{id}

### Description
Fetches a response you already created, by id — the same shape `POST /responses` returned when you first created it.

### Method
GET

### Endpoint
`/responses/{id}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the response to retrieve.

### Request Example
```
curl https://api.grokified.com/v1/responses/resp_01j9k2m4n6p8q0r2s4t6u8v0w2 \
  -H "Authorization: Bearer $GROKIFIED_API_KEY"
```

### Response
#### Success Response (200)
Returns the response object with the same shape as the one returned by `POST /responses` when the response was created.

```

--------------------------------

### Reference to video with cURL

Source: https://grokified.com/docs/video

Uses `reference_images` to place a person, product, or clothing in a new scene. `prompt` is required and can tag images with `<IMAGE_0>`, `<IMAGE_1>`, etc. Accepts up to 3 images.

```bash
curl https://api.grokified.com/v1/videos/generations \
  -H "Authorization: Bearer $GROKIFIED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-imagine-video-1.5", "prompt": "The person from <IMAGE_0> wearing the jacket from <IMAGE_1>, walking down a rainy city street at night", "reference_images": [{"url": "https://example.com/person.png"}, {"url": "https://example.com/jacket.png"}], "duration": 6}'
```

--------------------------------

### client.beta.chat.completions.parse()

Source: https://grokified.com/docs/structured-outputs

SDK helper method for structured outputs using Pydantic models.

```APIDOC
## client.beta.chat.completions.parse()

### Description
SDK helper method that accepts a Pydantic BaseModel as the response format and returns a parsed, typed result. It handles schema conversion and JSON parsing automatically.

### Method
POST (underlying HTTP call)

### Endpoint
https://api.grokified.com/v1/chat/completions

### Parameters
- **model** (string) - Required - The model to use, e.g., "grok-4.7".
- **messages** (array) - Required - A list of message objects, each with a role and content.
- **response_format** (BaseModel) - Required - A Pydantic BaseModel class that defines the expected output schema.

### Request Example
```python
import os
from enum import Enum
from openai import OpenAI
from pydantic import BaseModel

client = OpenAI(api_key=os.environ["GROKIFIED_API_KEY"], base_url="https://api.grokified.com/v1")

class Urgency(str, Enum):
    low = "low"
    medium = "medium"
    high = "high"

class SupportTicket(BaseModel):
    name: str
    email: str
    urgency: Urgency

completion = client.beta.chat.completions.parse(
    model="grok-4.7",
    messages=[
        {"role": "system", "content": "Extract the sender contact details and urgency."},
        {"role": "user", "content": "Hi, this is Dana Wu (dana@example.com) - checkout is throwing 500s in prod, need this fixed today."},
    ],
    response_format=SupportTicket,
)
```

### Response
#### Success Response (200)
- **message.parsed** (object) - The typed result, an instance of the provided BaseModel.

#### Response Example
```python
ticket = completion.choices[0].message.parsed
print(ticket.name, ticket.email, ticket.urgency)
# Dana Wu dana@example.com Urgency.high
```
```

--------------------------------

### GET /v1/models/{id}

Source: https://grokified.com/docs/models

Fetches a single model's details, including context window and pricing, without scanning the entire catalog.

```APIDOC
## GET /v1/models/{id}

### Description
Returns the same fields as the list endpoint for a single model, useful for retrieving a specific model's context window or price.

### Method
GET

### Endpoint
/v1/models/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The model identifier (e.g., `grok-4.7`).

#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.

### Request Example
```
curl https://api.grokified.com/v1/models/grok-4.7 \
  -H "Authorization: Bearer $GROKIFIED_API_KEY"
```

### Response
#### Success Response (200)
- **model** (string) - The model identifier.
- **prompt_text_token_price** (integer) - Price in USD cents per 100 million tokens.

#### Response Example
```
{
  "model": "grok-4.7",
  "prompt_text_token_price": 20000
}
```
```

--------------------------------

### Turn on streaming with cURL

Source: https://grokified.com/docs/streaming

Enables streaming on a chat completion request by setting stream to true and stream_options.include_usage to true. The response comes back as text/event-stream with standard SSE events, ending with a literal data: [DONE] line.

```bash
curl https://api.grokified.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GROKIFIED_API_KEY" \
  -d '{
    "model": "grok-4.7",
    "stream": true,
    "stream_options": { "include_usage": true },
    "messages": [
      { "role": "user", "content": "Explain how neural networks learn in two sentences." }
    ]
  }'
```

--------------------------------

### DELETE /responses/{id}

Source: https://grokified.com/docs/responses-api

Removes a stored response before its 30-day retention window expires. Once deleted, that id no longer resolves as a previous_response_id or a GET target.

```APIDOC
## DELETE /responses/{id}

### Description
Removes a stored response before its 30-day retention window expires. Once deleted, that id no longer resolves as a `previous_response_id` or a `GET` target.

### Method
DELETE

### Endpoint
`/responses/{id}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The response ID (e.g., `resp_01j9k2m4n6p8q0r2s4t6u8v0w2`)

### Request Example
```
curl -X DELETE https://api.grokified.com/v1/responses/resp_01j9k2m4n6p8q0r2s4t6u8v0w2 \
  -H "Authorization: Bearer $GROKIFIED_API_KEY"
```

### Response
#### Success Response (200)
Confirms the response has been deleted.

```

--------------------------------

### POST /v1/videos/generations (Image to video)

Source: https://grokified.com/docs/video

Creates a video generation from a single still image. The image is locked as the first frame and animated. The prompt is optional; without one, motion is generated from the image alone.

```APIDOC
## [POST] /v1/videos/generations

### Description
Creates a video generation from a single still image. The image is locked as the first frame and animated. The prompt is optional; without one, motion is generated from the image alone.

### Method
POST

### Endpoint
/v1/videos/generations

### Parameters
#### Request Body
- **model** (string) - Required - The model identifier, e.g., "grok-imagine-video".
- **prompt** (string) - Optional - A text description of the desired motion or scene.
- **image** (object) - Required - An object containing a `url` field pointing to the source image.
- **duration** (number) - Optional - The duration of the video in seconds.

### Request Example
```
curl https://api.grokified.com/v1/videos/generations \
  -H "Authorization: Bearer $GROKIFIED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-imagine-video", "prompt": "Waves rolling gently onto the shore", "image": {"url": "https://example.com/beach.png"}, "duration": 6}'
```

### Response
#### Success Response (200)
- **request_id** (string) - The identifier for the generation request, used for polling.

#### Response Example
(Not provided in source)

```

--------------------------------

### Let the model search with file_search tool (POST /responses)

Source: https://grokified.com/docs/files-collections

Passes a file_search tool on /responses with collection ids in vector_store_ids. The model decides when to search and cites findings. Some SDKs call this tool collections_search.

```bash
curl https://api.grokified.com/v1/responses \
  -H "Authorization: Bearer $GROKIFIED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.7",
    "input": [{ "role": "user", "content": "What is the vacation policy?" }],
    "tools": [{ "type": "file_search", "vector_store_ids": ["'"$COLLECTION_ID"'"] }]
  }'
```

--------------------------------

### GET /responses/{id}/input_items

Source: https://grokified.com/docs/responses-api

Lists the input items stored against a response, useful for auditing exactly what was sent without keeping your own copy of every conversation.

```APIDOC
## GET /responses/{id}/input_items

### Description
Lists the input items stored against a response — useful for auditing exactly what was sent, without keeping your own copy of every conversation.

### Method
GET

### Endpoint
`/responses/{id}/input_items`

### Parameters
#### Path Parameters
- **id** (string) - Required - The response ID (e.g., `resp_01j9k2m4n6p8q0r2s4t6u8v0w2`)

### Request Example
```
curl https://api.grokified.com/v1/responses/resp_01j9k2m4n6p8q0r2s4t6u8v0w2/input_items \
  -H "Authorization: Bearer $GROKIFIED_API_KEY"
```

### Response
#### Success Response (200)
Returns the list of input items stored against the response.

```

--------------------------------

### First request: model asks for data (cURL)

Source: https://grokified.com/docs/function-calling

Send a chat completion request with a user message and a tool definition. The model returns a tool_calls array instead of a normal reply when it needs data.

```bash
curl https://api.grokified.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GROKIFIED_API_KEY" \
  -d '{
    "model": "grok-4.7",
    "messages": [
      { "role": "user", "content": "What is the temperature in San Francisco?" }
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_temperature",
          "description": "Get the current temperature for a city",
          "parameters": {
            "type": "object",
            "properties": { "location": { "type": "string", "description": "City name" } },
            "required": ["location"]
          }
        }
      }
    ]
  }'
```

--------------------------------

### Delete a stored response with cURL

Source: https://grokified.com/docs/responses-api

Deletes a stored response before its 30-day retention window expires. Once deleted, the id no longer resolves as a previous_response_id or a GET target.

```bash
curl -X DELETE https://api.grokified.com/v1/responses/resp_01j9k2m4n6p8q0r2s4t6u8v0w2 \
  -H "Authorization: Bearer $GROKIFIED_API_KEY"
```

--------------------------------

### POST /v1/responses

Source: https://grokified.com/docs/mcp

Documentation for connecting a remote MCP server as a tool in the Grokified API, including the request format, parameters, and limitations.

```APIDOC
## [POST] /v1/responses

### Description
Creates a response using a remote MCP server as a tool. The model discovers and calls the server's tools server-side.

### Method
POST

### Endpoint
https://api.grokified.com/v1/responses

### Parameters
#### Request Body
- **model** (string) - Required - The model to use, e.g., "grok-4.7".
- **input** (array) - Required - The user input, e.g., [{"role": "user", "content": "..."}].
- **tools** (array) - Required - List of tool configurations. Each MCP tool entry must include:
  - **type** (string) - Required - Must be "mcp".
  - **server_url** (string) - Required - The MCP server's URL. Only Streaming HTTP and SSE transports are supported.
  - **server_label** (string) - Required - Identifies the server and prefixes its tool calls.
  - **server_description** (string) - Optional - Describes what the server provides.
  - **allowed_tools** (array of strings) - Optional - Only these tool names reach the model. Empty allows every tool the server exposes.
  - **authorization** (string) - Optional - Bearer token sent in the Authorization header on requests to the MCP server.
  - **headers** (object) - Optional - Extra headers sent to the MCP server.

### Request Example
{
  "model": "grok-4.7",
  "input": [{ "role": "user", "content": "What can you do with https://github.com/psf/requests?" }],
  "tools": [{ "type": "mcp", "server_url": "https://mcp.deepwiki.com/mcp", "server_label": "deepwiki" }]
}

### Response
#### Success Response (200)
- **id** (string) - The response identifier.
- **object** (string) - The object type, e.g., "response".
- **created_at** (integer) - Unix timestamp of creation.
- **status** (string) - The status of the response, e.g., "completed".
- **output** (array) - The output items, including tool calls and messages.
- **usage** (object) - Token usage details.

#### Response Example
{
  "id": "resp_123",
  "object": "response",
  "created_at": 1710000000,
  "status": "completed",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "The requests library is a popular HTTP client for Python..."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 100,
    "output_tokens": 50,
    "total_tokens": 150
  }
}

### Error Handling
- **401 Unauthorized** - Invalid or missing API key.
- **403 Forbidden** - Insufficient permissions (e.g., Basic plan).
- **404 Not Found** - Invalid endpoint or model.
- **429 Too Many Requests** - Rate limit exceeded.
- **500 Internal Server Error** - Server error.

### Notes
- `require_approval` and `connector_id` are not currently supported.
- Multiple MCP servers can be listed in the same request, each with its own `server_label`.
```

--------------------------------

### GET /v1/language-models

Source: https://grokified.com/docs/models

Returns a typed catalog of language models (chat and image-understanding) with additional fields like modalities, fingerprint, cached-token pricing, and long-context rates.

```APIDOC
## GET /v1/language-models

### Description
Returns a typed catalog of chat and image-understanding models, with more fields than the generic models endpoint: input/output modalities, a system fingerprint, cached-token pricing, and long-context rates. These models are called through `/chat/completions` or `/responses`.

### Method
GET

### Endpoint
/v1/language-models

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.

### Request Example
```
curl https://api.grokified.com/v1/language-models \
  -H "Authorization: Bearer $GROKIFIED_API_KEY"
```

### Response
#### Success Response (200)
- **model** (string) - The model identifier.
- **input_modalities** (array) - Supported input modalities.
- **output_modalities** (array) - Supported output modalities.
- **fingerprint** (string) - System fingerprint.
- **cached_token_price** (integer) - Cached-token pricing.
- **long_context_rate** (integer) - Long-context rate.

#### Response Example
```
{
  "model": "grok-4.7",
  "input_modalities": ["text"],
  "output_modalities": ["text"],
  "fingerprint": "fp_abc123",
  "cached_token_price": 10000,
  "long_context_rate": 5000
}
```
```

--------------------------------

### GET /chat/deferred-completion/{request_id}

Source: https://grokified.com/docs/deferred-completions

Polls for the result of a deferred completion. Returns 200 with the full completion body when done, or 202 with an empty body if still processing.

```APIDOC
## GET /chat/deferred-completion/{request_id}

### Description
Retrieves the result of a deferred completion. Poll this endpoint until it returns `200` with the full completion body. A `202` with an empty body means the request is still being processed.

### Method
GET

### Endpoint
`https://api.grokified.com/v1/chat/deferred-completion/{request_id}`

### Parameters
#### Path Parameters
- **request_id** (string) - Required - The ID returned from the initial deferred completion request.

### Response
#### Success Response (200)
- **choices** (array) - The completion choices, each containing a `message` with `content`.

#### Response Example
```json
{
  "choices": [
    {
      "message": {
        "content": "..."
      }
    }
  ]
}
```

#### Processing Response (202)
- Empty body - The request is still being processed; keep polling.

### Notes
- The result is handed out exactly once. After a `200` response, the result is discarded and cannot be retrieved again.
- Unclaimed results are discarded after 24 hours.
```

--------------------------------

### cURL: Switch from any chat-completions provider to Grokified

Source: https://grokified.com/docs/migration

Shows the before and after cURL commands for migrating a chat-completions client. Change the host to api.grokified.com, swap the access key, and swap the model to a Grokified one such as grok-4.7. The body and response shape remain unchanged.

```bash
# Before — your current provider
curl https://api.your-provider.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PROVIDER_API_KEY" \
  -d '{"model": "your-model", "messages": [{"role": "user", "content": "Hello"}]}'

# After — api.grokified.com
curl https://api.grokified.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GROKIFIED_API_KEY" \
  -d '{"model": "grok-4.7", "messages": [{"role": "user", "content": "Hello"}]}'
```

--------------------------------

### Edit a video with POST /videos/edits (cURL)

Source: https://grokified.com/docs/video

Sends a POST request to edit an existing video using a prompt. The output inherits the source's duration, ratio, and resolution (capped at 720p). Requires the GROKIFIED_API_KEY environment variable.

```bash
curl https://api.grokified.com/v1/videos/edits \
  -H "Authorization: Bearer $GROKIFIED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-imagine-video", "prompt": "Give the rider a red helmet", "video": {"url": "https://example.com/render.mp4"}}'
```