How to generate captions and hashtags with AI ​

Add your own AI provider key to the workspace, then call POST /api/ai/generate-content with the platforms you target. Socifyr returns one caption per platform, written to that platform's length and style. POST /api/ai/suggest-hashtags returns scored hashtags.

AI runs only on your key (bring your own key). There is no shared key, so without one the AI endpoints return 503. Supported providers are OpenAI, Anthropic, Google Gemini, Mistral and xAI.

How do I add my AI key? ​

Use the dashboard (Settings, then the AI section) or REST. See AI composer and BYOK.

curl -X PUT https://api.socifyr.com/api/ai/settings \
  -H "Authorization: Bearer $SOCIFYR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "provider": "anthropic", "apiKey": "sk-ant-..." }'

The key is checked with a live call, stored encrypted and never returned. Changing it needs the workspace.edit permission and an unrestricted key, so agents cannot change it.

Check availability any time:

curl https://api.socifyr.com/api/ai/status -H "Authorization: Bearer $SOCIFYR_API_KEY"
# {"success":true,"data":{"available":true,"source":"byok","model":"gemini-2.5-flash"}}

How do I generate captions? ​

platforms takes platform names such as linkedin and x, not connection slugs.

Add your key under Settings first. Then New Post shows an AI menu in the
composer that generates captions and hashtags for the selected platforms.
Without a key the menu does not appear.

# Generates platform captions from the text, then posts the first one returned.
socifyr post "We added bulk scheduling from CSV" --to linkedin-myhandle,x-myhandle --ai

const { content } = await socifyr.ai.generateContent({
  uploadType: 'text',
  platforms: ['linkedin', 'x'],
  text: 'We added bulk scheduling from CSV.',
  tone: 'professional',
  brandVoice: 'Plain, specific, no hype',
})
console.log(content.linkedin, content.x)

res = client.ai.generate_caption(
    upload_type="text",
    platforms=["linkedin", "x"],
    text="We added bulk scheduling from CSV.",
    tone="professional",
)
print(res["content"]["linkedin"])

curl -X POST https://api.socifyr.com/api/ai/generate-content \
  -H "Authorization: Bearer $SOCIFYR_API_KEY" \
  -H "X-Workspace-Id: $SOCIFYR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "uploadType": "text",
    "platforms": ["linkedin", "x"],
    "text": "We added bulk scheduling from CSV.",
    "tone": "professional"
  }'

{
  "tool": "generate_caption",
  "arguments": {
    "description": "We added bulk scheduling from CSV.",
    "platforms": ["linkedin", "x"],
    "tone": "professional"
  }
}

Prompt for your agent: "Write a LinkedIn and an X caption for our bulk scheduling launch, professional tone, then show me both before posting." The agent calls generate_caption and waits for your answer before post_text.

Response (your text will differ):

{
  "success": true,
  "data": {
    "content": {
      "linkedin": "Bulk scheduling from CSV is live. Upload one file and plan a month of posts in a single step.",
      "x": "Bulk scheduling from CSV is live. Plan a month of posts with one upload."
    }
  }
}

Fields: uploadType (video, photo, text, document) and platforms are required. Optional: text, title, description (each up to 5,000 characters), tone (professional, casual, humorous, inspirational, informative) and brandVoice (up to 1,000 characters). The MCP tool takes description as the brief and has no brandVoice field.

How do I get hashtag suggestions? ​

res = client.ai.suggest_hashtags(text="Bulk scheduling from CSV", platforms=["instagram"], count=5)
print([h["tag"] for h in res["hashtags"]])

curl -X POST https://api.socifyr.com/api/ai/suggest-hashtags \
  -H "Authorization: Bearer $SOCIFYR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Bulk scheduling from CSV", "platforms": ["instagram"], "count": 5 }'

{
  "success": true,
  "data": {
    "hashtags": [
      { "tag": "socialmediatools", "score": 88 },
      { "tag": "contentcalendar", "score": 81 }
    ]
  }
}

count is 1 to 30 and defaults to 10. tag has no #. The TypeScript SDK has ai.suggestHashtags(), but its declared return type does not match this response, so read hashtags from the result loosely. The CLI and MCP have no hashtag command.

What errors can I get, and how do I fix them? ​

FAQ ​

Does Socifyr charge for AI? ​

Calls run on your provider account, so your provider bills you.

Can an agent with guardrails use AI? ​

Yes for generation and hashtags. Settings routes are blocked for guarded keys.

Next steps ​

• AI composer in the dashboard
• Publish a text post
• REST reference: AI
• Build a content agent