Generate

Base path: /v1/ai/generate

All endpoints require the api-key header. See Authentication.

Generate text

POST /v1/ai/generate/text

curl https://api.tryranktune.com/v1/ai/generate/text \
  -H "api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5","text":"Write a short product intro."}'

Field	Type	Required	Description
`model`	string	Yes	Model to use
`text`	string	Yes	Prompt
`useWorker`	boolean	No	Queue the job instead of running inline
`options`	object	No	Options for the worker payload
`jobType`	string	No	Job name when queuing (default `ai_tool_content`)

When useWorker is true, the API returns 202:

{ "message": "Content generation queued", "jobId": "123" }

Poll with Async jobs.

Generate Agent message

POST /v1/ai/generate/chat

Field	Type	Description
`model`	string	Model to use
`text`	string	User message
`sessionId`	string	Existing Agent session id (when continuing a thread)

Session CRUD lives under Agent.

Agent workspace context

GET /v1/ai/generate/assistant/context

Returns a summary of workspace context available to Ranktune Agent (visibility, traffic, documents, and related signals).

AI traffic stats (generate alias)

GET /v1/ai/generate/ai-traffic

Convenience alias for traffic stats. Prefer the dedicated AI traffic routes for site management.

Generate image

POST /v1/ai/generate/image

Generate images with OpenAI GPT Image models (gpt-image-1 by default). The API uploads the result and returns a hosted URL when S3 is configured.

Field	Type	Required	Description
`text`	string	Yes	Image prompt
`model`	string	No	`gpt-image-1` (default), `gpt-image-1-mini`, `gpt-image-1.5`, or `gpt-image-2`
`size`	string	No	`1024x1024`, `1536x1024`, `1024x1536`, or `auto`
`quality`	string	No	`low`, `medium`, `high` (default), or `auto`
`purpose`	string	No	Preset: `linkedin`, `blog`, `square`, or `portrait` (sets size/quality defaults)

curl https://api.tryranktune.com/v1/ai/generate/image \
  -H "api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Minimal product hero illustration for a SaaS blog","purpose":"blog"}'

{
  "message": "Generated image successfully.",
  "data": {
    "url": "https://…/uploads/ai-image-….png",
    "model": "gpt-image-1",
    "size": "1536x1024",
    "quality": "high",
    "purpose": "blog"
  }
}

Each successful request counts toward monthly AI credits.

Brand voice from website

POST /v1/ai/generate/brand-voice/website

Field	Type	Description
`websiteurl`	string	HTTPS URL to analyze
`name`	string	Optional display name
`fetchInterval`	string	Optional refresh interval
`scope`	string	`team` (default) or `personal`

{
  "message": "Brand voice created successfully.",
  "data": {
    "id": "...",
    "name": "Brand Voice - 7/9/2026",
    "url": "https://example.com",
    "contentLength": 12000,
    "type": "website"
  }
}

Brand voice from text

POST /v1/ai/generate/brand-voice/text

Field	Type	Description
`content`	string	Source text
`name`	string	Optional name
`scope`	string	`team` or `personal`

Brand voice from file URL

POST /v1/ai/generate/brand-voice/file

Field	Type	Description
`file`	string	URL to a `.md`, `.txt`, `.html`, or `.json` file
`name`	string	Optional name
`scope`	string	`team` or `personal`

Manage existing voices with Brand voice.

SEO visibility report

Visibility report endpoints are documented on AI visibility:

POST /v1/ai/generate/seo-site-report
POST /v1/ai/generate/seo-site-report/prefill
GET /v1/ai/generate/seo-site-report
GET /v1/ai/generate/seo-site-report/one-off
GET /v1/ai/generate/seo-site-report/one-off/:id
GET /v1/ai/generate/seo-site-report/history

Calculate SEO score

POST /v1/ai/generate/calculate-seo-score

Field	Type	Description
`content`	string	Required body text
`title`	string	Optional title
`keywords`	string[]	Optional keywords
`autoExtractKeywords`	boolean	Extract keywords when none are provided (default `true`)

Improve content

POST /v1/ai/generate/improve-content-with-validation — improve content and return validation/SEO signals.

POST /v1/ai/generate/improve-content-simple

Field	Type	Description
`content`	string	Original content
`improvePrompt`	string	Instructions for the improvement
`metricType`	string	Optional metric label

Feedback

POST /v1/ai/generate/feedback

Submit feedback on a generation result (used by the product UI; include the identifiers your client already sends).