Chat Completions

OpenAI-compatible chat endpoint that orchestrates multiple Soke services via natural language.

POST /api/v1/chat/completions

An OpenAI-compatible chat completions endpoint that understands content optimization intents. Send natural language messages and Soke automatically routes to the right services (keyword research, title optimization, etc.) and synthesizes the results.

Credits: 5 per request

Authentication

This endpoint accepts both API key and JWT authentication:

API Key (X-Soke-Key): Stateless — no conversation history
JWT (Authorization: Bearer): Conversations are persisted and accessible from the dashboard

Request Body

Field	Type	Required	Default	Description
`messages`	object[]	Yes	—	Array of chat messages
`messages[].role`	string	Yes	—	`"user"` or `"assistant"`
`messages[].content`	string	Yes	—	Message content
`platform`	string	No	`"youtube"`	Target platform
`model`	string	No	`"soke-v1"`	Model to use
`conversationId`	string	No	—	Resume an existing conversation (JWT only)
`connectionId`	string	No	—	Connected platform account for personalized analytics
`stream`	boolean	No	`false`	Enable Server-Sent Events streaming

Non-Streaming Example

curl -X POST https://api.usesoke.ai/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-Soke-Key: sk_live_your_api_key" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Research keywords for developer productivity and suggest 5 optimized titles"
      }
    ],
    "platform": "youtube"
  }'

Non-Streaming Response

200 OK

{
  "id": "chatcmpl-550e8400-e29b-41d4-a716-446655440000",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "soke-v1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "I researched keywords for 'developer productivity' and found several high-opportunity terms. Based on these, here are 5 optimized title suggestions...",
        "data": {
          "services_used": ["keyword_research", "title_optimize"],
          "results": {
            "keyword_research": {
              "keywords": [...]
            },
            "title_optimize": {
              "alternatives": [...]
            }
          }
        }
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0
  },
  "conversation_id": "guid-if-jwt-auth"
}

Streaming Example

curl -X POST https://api.usesoke.ai/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-Soke-Key: sk_live_your_api_key" \
  -d '{
    "messages": [
      {"role": "user", "content": "Analyze keywords for cooking tutorials"}
    ],
    "stream": true
  }'

Streaming Response (SSE)

Events are sent in this order:

1. Thinking events — Show which services are being used:

data: {"type": "thinking", "step": "keyword_research", "content": "Researching keywords for cooking tutorials..."}

2. Data events — Raw results from each service:

data: {"type": "data", "service": "keyword_research", "result": {"keywords": [...]}}

3. Content events — Streamed natural language synthesis:

data: {"type": "content", "content": "Based on my"}
data: {"type": "content", "content": " research, here are"}

4. Done event — Final metadata:

data: {"type": "done", "services_used": ["keyword_research"], "conversation_id": "uuid", "usage": {...}}

5. Stream end:

data: [DONE]

Supported Intents

The chat engine automatically detects these intents from natural language:

Intent	Triggered By	Service Used
`keyword_research`	"research keywords for...", "find keywords about..."	Keyword Research
`title_optimize`	"optimize this title...", "suggest titles for..."	Title Optimization
`title_score`	"score this title...", "rate my title..."	Content Scoring
`description_generate`	"write a description for...", "generate description..."	Description Generation
`tags_suggest`	"suggest tags for...", "what tags should I use..."	Tag Suggestions
`trend_scan`	"what's trending in...", "scan trends for..."	Trend Scanning
`competitor_analyze`	"analyze this channel...", "competitor analysis for..."	Competitor Analysis
`repurpose`	"repurpose this for...", "convert to TikTok..."	Content Repurposing

Multiple intents can be triggered in a single message (e.g., "Research keywords for X and suggest 5 titles").

Error Codes

Code	Status	Description
`BAD_REQUEST`	400	Missing or empty `messages` array
`RATE_LIMIT_EXCEEDED`	429	Rate limit exceeded
`INSUFFICIENT_CREDITS`	402	Not enough credits
`PLATFORM_NOT_IMPLEMENTED`	501	Platform not yet supported

When using JWT auth, pass conversationId to continue a previous conversation. The full message history is loaded from the server — you don't need to re-send previous messages.

On this page