POST /v1/generateStructured outputsValidation + retries

Quickstart

Make your first request and get schema-valid structured outputs.

1) Get an API key

Create a key in Console, then pass it via x-api-key.

curl -X POST https://oneai-saas-api-production.up.railway.app/v1/generate \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_KEY" \
  -H "Idempotency-Key: launch-plan-001" \
  -d '{
    "type": "agent_plan",
    "input": { "goal": "Create a launch plan for OneAI API" },
    "options": { "llm": { "mode": "cheap", "maxCostUsd": 0.02 } }
  }'

Get API key →Generate reference →Chat reference →

2) Understand the response

The API returns structured data plus requestId, usage, and model trace metadata when debug is enabled.

Success

{
  "success": true,
  "requestId": "req_...",
  "data": { ...schema-valid output... },
  "usage": { "provider": "openai", "model": "gpt-4o-mini" },
  "attempts": 1
}

Failure

{
  "success": false,
  "error": "Failed to produce valid structured output",
  "details": { "code":"VALIDATION_FAILED", "issues":[...] }
}

3) Use the model gateway

For OpenAI-compatible integrations, call /v1/chat/completions with Authorization: Bearer.

curl -s https://oneai-saas-api-production.up.railway.app/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_KEY" \
  -d '{
    "model": "openai:gpt-5.2",
    "messages": [
      { "role": "user", "content": "Explain OneAI SaaS in one sentence." }
    ],
    "max_completion_tokens": 300
  }'

Docs Home

API Basics