Generation
Generate Moment
Create a new historical moment from a text query using Flash Timepoint API
POST
Generate Moment
Overview
The/generate endpoint accepts a natural language query describing a historical event and returns a job ID. The system uses the Flash Timepoint API to generate structured moment data, which is then indexed into the Clockchain graph.
Authentication
RequiresSERVICE_API_KEY header for authentication.
Request Body
string
required
Natural language description of the historical event. Can include date and location hints.Examples:
- “Caesar’s assassination March 15 44 BC Rome”
- “Moon landing 1969”
- “Fall of the Berlin Wall”
string
default:"default"
Flash API preset controlling generation quality and detail level.Available presets:
default- Standard generationbalanced- Balanced quality and speeddetailed- Maximum detail and accuracy
string
default:"private"
Visibility level for the generated moment.Options:
private- Only visible to creatorpublic- Visible to all users
Response
string
Unique identifier for the generation job. Use this with the Get Job endpoint to check status.
string
Current job status. Will be
pending immediately after creation.Possible values:pending- Job created, waiting to processprocessing- Currently generating momentcompleted- Successfully generated and indexedfailed- Generation failed (checkerrorfield)
string
ISO 8601 timestamp when the job was created.
string | null
Graph path where the moment will be indexed. Only available when status is
completed.Format: /YYYY/month/DD/HHMM/country/region/city/event-slugstring | null
Error message if status is
failed. Otherwise null.string | null
ISO 8601 timestamp when job finished (completed or failed).
null while processing.Example Request
Example Response
Content Moderation
If
OPENROUTER_API_KEY is configured, queries are screened by a content judge before processing. Inappropriate queries will be rejected with a 400 error.Job Processing
Generation jobs are processed asynchronously in the background. To check job status and retrieve the generated moment path:- Store the
job_idfrom the response - Poll the Get Job endpoint
- When
statusiscompleted, use thepathto fetch moment details
Error Responses
Related Endpoints
- Get Job - Check job status
- Publish Moment - Change moment visibility
- Bulk Generate - Generate multiple moments