Skills
skills/catfishw/grokagentskill/grok-api

grok-api

SKILL.md

Grok API (via grok2api)

OpenAI-compatible Grok API proxy hosted at https://mc.agaii.org/grok. Use this skill whenever the user asks you to call Grok models, generate text with Grok, or interact with the Grok API.

Overview

  • Base URL: https://mc.agaii.org/grok/v1
  • Auth header: Authorization: Bearer <app_key>
  • Protocol: OpenAI-compatible (drop-in replacement for openai SDK)
  • Admin panel: https://mc.agaii.org/grok/admin/login

The API supports chat completions, streaming, and all standard OpenAI-compatible parameters.

Step 0: Confirm Credentials

Before making any call, confirm the app key is available. The key is used as a Bearer token:

# Verify the key works
curl -s https://mc.agaii.org/grok/v1/models \
  -H "Authorization: Bearer <app_key>"

A successful response lists available Grok models.

Step 1: Choose a Model

Use GET /v1/models to list available models, or pick from the well-known ones:

Model Description
grok-3 Most capable, best for complex reasoning
grok-3-fast Fast variant of Grok-3
grok-3-mini Lightweight, efficient
grok-3-mini-fast Fastest, lowest latency
grok-2-vision-1212 Vision-capable model 
curl -s https://mc.agaii.org/grok/v1/models \
  -H "Authorization: Bearer <app_key>" | python3 -m json.tool

Step 2: Chat Completions

Non-streaming

curl -s -X POST https://mc.agaii.org/grok/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <app_key>" \
  -d '{
    "model": "grok-3",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Explain quantum entanglement in simple terms."}
    ],
    "temperature": 0.7,
    "max_tokens": 1024
  }'

Response shape:

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "grok-3",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "..."
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0
  }
}

Streaming

curl -s -X POST https://mc.agaii.org/grok/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <app_key>" \
  -d '{
    "model": "grok-3",
    "messages": [{"role": "user", "content": "Write a haiku about the sea."}],
    "stream": true
  }'

Streaming returns text/event-stream Server-Sent Events. Each chunk is:

data: {"id":"...","object":"chat.completion.chunk","choices":[{"delta":{"content":"..."}}]}

The stream ends with data: [DONE].

Step 3: Using the Python Script

A ready-to-use Python script is available at scripts/grok_api.py in this skill directory.

Find it:

# If installed via npx skills add
ls .cursor/skills/GrokAgentSkill/scripts/grok_api.py

Run examples

# Simple chat
python scripts/grok_api.py chat "What is the capital of France?"

# Chat with a specific model
python scripts/grok_api.py chat "Write a poem" --model grok-3-mini

# Streaming chat
python scripts/grok_api.py chat "Tell me a story" --stream

# Multi-turn conversation (JSON file)
python scripts/grok_api.py file scripts/example_messages.json

# List models
python scripts/grok_api.py models

Set the app key via environment variable (recommended):

export GROK_API_KEY=<app_key>
python scripts/grok_api.py chat "Hello"

Or pass inline:

python scripts/grok_api.py chat "Hello" --key <app_key>

Step 4: Using the OpenAI Python SDK

The API is a drop-in replacement. Install: pip install openai

from openai import OpenAI

client = OpenAI(
    base_url="https://mc.agaii.org/grok/v1",
    api_key="<app_key>",
)

response = client.chat.completions.create(
    model="grok-3",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is 2 + 2?"},
    ],
)
print(response.choices[0].message.content)

Streaming with SDK

stream = client.chat.completions.create(
    model="grok-3",
    messages=[{"role": "user", "content": "Count to 5 slowly."}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

Async usage

import asyncio
from openai import AsyncOpenAI

client = AsyncOpenAI(
    base_url="https://mc.agaii.org/grok/v1",
    api_key="<app_key>",
)

async def main():
    response = await client.chat.completions.create(
        model="grok-3-fast",
        messages=[{"role": "user", "content": "Hello!"}],
    )
    print(response.choices[0].message.content)

asyncio.run(main())

API Reference

POST /v1/chat/completions

Parameter Type Required Description
model string Yes Model ID (e.g. grok-3)
messages array Yes Array of {role, content} objects
stream boolean No Enable SSE streaming (default: false)
temperature float No Sampling temperature 0–2 (default: 1.0)
max_tokens integer No Max tokens to generate
top_p float No Nucleus sampling (default: 1.0)
frequency_penalty float No -2.0 to 2.0
presence_penalty float No -2.0 to 2.0
stop string/array No Stop sequences
n integer No Number of completions
user string No End-user identifier

Message roles

Role Description
system Sets assistant behavior/persona
user Human turn
assistant Previous assistant turn (for multi-turn)

GET /v1/models

Returns list of available models. No body required.

Error codes

Code Meaning
401 Invalid or missing API key
429 No available tokens / rate limited
500 Internal server error

Admin API

All admin endpoints require Authorization: Bearer <app_key>.

List tokens

curl https://mc.agaii.org/grok/v1/admin/tokens \
  -H "Authorization: Bearer <app_key>"

Add / update tokens

curl -X POST https://mc.agaii.org/grok/v1/admin/tokens \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <app_key>" \
  -d '{"ssoBasic": [{"token": "<sso_token>", "status": "active", "quota": 10, "created_at": 0, "use_count": 0, "fail_count": 0, "tags": [], "note": ""}]}'

Refresh token quota

curl -X POST https://mc.agaii.org/grok/v1/admin/tokens/refresh \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <app_key>" \
  -d '{"token": "<sso_token>"}'

Common Patterns

System prompt + user message

messages = [
    {"role": "system", "content": "You are an expert Python developer. Be concise."},
    {"role": "user", "content": "How do I read a file line by line in Python?"},
]

Multi-turn conversation

messages = [
    {"role": "user", "content": "My name is Alice."},
    {"role": "assistant", "content": "Nice to meet you, Alice!"},
    {"role": "user", "content": "What is my name?"},
]

Low-latency use case

Use grok-3-mini-fast with max_tokens set to limit response length:

client.chat.completions.create(
    model="grok-3-mini-fast",
    messages=[{"role": "user", "content": "Summarize in one sentence: ..."}],
    max_tokens=100,
)

Structured output (JSON mode)

client.chat.completions.create(
    model="grok-3",
    messages=[
        {"role": "system", "content": "Always respond with valid JSON only."},
        {"role": "user", "content": "List 3 fruits with their colors as JSON."},
    ],
    temperature=0,
)

Image Generation

Use model grok-imagine-1.0 to generate images from a text prompt.

curl -s -X POST https://mc.agaii.org/grok/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <app_key>" \
  -d '{
    "model": "grok-imagine-1.0",
    "messages": [{"role": "user", "content": "A photorealistic red apple on a wooden table"}]
  }'

The response content will contain an <img> tag with a src URL pointing to the generated image.

Parse the image URL from the response:

import re
content = response["choices"][0]["message"]["content"]
match = re.search(r'src="([^"]+)"', content)
image_url = match.group(1) if match else None

Image editing

Use model grok-imagine-1.0-edit with an existing image URL in the prompt:

-d '{"model": "grok-imagine-1.0-edit", "messages": [{"role": "user", "content": "Make the apple golden. Image: https://..."}]}'

Video Generation

Use model grok-imagine-1.0-video to generate short videos from a text prompt.

Important: The API streams progress updates as SSE chunks (percent complete), then delivers the final video URL embedded in HTML at 100%. You MUST stream the response and parse the final chunk for the video URL.

Step-by-step workflow

1. Submit the request (streaming required):

curl -s -X POST https://mc.agaii.org/grok/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <app_key>" \
  -d '{
    "model": "grok-imagine-1.0-video",
    "messages": [{"role": "user", "content": "<your video prompt>"}]
  }' > /tmp/video_response.txt

2. Extract the video URL from the streamed output:

grep -oP 'src=\\"https://[^"]+\.mp4\\"' /tmp/video_response.txt | head -1 | grep -oP 'https://[^"\\]+'

Or in Python:

import re, subprocess, json

# Run curl and capture all SSE lines
output = subprocess.check_output([
    "curl", "-s", "-X", "POST",
    "https://mc.agaii.org/grok/v1/chat/completions",
    "-H", "Content-Type: application/json",
    "-H", f"Authorization: Bearer {api_key}",
    "-d", json.dumps({
        "model": "grok-imagine-1.0-video",
        "messages": [{"role": "user", "content": prompt}]
    })
], timeout=300).decode()

# Extract video URL
match = re.search(r'src=\\"(https://[^"\\]+\.mp4)\\"', output)
video_url = match.group(1) if match else None
print("Video URL:", video_url)

3. Download the video:

wget -O output.mp4 "<video_url>"
# or
curl -L -o output.mp4 "<video_url>"

Using the bundled script

GROK_API_KEY=<key> python scripts/grok_api.py video "A glowing figure rotating in the dark"

This will print the video URL when generation completes (typically takes 20–60 seconds).

Progress tracking

During generation the API streams lines like:

正在生成视频中，当前进度1%
正在生成视频中，当前进度25%
...
正在生成视频中，当前进度100%
<video id="video" ...><source src="https://.../generated_video.mp4" ...></video>

The final content after 100% contains the <video> HTML with the mp4 URL and a preview image (poster).

Preview image

The poster/thumbnail URL is also embedded:

poster="https://mc.agaii.org/grok/v1/files/image/.../preview_image.jpg"

Extract with:

match = re.search(r'poster=\\"(https://[^"\\]+)\\"', output)
preview_url = match.group(1) if match else None

Tips for good video prompts

  • Describe subject, motion, camera movement, and lighting explicitly
  • Mention tone (cinematic, futuristic, elegant, etc.)
  • Keep prompts under 300 words
  • Dark backgrounds with glowing elements tend to render well
  • Specify duration feel with pacing words ("slowly pulls back", "quick cut", etc.)

Troubleshooting

Symptom Cause Fix
429 "No available tokens" Token pool empty or all cooling Add more SSO tokens via admin API
401 Unauthorized Wrong app key Check Authorization: Bearer <key> header
Connection refused Server not running Check service on port 15125
Blank content in response Model returned empty Try again or reduce temperature
Token refresh returns false SSO token expired Remove token and add a fresh one
Weekly Installs
9
Repository
catfishw/grokagentskill
First Seen
Feb 23, 2026
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykFail
Installed on
opencode9
gemini-cli9
github-copilot9
amp9
cline9
codex9