Text Generation

Generate chat completions, articles, code, summaries, and more with type: "text" (the default).

Request

POST /api/external/ai
Content-Type: application/json
X-API-Key: your-api-key-here

Simple prompt

{
  "prompt": "Explain machine learning in simple terms",
  "model": "lumo-ai",
  "provider": "deepseek",
  "type": "text",
  "max_tokens": 1000,
  "temperature": 0.7
}

Prompt + system instruction

{
  "system": "You are a concise technical writer.",
  "prompt": "Explain machine learning in simple terms",
  "model": "lumo-ai",
  "type": "text"
}

Chat messages

{
  "type": "text",
  "model": "lumo-ai",
  "messages": [
    { "role": "system", "content": "You are a helpful coding assistant." },
    { "role": "user", "content": "Write a Python hello world." },
    { "role": "assistant", "content": "print(\"Hello, world\")" },
    { "role": "user", "content": "Now add a main guard." }
  ],
  "max_tokens": 500,
  "temperature": 0.2
}

Provide either prompt or a non-empty messages array (or both patterns above). Roles must be system, user, or assistant.

Parameters

Parameter	Type	Default	Description
prompt	string	—	User prompt (required unless messages is provided)
messages	array	—	Chat history; each item { role, content }
system	string	—	Optional system message when using prompt
model	string	—	Required. Model id or name from GET discovery
provider	string	model’s provider	Must match the resolved model provider if set
type	string	text	Must be text for this flow
max_tokens	number	capped	Max output tokens (clamped to model + platform limits)
temperature	number	provider default	Randomness from 0.0 to 2.0
stream	boolean	false	When true, returns SSE if the model supports streaming

Temperature guidance

Use case	Suggested range
Code generation	0.1 – 0.3
Technical writing	0.3 – 0.5
General content	0.5 – 0.8
Creative writing	0.7 – 1.2
Brainstorming	1.0 – 1.5

Streaming (SSE)

Set "stream": true only when the chosen model reports capabilities.streaming: true (or supported_features.streaming is true for your key/catalog).

• Response Content-Type is an SSE stream (OpenAI-style chunk framing for text)
• Token usage is tracked when the stream completes
• Image and embedding requests reject stream: true

Success response (non-stream)

{
  "success": true,
  "data": {
    "content": "Machine learning is a subset of artificial intelligence...",
    "model": "lumo-ai",
    "provider": "deepseek",
    "tokens_used": 150,
    "actual_tokens": 148,
    "cost": 0.0003,
    "remaining_tokens": 9850,
    "usage_percentage": "1.5"
  }
}

Field	Description
content	Generated text
tokens_used	Tokens deducted from your balance
actual_tokens	Provider-reported token usage when available
remaining_tokens	Balance after this request
usage_percentage	Percent of plan/credit usage consumed

Example prompts

Creative writing

{
  "prompt": "Write a short story about a robot discovering emotions",
  "model": "lumo-ai",
  "provider": "deepseek",
  "type": "text",
  "max_tokens": 1500,
  "temperature": 0.9
}

Code generation

{
  "prompt": "Create a Python function to calculate the Fibonacci sequence",
  "model": "lumo-ai",
  "provider": "deepseek",
  "type": "text",
  "max_tokens": 500,
  "temperature": 0.1
}

Summarization

{
  "prompt": "Summarize the key benefits of renewable energy in 3 bullet points",
  "model": "lumo-ai",
  "provider": "deepseek",
  "type": "text",
  "max_tokens": 200,
  "temperature": 0.3
}

Replace example model names with values from your live GET response.

Requirements

• Valid API key (pk_…)
• Sufficient remaining tokens/credits
• Provider available and allowed on your API key
• Model available and allowed on your API key

If tokens are insufficient, the API returns 402 with required vs remaining token details.