n8n

n8n Integration

Use Soke with n8n to build visual content optimization workflows. This guide covers credential setup, working with Soke's API response format, and includes ready-to-import workflow templates for every major Soke feature.

What you can build

• Keyword research pipelines — automatically research keywords on a schedule and push results to Google Sheets, Notion, or Airtable
• Content optimization workflows — chain keyword research → title optimization → description generation into a single automated pipeline
• Async job monitoring — generate thumbnails or transcribe videos with automatic polling until completion
• Chat-powered automation — use Soke's OpenAI-compatible chat endpoint to handle complex, multi-step content tasks in a single request

Prerequisites

• n8n — self-hosted or n8n Cloud
• Soke API key — get one from your Soke dashboard

Credential Setup

{
  "topic": "test",
  "platform": "youtube"
}

Understanding Soke Responses in n8n

Every Soke API response follows a standard envelope:

{
  "success": true,
  "data": { /* endpoint-specific results */ },
  "meta": {
    "platform": "youtube",
    "request_id": "uuid",
    "processing_time_ms": 142
  }
}

Accessing data in expressions

In n8n expressions, access nested response fields like this:

Error handling

Always check the success field before processing results. Add an IF node after each HTTP Request:

• Condition: {{ $json.success }} equals true
• True branch: continue processing
• False branch: log {{ $json.error.code }} and {{ $json.error.message }}

Workflow: Keyword Research

Research keywords for any topic and extract structured results.

{
  "topic": "productivity tips for developers",
  "platform": "youtube",
  "maxResults": 20
}

{
  "keywords": "{{ $json.data.keywords.map(k => k.keyword) }}",
  "topKeyword": "{{ $json.data.keywords[0]?.keyword }}",
  "keywordsWithScores": "{{ $json.data.keywords.slice(0, 5).map(k => ({ keyword: k.keyword, score: k.competitionScore, trend: k.trendDirection })) }}",
  "longTailPhrases": "{{ $json.data.longTailPhrases }}"
}

Workflow: Content Optimization Pipeline

Chain multiple Soke endpoints to go from a topic to fully optimized content in one workflow.

Pipeline flow: Keyword Research → Title Optimization → Description Generation

Total credits: 8 per run (2 + 3 + 3)

{
  "topic": "{{ $json.topic }}",
  "platform": "youtube",
  "maxResults": 10
}

{
  "draftTitle": "{{ $json.draftTitle || 'How to boost productivity as a developer' }}",
  "platform": "youtube",
  "keywords": "{{ $('1. Research Keywords').item.json.data.keywords.slice(0, 5).map(k => k.keyword) }}",
  "keywordsWithScores": "{{ $('1. Research Keywords').item.json.data.keywords.slice(0, 5).map(k => ({ keyword: k.keyword, competitionScore: k.competitionScore, trendDirection: k.trendDirection })) }}"
}

{
  "title": "{{ $json.data.alternatives[0]?.title }}",
  "platform": "youtube",
  "keywords": "{{ $('1. Research Keywords').item.json.data.keywords.slice(0, 5).map(k => k.keyword) }}",
  "niche": "tech",
  "tone": "casual"
}

{
  "optimizedTitle": "{{ $('2. Optimize Title').item.json.data.alternatives[0]?.title }}",
  "titleScore": "{{ $('2. Optimize Title').item.json.data.alternatives[0]?.overallScore }}",
  "description": "{{ $json.data.description }}",
  "keywords": "{{ $('1. Research Keywords').item.json.data.keywords.slice(0, 5).map(k => k.keyword) }}",
  "creditsUsed": 8
}

Workflow: Content Scoring

Score a title or caption to see how well it's optimized.

Configure an HTTP Request node:

• Method: POST
• URL: https://api.usesoke.ai/api/v1/content/score
• Body:

{
  "content": "10 Developer Productivity Hacks That Actually Work",
  "platform": "youtube",
  "targetKeywords": ["developer productivity", "coding tips"]
}

The response includes an overallScore (0–100) and a breakdown object with individual scores for keyword placement, emotional pull, curiosity gap, hook strength, and more. Each dimension includes a suggestion field when improvement is possible.

Key expressions for downstream nodes:

Workflow: Async Operations (Thumbnails & Transcription)

Thumbnail generation and transcription are async operations — they return immediately with a job ID, and you poll for results. Here's the pattern:

The polling loop pattern

Start Job → Wait → Poll Status → Is Completed?
                                    ├─ Yes → Process Results
                                    └─ No  → Wait & Retry (loops back to Poll)

{
  "manualTitle": "10 Developer Productivity Hacks",
  "manualPrompt": "A developer at a clean desk with multiple monitors showing code",
  "templateId": "your-template-id",
  "platform": "youtube"
}

{
  "manualTitle": "10 Developer Productivity Hacks",
  "manualPrompt": "A developer at a clean desk with multiple monitors showing code",
  "colorGrading": "Cinematic",
  "layoutType": "TextCenter",
  "resolution": "1280x720",
  "platform": "youtube"
}

Workflow: Chat Completions

Use Soke's OpenAI-compatible chat endpoint for natural language content tasks. The chat endpoint automatically orchestrates multiple services (keyword research, title optimization, etc.) based on your prompt.

• Method: POST
• URL: https://api.usesoke.ai/api/v1/chat/completions
• Body:

{
  "messages": [
    {
      "role": "user",
      "content": "Research keywords for cooking tutorials and suggest 3 optimized titles"
    }
  ],
  "platform": "youtube",
  "model": "soke-v1",
  "stream": false
}

Response structure:

Downloadable Workflows

Import these directly into n8n via Workflow → Import from File.

Error Handling & Tips

Rate limit handling

If you hit a rate limit (429 status), the response includes a Retry-After header. Add an error handling branch:

1. After each HTTP Request node, check {{ $json.success }}
2. If false and {{ $json.error.code }} is RATE_LIMIT_EXCEEDED, add a Wait node for {{ $json.error.details.retryAfter }} seconds
3. Then retry the request

Credit monitoring

Add a credit check at the start of expensive workflows:

GET https://api.usesoke.ai/api/v1/credits/balance

Use an IF node to check {{ $json.data.currentBalance }} is sufficient before proceeding.

Common pitfalls

• Missing platform field — most endpoints default to "youtube", but it's best to always include it explicitly
• Async polling too fast — don't poll more frequently than every 3 seconds. The downloadable workflows use 5–10 second intervals
• Large topic strings — the topic field has a 200-character limit. Use concise, keyword-focused topics
• Expression syntax — n8n expressions use {{ }} double braces. For complex JavaScript, use {{ }} with standard JS inside (e.g., {{ $json.data.keywords.map(k => k.keyword).join(', ') }})

Scheduling workflows

Replace the Manual Trigger with a Schedule Trigger for automated runs:

• Daily keyword research — run once per day to track keyword trends
• Weekly competitor monitoring — check competitor channels weekly
• Hourly trend scanning — catch trending topics early