Quickstart Guide

Get started with Outcry AI in under 5 minutes. This guide will walk you through authentication, adding credits, and making your first API requests.

Prerequisites

An Outcry AI account (sign up here)
Node.js 16+ or Python 3.8+ installed
5 minutes of your time

Step 1: Get Your API Key

Navigate to outcryai.com and log in to your account.

Generate an API key

Go to Settings > API Keys and click Create New Key.Give your key a name (e.g., “Production Key”) and select the scopes you need:

video:write - Create videos
video:read - Check video status
chat:write - Create chat completions
chat:read - Retrieve chat history

Save your key securely

Your API key will be shown only once. Copy it and store it securely:

oc_live_abc123def456...

Never commit API keys to version control! Use environment variables instead.

Step 2: Add Credits to Your Account

All API usage is prepaid. Add credits to your account before making requests:

Go to Billing > Add Credits
Select a credit bundle:
- Starter: 4 credits ($10) - Good for 3-8 videos
- Popular: 11 credits ($25, +1 bonus)
- Power: 22.5 credits ($50, +2.5 bonus)
- Creator: 50 credits ($100, +10 bonus)
Complete payment via Stripe or crypto wallet

Credit Pricing:

Videos: 0.5 - 9 credits per video (based on model, duration, resolution)
Chat/Text: ~0.03 credits per 1,000 tokens ($0.08 per 1K tokens)

Step 3: Install the SDK

npm install openai

pnpm add openai

pip install openai

Yes, you read that right - just install the official OpenAI SDK! Outcry AI is 100% OpenAI-compatible.

Step 4: Set Up Your Environment

Create a .env file (or .env.local for Next.js):

OUTCRY_API_KEY=oc_live_abc123def456...

Security Tip: Never hardcode API keys in your source code. Always use environment variables.

Step 5: Make Your First Request

Generate an Activist Video

import OpenAI from 'openai';

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

async function generateVideo() {
  console.log('Creating video...');

  const video = await client.videos.create({
    model: 'sora-2',
    prompt: 'Activists marching for climate justice with banners',
    seconds: '8',  // STRING: "4", "8", or "12"
    size: '1280x720'  // Resolution in pixels
  });

  console.log(`Video ID: ${video.id}`);
  console.log(`Status: ${video.status}`);

  // Poll for completion
  while (video.status === 'queued' || video.status === 'in_progress') {
    await new Promise(resolve => setTimeout(resolve, 5000)); // Wait 5 seconds

    const updated = await client.videos.retrieve(video.id);
    console.log(`Status: ${updated.status} (${updated.progress}%)`);

    if (updated.status === 'completed') {
      console.log(`Video URL: ${updated.url}`);
      break;
    }

    if (updated.status === 'failed') {
      console.error(`Video failed: ${updated.error}`);
      break;
    }
  }
}

generateVideo();

from openai import OpenAI
import time
import os

# Initialize client - just change the base_url!
client = OpenAI(
    api_key=os.environ.get("OUTCRY_API_KEY"),
    base_url="https://api.outcryai.com/v1"
)

def generate_video():
    print("Creating video...")

    video = client.videos.create(
        model="sora-2",
        prompt="Activists marching for climate justice with banners",
        seconds="8",  # STRING: "4", "8", or "12"
        size="1280x720"  # Resolution in pixels
    )

    print(f"Video ID: {video.id}")
    print(f"Status: {video.status}")

    # Poll for completion
    while video.status in ['queued', 'in_progress']:
        time.sleep(5)  # Wait 5 seconds

        updated = client.videos.retrieve(video.id)
        print(f"Status: {updated.status} ({updated.progress}%)")

        if updated.status == 'completed':
            print(f"Video URL: {updated.url}")
            break

        if updated.status == 'failed':
            print(f"Video failed: {updated.error}")
            break

generate_video()

# Create video
curl https://api.outcryai.com/v1/videos \
  -H "Authorization: Bearer oc_live_abc123def456..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "Activists marching for climate justice with banners",
    "seconds": "8",
    "size": "1280x720"
  }'

# Response:
# {
#   "id": "video_abc123",
#   "object": "video",
#   "created": 1730634060,
#   "model": "sora-2",
#   "status": "queued",
#   "progress": 0,
#   "url": null
# }

# Check status (poll every 5 seconds)
curl https://api.outcryai.com/v1/videos/video_abc123 \
  -H "Authorization: Bearer oc_live_abc123def456..."

# Response when complete:
# {
#   "id": "video_abc123",
#   "object": "video",
#   "created": 1730634060,
#   "model": "sora-2",
#   "status": "completed",
#   "progress": 100,
#   "url": "https://pub-....r2.dev/videos/..."
# }

Notes:

Videos take ~60-90 seconds to generate
seconds must be a STRING (“4”, “8”, or “12”), not a number
size is pixel dimensions, not aspect ratio
Poll every 5 seconds - don’t hammer the API!

Chat with Theory of Change

import OpenAI from 'openai';

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

async function chat() {
  const completion = await client.chat.completions.create({
    model: 'grok-2',
    messages: [
      { role: 'user', content: 'How can I organize a grassroots climate campaign?' }
    ],
    // Optional: Set Theory of Change position
    // @ts-ignore - Custom vendor extension
    'x-theory-position': { x: -0.5, y: -0.3 } // Voluntarist approach
  });

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

chat();

from openai import OpenAI
import os

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

def chat():
    completion = client.chat.completions.create(
        model="grok-2",
        messages=[
            {"role": "user", "content": "How can I organize a grassroots climate campaign?"}
        ],
        # Optional: Set Theory of Change position
        extra_body={
            "x-theory-position": {"x": -0.5, "y": -0.3}  # Voluntarist approach
        }
    )

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

chat()

curl https://api.outcryai.com/v1/chat/completions \
  -H "Authorization: Bearer oc_live_abc123def456..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-2",
    "messages": [
      {"role": "user", "content": "How can I organize a grassroots climate campaign?"}
    ],
    "x-theory-position": {"x": -0.5, "y": -0.3}
  }'

Theory of Change Position:

x axis: -1 (Subjective) to +1 (Objective)
y axis: -1 (Material) to +1 (Spiritual)
Examples:
- {x: -0.8, y: -0.6} - Strong voluntarist (grassroots organizing)
- {x: 0.7, y: -0.5} - Structuralist (policy/systems focus)
- {x: 0, y: 0} - Balanced approach

Learn more in the Theory of Change Guide.

Step 6: Handle Errors Gracefully

Always wrap API calls in try-catch blocks:

try {
  const video = await client.videos.create({
    model: 'sora-2',
    prompt: 'Activist rally',
    seconds: '8',
    size: '1280x720'
  });
  console.log(`Video created: ${video.id}`);
} catch (error: any) {
  if (error.status === 402) {
    console.error('Insufficient credits. Please add more credits to your account.');
  } else if (error.status === 429) {
    console.error('Rate limit exceeded. Please slow down.');
  } else if (error.status === 400) {
    console.error(`Validation error: ${error.message}`);
  } else {
    console.error(`API error: ${error.message}`);
  }
}

try:
    video = client.videos.create(
        model="sora-2",
        prompt="Activist rally",
        seconds="8",
        size="1280x720"
    )
    print(f"Video created: {video.id}")
except Exception as e:
    if hasattr(e, 'status_code'):
        if e.status_code == 402:
            print("Insufficient credits. Please add more credits to your account.")
        elif e.status_code == 429:
            print("Rate limit exceeded. Please slow down.")
        elif e.status_code == 400:
            print(f"Validation error: {e}")
        else:
            print(f"API error: {e}")
    else:
        print(f"Unknown error: {e}")

Common status codes:

400 - Bad request (invalid parameters)
401 - Invalid API key
402 - Insufficient prepaid balance
403 - Missing required scope
429 - Rate limit exceeded
500 - Server error

See the Error Handling Guide for complete details.

Next Steps

Authentication Guide

Learn about API keys, scopes, and security best practices

Video API Reference

Complete documentation for video generation endpoints

Webhooks Guide

Set up real-time notifications for video completions

Theory of Change

Understand how to align AI outputs with your strategy

Production Checklist

Before going to production:

Store API keys in environment variables (never hardcode)
Implement error handling for all API calls
Set up webhooks for video completions (don’t poll)
Add retry logic for transient errors (429, 500)
Monitor your credit balance
Set up alerts for low credit balance
Test rate limiting behavior
Implement exponential backoff for retries

Ready to build? Explore the full API Reference or read the Authentication Guide.

​Quickstart Guide

​Prerequisites

​Step 1: Get Your API Key

​Step 2: Add Credits to Your Account

​Step 3: Install the SDK

​Step 4: Set Up Your Environment

​Step 5: Make Your First Request

​Generate an Activist Video

​Chat with Theory of Change

​Step 6: Handle Errors Gracefully

​Next Steps