Create Chat Completion

Create a chat completion with AI that understands activist strategy.

This endpoint is 100% OpenAI SDK compatible. Just change the base URL!

Endpoint

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

Required Scopes

chat:write - Create chat completions

Request Body

Parameter	Type	Required	Description
`model`	string	Yes	Model ID: `"grok-2"`
`messages`	array	Yes	Array of message objects (see below)
`stream`	boolean	No	Enable streaming responses (default: `false`)
`temperature`	number	No	Randomness (0-2, default: 1)
`max_tokens`	number	No	Maximum completion tokens
`session_id`	string	No	Session ID for multi-turn conversations
`x-theory-position`	object	No	Theory of Change position `{x, y}`

Message Object

Field	Type	Description
`role`	string	`"system"`, `"user"`, or `"assistant"`
`content`	string	Message text content

Response

Non-Streaming Response

{
  "id": "chatcmpl_abc123",
  "object": "chat.completion",
  "created": 1730634060,
  "model": "grok-2",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "To organize a grassroots campaign..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 150,
    "total_tokens": 165
  },
  "session_id": "chat_abc123"
}

Streaming Response

When stream: true, returns Server-Sent Events (SSE):

data: {"id":"chatcmpl_abc123","object":"chat.completion.chunk","created":1730634060,"model":"grok-2","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"chatcmpl_abc123","object":"chat.completion.chunk","created":1730634060,"model":"grok-2","choices":[{"index":0,"delta":{"content":"To"},"finish_reason":null}]}

data: {"id":"chatcmpl_abc123","object":"chat.completion.chunk","created":1730634060,"model":"grok-2","choices":[{"index":0,"delta":{"content":" organize"},"finish_reason":null}]}

...

data: {"id":"chatcmpl_abc123","object":"chat.completion.chunk","created":1730634060,"model":"grok-2","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

Examples

Basic Completion

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.OUTCRY_API_KEY,
  baseURL: 'https://api.outcryai.com/v1'
});

const completion = await client.chat.completions.create({
  model: 'grok-2',
  messages: [
    {
      role: 'user',
      content: 'How do I organize a grassroots campaign?'
    }
  ]
});

console.log(completion.choices[0].message.content);

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("OUTCRY_API_KEY"),
    base_url="https://api.outcryai.com/v1"
)

completion = client.chat.completions.create(
    model="grok-2",
    messages=[
        {
            "role": "user",
            "content": "How do I organize a grassroots campaign?"
        }
    ]
)

print(completion.choices[0].message.content)

curl https://api.outcryai.com/v1/chat/completions \
  -H "Authorization: Bearer oc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-2",
    "messages": [
      {
        "role": "user",
        "content": "How do I organize a grassroots campaign?"
      }
    ]
  }'

With System Message

Set context and persona with a system message:

const completion = await client.chat.completions.create({
  model: 'grok-2',
  messages: [
    {
      role: 'system',
      content: 'You are an expert in grassroots organizing with 20 years of experience'
    },
    {
      role: 'user',
      content: 'How do I build a coalition?'
    }
  ]
});

completion = client.chat.completions.create(
    model="grok-2",
    messages=[
        {
            "role": "system",
            "content": "You are an expert in grassroots organizing with 20 years of experience"
        },
        {
            "role": "user",
            "content": "How do I build a coalition?"
        }
    ]
)

Multi-Turn Conversation

Method 1: Send Full History

const messages = [
  { role: 'user', content: 'What is direct action?' },
  { role: 'assistant', content: 'Direct action is...' },
  { role: 'user', content: 'Can you give me examples?' }
];

const completion = await client.chat.completions.create({
  model: 'grok-2',
  messages
});

messages = [
    {"role": "user", "content": "What is direct action?"},
    {"role": "assistant", "content": "Direct action is..."},
    {"role": "user", "content": "Can you give me examples?"}
]

completion = client.chat.completions.create(
    model="grok-2",
    messages=messages
)

Method 2: Use Session ID

// First message
const completion1 = await client.chat.completions.create({
  model: 'grok-2',
  messages: [{ role: 'user', content: 'What is direct action?' }],
  // @ts-ignore - Vendor extension
  session_id: 'my-conversation-123'
});

// Follow-up (references previous context)
const completion2 = await client.chat.completions.create({
  model: 'grok-2',
  messages: [{ role: 'user', content: 'Can you give me examples?' }],
  // @ts-ignore - Vendor extension
  session_id: 'my-conversation-123'
});

# First message
completion1 = client.chat.completions.create(
    model="grok-2",
    messages=[{"role": "user", "content": "What is direct action?"}],
    session_id="my-conversation-123"
)

# Follow-up (references previous context)
completion2 = client.chat.completions.create(
    model="grok-2",
    messages=[{"role": "user", "content": "Can you give me examples?"}],
    session_id="my-conversation-123"
)

With Theory of Change

Align AI responses with your strategic framework:

const completion = await client.chat.completions.create({
  model: 'grok-2',
  messages: [
    { role: 'user', content: 'How can I fight climate change?' }
  ],
  // @ts-ignore - Vendor extension
  'x-theory-position': {
    x: -0.7,  // Subjective (grassroots)
    y: -0.5   // Material (concrete action)
  }
});

// Response emphasizes grassroots organizing and direct action

completion = client.chat.completions.create(
    model="grok-2",
    messages=[
        {"role": "user", "content": "How can I fight climate change?"}
    ],
    x_theory_position={
        "x": -0.7,  # Subjective (grassroots)
        "y": -0.5   # Material (concrete action)
    }
)

# Response emphasizes grassroots organizing and direct action

Theory Positions:

Voluntarism {x: -1, y: -1} - Grassroots mobilization
Structuralism {x: 1, y: -1} - Policy/systems change
Subjectivism {x: -1, y: 1} - Cultural transformation
Theurgism {x: 1, y: 1} - Faith-based activism

See the Theory of Change Guide for details.

Streaming Response

Get real-time token-by-token responses:

const stream = await client.chat.completions.create({
  model: 'grok-2',
  messages: [{ role: 'user', content: 'Explain civil disobedience' }],
  stream: true
});

for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content || '';
  process.stdout.write(content);
}

stream = client.chat.completions.create(
    model="grok-2",
    messages=[{"role": "user", "content": "Explain civil disobedience"}],
    stream=True
)

for chunk in stream:
    content = chunk.choices[0].delta.content or ""
    print(content, end="")

See the Streaming Guide for advanced patterns.

Temperature Control

Control response randomness:

// More focused and deterministic
const completion = await client.chat.completions.create({
  model: 'grok-2',
  messages: [{ role: 'user', content: 'What is organizing?' }],
  temperature: 0.3
});

// More creative and varied
const completion2 = await client.chat.completions.create({
  model: 'grok-2',
  messages: [{ role: 'user', content: 'Brainstorm campaign slogans' }],
  temperature: 1.5
});

# More focused and deterministic
completion = client.chat.completions.create(
    model="grok-2",
    messages=[{"role": "user", "content": "What is organizing?"}],
    temperature=0.3
)

# More creative and varied
completion2 = client.chat.completions.create(
    model="grok-2",
    messages=[{"role": "user", "content": "Brainstorm campaign slogans"}],
    temperature=1.5
)

Max Tokens

Limit response length:

const completion = await client.chat.completions.create({
  model: 'grok-2',
  messages: [{ role: 'user', content: 'Explain activism' }],
  max_tokens: 500  // ~375 words
});

completion = client.chat.completions.create(
    model="grok-2",
    messages=[{"role": "user", "content": "Explain activism"}],
    max_tokens=500  # ~375 words
)

Error Responses

400 Bad Request

{
  "error": {
    "type": "invalid_request_error",
    "message": "Missing or invalid model",
    "param": "model",
    "code": "invalid_model"
  }
}

401 Unauthorized

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid or expired API key",
    "code": "invalid_api_key"
  }
}

402 Payment Required

{
  "error": {
    "type": "insufficient_quota",
    "message": "Insufficient prepaid balance. Please add funds to continue.",
    "code": "insufficient_quota"
  }
}

429 Too Many Requests

{
  "error": {
    "type": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 30 seconds.",
    "code": "rate_limit_exceeded"
  }
}

Pricing

Chat is billed per token at $0.08 per 1,000 tokens. Token Estimation:

~750 words = 1,000 tokens
Average message: 50-200 tokens
Typical conversation: 500-2,000 tokens ( $0.04-$ 0.16)

Example costs:

Question: "How do I organize?" (5 tokens)
Answer: 200-word response (267 tokens)
Total: 272 tokens = $0.02

Rate Limits

Tier	Requests per Minute	Tokens per Day
Free	10	10,000
Standard	60	1,000,000
Premium	300	10,000,000
Enterprise	Custom	Custom

Best Practices

1. Use System Messages

Set context with system messages for better responses:

const completion = await client.chat.completions.create({
  model: 'grok-2',
  messages: [
    {
      role: 'system',
      content: 'You are an expert in grassroots organizing with 20 years of experience'
    },
    {
      role: 'user',
      content: 'How do I build a coalition?'
    }
  ]
});

2. Manage Context Window

Keep conversations under 128K tokens. See best practices guide.

3. Use Streaming for UX

Stream responses for better perceived performance:

const stream = await client.chat.completions.create({
  model: 'grok-2',
  messages: [{ role: 'user', content: 'Long question...' }],
  stream: true
});

4. Handle Errors Gracefully

Always implement retry logic and error handling. See Error Handling Guide.

Next Steps

Streaming

Use streaming for real-time responses

List Sessions

List chat sessions

Theory of Change

Align AI with your strategic approach

Error Handling

Handle errors gracefully

Video API

Chat API

Text API

Webhooks API

Create

Create Chat Completion

Endpoint

Required Scopes

Request Body

Message Object

Response

Non-Streaming Response

Streaming Response

Examples

Basic Completion

With System Message

Multi-Turn Conversation

Method 1: Send Full History

Method 2: Use Session ID

With Theory of Change

Streaming Response

Temperature Control

Max Tokens

Error Responses

400 Bad Request

401 Unauthorized

402 Payment Required

429 Too Many Requests

Pricing

Rate Limits

Best Practices

1. Use System Messages

2. Manage Context Window

3. Use Streaming for UX

4. Handle Errors Gracefully

Next Steps

Streaming

List Sessions

Theory of Change

Error Handling

​Create Chat Completion

​Endpoint

​Required Scopes

​Request Body

​Message Object

​Response

​Non-Streaming Response

​Streaming Response

​Examples

​Basic Completion

​With System Message

​Multi-Turn Conversation

​Method 1: Send Full History

​Method 2: Use Session ID

​With Theory of Change

​Streaming Response

​Temperature Control

​Max Tokens

​Error Responses

​400 Bad Request

​401 Unauthorized

​402 Payment Required

​429 Too Many Requests

​Pricing

​Rate Limits

​Best Practices

​1. Use System Messages

​2. Manage Context Window

​3. Use Streaming for UX

​4. Handle Errors Gracefully

​Next Steps

Streaming

List Sessions

Theory of Change

Error Handling

Create Chat Completion

Endpoint

Required Scopes

Request Body

Message Object

Response

Non-Streaming Response

Streaming Response

Examples

Basic Completion

With System Message

Multi-Turn Conversation

Method 1: Send Full History

Method 2: Use Session ID

With Theory of Change

Streaming Response

Temperature Control

Max Tokens

Error Responses

400 Bad Request

401 Unauthorized

402 Payment Required

429 Too Many Requests

Pricing

Rate Limits

Best Practices

1. Use System Messages

2. Manage Context Window

3. Use Streaming for UX

4. Handle Errors Gracefully

Next Steps