AI captions and hashtags with your own key
Socifyr generates captions and hashtags with a key you provide, called bring your own key (BYOK). You add a provider key once in Settings. After that, the composer shows an AI menu, and the CLI, SDK, and MCP server can generate captions too. Socifyr does not meter the usage. Your provider bills you directly.
AI is off until a key is set. Without one, the AI menu does not appear in the composer.
How do I add my own AI key to Socifyr?
- Open Settings and find the card "AI - bring your own key". You need
workspace.edit(Owner or Admin). Others see "No AI key configured. A workspace admin can add one." - Choose a Provider.
- Choose a Model from the list, or type a Custom model name for anything newer.
- Paste the provider API key. The Get a key link opens the provider's key page.
- Click Save key.
Socifyr runs a short live test call with the key and model before saving, so a wrong key or unavailable model fails right away with a message. The key is stored encrypted and is never shown again. When a key is set, the card says "<Provider> key configured" and "AI runs on your own account - we don't meter it." Click Remove to delete it.
Which AI providers are supported?
| Provider | Default model | Where to get a key |
|---|---|---|
| OpenAI | gpt-5 | platform.openai.com/api-keys |
| Anthropic (Claude) | claude-sonnet-5 | console.anthropic.com/settings/keys |
| Google Gemini | gemini-2.5-flash | aistudio.google.com/apikey |
| Mistral | mistral-large-latest | Mistral console |
| xAI (Grok) | grok-4-latest | xAI console |
The model list in the dropdown is a suggestion. Use the custom field for any model your key can access.
How do I generate a caption in the composer?
- Select at least one account first. AI tailors the caption to the platforms you pick. Without one you get "Select at least one account first".
- Click AI in the bottom bar.
- Choose Generate caption (or Rewrite caption if the editor already has text).
- The caption replaces the editor text and a toast says "Caption generated".
The composer uses the first selected platform's version. Existing text, title, and description are sent as context, so write a rough draft first to steer it.
How do I add hashtags with AI?
Write a caption, select accounts, then choose AI, Suggest hashtags. Socifyr appends the tags to the end of your caption and toasts "Added N hashtags". An empty caption gives "Write a caption first".
Who can use AI?
Anyone with ai.use: Owner, Admin, Editor, and Contributor. Setting or removing the key needs workspace.edit. API keys with guardrails can still call the AI endpoints.
How do I use AI from code?
| Surface | How |
|---|---|
| CLI | socifyr post --ai generates platform-specific captions while posting (CLI post) |
| TypeScript SDK | socifyr.ai.status(), socifyr.ai.generateContent(), socifyr.ai.suggestHashtags() |
| Python SDK | generate_caption(...) and suggest_hashtags(...) on the ai resource |
| MCP | generate_caption with description, platforms, and optional tone |
| REST | GET /api/ai/status, POST /api/ai/generate-content, POST /api/ai/suggest-hashtags |
The generate request takes uploadType (video, photo, text, or document), a non-empty platforms array such as ["instagram","x"], and optional text, title, description (each up to 5,000 characters), tone (professional, casual, humorous, inspirational, or informative), and brandVoice (up to 1,000 characters). The composer does not expose tone or brand voice, but the API, SDK, and MCP do. The AI endpoints allow 10 requests per minute.
curl -X POST https://api.socifyr.com/api/ai/generate-content \
-H "Authorization: Bearer sk_YOUR_KEY" \
-H "X-Workspace-Id: YOUR_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{"uploadType":"text","platforms":["linkedin","x"],"description":"We shipped bulk CSV scheduling","tone":"professional"}'The response is {"success":true,"data":{"content":{"linkedin":"...","x":"..."}}}, one caption per platform.
Common problems
| Symptom | Fix |
|---|---|
| No AI menu in the composer | No key is set, or your role lacks ai.use. Add a key in Settings. |
| Key rejected on save | The key is invalid, over quota, or the model is not available to it. Try the provider's default model. |
| 429 from the AI endpoints | Wait a minute. The limit is 10 requests per minute. |
| Caption ignores your style | Use the API or MCP tone and brandVoice, or edit the draft before rewriting. |