OpenX API Docs

1. Quick Start

OpenX API is 100% compatible with the OpenAI Chat Completions format. You can use any OpenAI SDK to access Twitter data.

Three things you need

Minimal example (Python)

from openai import OpenAI
import json

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.gugou.ai/v1",
)

resp = client.chat.completions.create(
    model="x-search-tweets",
    messages=[{
        "role": "user",
        "content": json.dumps({
            "query": "bitcoin",
            "limit": 5,
            "product": "Latest"
        })
    }]
)

tweets = json.loads(resp.choices[0].message.content)
for t in tweets:
    print(f"@{t['user']['username']}: {t['rawContent'][:80]}")

Minimal example (cURL)

curl -X POST https://api.gugou.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "x-search-tweets",
    "messages": [{"role": "user", "content": "{\"query\":\"bitcoin\",\"limit\":5,\"product\":\"Latest\"}"}]
  }'

2. Authentication

All requests require an API key in the Authorization header:

Authorization: Bearer sk-your-api-key

3. Available Models

Parameter Reference

4. Request Format

Parameters are passed as a JSON string inside the user message content:

{
  "model": "x-search-tweets",
  "messages": [
    {
      "role": "user",
      "content": "{\"query\": \"bitcoin\", \"limit\": 10, \"product\": \"Latest\"}"
    }
  ],
  "stream": false
}

For stock ticker searches

When searching for stock-related tweets, it is recommended to use $ + stock symbol for better precision.

{
  "model": "x-search-tweets",
  "messages": [
    {
      "role": "user",
      "content": "{\"query\": \"$TSLA\", \"limit\": 10, \"product\": \"Latest\"}"
    }
  ]
}

Advanced stock search examples

You can combine ticker symbols with company names or other query operators for broader or more precise matching.

{
  "model": "x-search-tweets",
  "messages": [
    {
      "role": "user",
      "content": "{\"query\": \"$TSLA OR Tesla\", \"limit\": 20, \"product\": \"Latest\"}"
    }
  ]
}

{
  "model": "x-search-tweets",
  "messages": [
    {
      "role": "user",
      "content": "{\"query\": \"$AAPL lang:en\", \"limit\": 20, \"product\": \"Latest\"}"
    }
  ]
}

For user-based models

{
  "model": "x-user-tweets",
  "messages": [
    {
      "role": "user",
      "content": "{\"user_id\": 44196397, \"limit\": 10}"
    }
  ]
}

5. Response Format

Responses follow the standard OpenAI Chat Completions format. The actual Twitter data is in choices[0].message.content as a JSON string that needs to be parsed.

{
  "id": "chatcmpl-openx-7663002f5683",
  "object": "chat.completion",
  "created": 1774489310,
  "model": "x-search-tweets",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "[{\"id\": 123, \"rawContent\": \"...\", \"user\": {...}}, ...]"
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 100,
    "completion_tokens": 900,
    "total_tokens": 1000
  }
}

Tweet Object Fields

User Object Fields

6. Code Examples

Python — Search tweets

from openai import OpenAI
import json

client = OpenAI(api_key="sk-your-key", base_url="https://api.gugou.ai/v1")

resp = client.chat.completions.create(
    model="x-search-tweets",
    messages=[{"role": "user", "content": json.dumps({
        "query": "$TSLA OR $BTC",
        "limit": 20,
        "product": "Latest"
    })}]
)

tweets = json.loads(resp.choices[0].message.content)
for t in tweets:
    print(f"@{t['user']['username']} [{t['likeCount']} likes]: {t['rawContent'][:100]}")

Python — Advanced stock query

resp = client.chat.completions.create(
    model="x-search-tweets",
    messages=[{
        "role": "user",
        "content": json.dumps({
            "query": "$TSLA OR Tesla lang:en",
            "limit": 20,
            "product": "Latest"
        })
    }]
)

tweets = json.loads(resp.choices[0].message.content)
for t in tweets:
    print(f"@{t['user']['username']}: {t['rawContent'][:120]}")

Python — Get user info

# Step 1: Find user ID
resp = client.chat.completions.create(
    model="x-search-users",
    messages=[{"role": "user", "content": json.dumps({"query": "elonmusk", "limit": 1})}]
)
users = json.loads(resp.choices[0].message.content)
user_id = users[0]["id"]
print(f"Found: @{users[0]['username']} (ID: {user_id}, Followers: {users[0]['followersCount']})")

# Step 2: Get their tweets
resp = client.chat.completions.create(
    model="x-user-tweets",
    messages=[{"role": "user", "content": json.dumps({"user_id": user_id, "limit": 5})}]
)
tweets = json.loads(resp.choices[0].message.content)
for t in tweets:
    print(f"  {t['rawContent'][:100]}")

Node.js — Search users

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-your-key",
  baseURL: "https://api.gugou.ai/v1",
});

const resp = await client.chat.completions.create({
  model: "x-search-users",
  messages: [{ role: "user", content: JSON.stringify({ query: "AI", limit: 5 }) }],
});

const users = JSON.parse(resp.choices[0].message.content);
users.forEach(u => console.log(`@${u.username} - ${u.followersCount} followers`));

cURL — Get followers

curl -X POST https://api.gugou.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "x-user-followers",
    "messages": [{"role": "user", "content": "{\"user_id\": 44196397, \"limit\": 10}"}]
  }'

7. Streaming (SSE)

Set "stream": true to receive results as Server-Sent Events. Each chunk contains one page of results.

resp = client.chat.completions.create(
    model="x-search-tweets",
    messages=[{"role": "user", "content": json.dumps({
        "query": "breaking news",
        "limit": 50,
        "product": "Latest"
    })}],
    stream=True
)

for chunk in resp:
    if chunk.choices[0].delta.content:
        page = json.loads(chunk.choices[0].delta.content)
        print(f"Received {len(page)} tweets in this chunk")

8. Error Codes

Error response format

{
  "error": {
    "message": "Model 'x-bad-model' not found. Available: ['x-search-tweets', ...]",
    "type": "model_not_found",
    "code": "model_not_found"
  }
}

9. Rate Limits & Best Practices

• Recommended limit per request: 20–50 for optimal latency.
• Maximum limit per request: 500.
• Large requests (limit > 100) may take 30–60 seconds. Consider using stream: true.
• Implement exponential backoff for scraping_error responses.
• Cache results locally when possible to reduce API calls and costs.