---
title: "Generate text using AI"
method: POST
path: "/api/ai/{project_id}/text"
tags: ["AI"]
---

# Generate text using AI

`POST /api/ai/{project_id}/text`

## Request

- Base URL: `https://core.blink.new`
- URL: `https://core.blink.new/api/ai/{project_id}/text`
- Auth: HTTP bearer

Generate text using large language models. Set `stream: true` for a streaming data stream compatible with the `useChat` hook. Set `search: true` to enable real-time web search with any model; the pages used are returned in `sources`. Include image URLs in `messages` content for multimodal input.

## Path parameters

- `project_id` string, required

## Request body

- TextGenerationRequest: Request for text generation. Either prompt or messages is required.
  - `model` string: AI model to use
  - `prompt` string: Text prompt for generation (alternative to messages)
  - `messages` Message[]: Array of messages for conversation-based generation. Supports both text-only and multimodal content.
    - `role` 'system' | 'user' | 'assistant', required: Message role
    - `content` union, required: Message content - either simple text or array of content items for multimodal support
      - string: Simple text content (legacy format)
      - MessageContent[]: Array of content items (multimodal format)
        - union
          - TextContent
            - `type` 'text', required: Content type identifier
            - `text` string, required: Text content
          - ImageContent
            - `type` 'image', required: Content type identifier
            - `image` string, uri, required: HTTPS URL to image. Supported formats: JPEG, PNG, GIF, WebP
  - `stream` boolean: Enable streaming response. When true, returns data stream format instead of JSON.
  - `search` boolean: Enable web search using OpenAI's native web search tool. Only works with OpenAI models (gpt-*, o1-*, o3-*). Gracefully ignored for non-OpenAI models.
  - `maxSteps` integer: Maximum number of sequential LLM calls (steps) for tool usage. Automatically set to 25 when tools are present, but can be overridden. Default is 1 when no tools are used.
  - `experimental_continueSteps` boolean: Enable continue steps for multi-step tool usage. Automatically set to true when tools are present, but can be overridden. Default is false when no tools are used.
  - `maxTokens` integer: Maximum number of tokens to generate
  - `temperature` number: Sampling temperature (0.0 to 2.0)
  - `topP` number: Nucleus sampling parameter
  - `frequencyPenalty` number: Frequency penalty (-2.0 to 2.0)
  - `presencePenalty` number: Presence penalty (-2.0 to 2.0)
  - `stop` union: Stop sequences
    - string
    - string[]

## Response `200`

Text generation successful

- TextGenerationResponse
  - `result` object: The response data
    - `text` string: Generated text content
    - `files` object[]: Associated files (if any)
    - `reasoningDetails` object[]: Reasoning process details
    - `toolCalls` object[]: Tool calls made during generation
    - `toolResults` object[]: Results from tool calls
    - `finishReason` 'stop' | 'length' | 'content_filter' | 'tool_calls': Reason why generation finished
    - `usage` object
      - `promptTokens` integer: Number of tokens in the prompt
      - `completionTokens` integer: Number of tokens in the completion
      - `totalTokens` integer: Total number of tokens used
    - `warnings` string[]: Any warnings from the generation process
    - `request` object
      - `body` string: Original request body as JSON string
    - `response` object: Full response metadata from the AI provider
    - `steps` object[]: Generation steps (for multi-step processes)
      - `stepType` string
      - `text` string: Generated text for this step
      - `finishReason` string
      - `usage` TokenUsage
        - `promptTokens` integer: Number of tokens in the prompt
        - `completionTokens` integer: Number of tokens in the completion
        - `totalTokens` integer: Total number of tokens used
    - `sources` object[]: Source materials used
    - `providerMetadata` object: Provider-specific metadata
    - `experimental_providerMetadata` object: Experimental provider metadata
  - `metadata` object
    - `projectId` string: Project identifier
    - `timestamp` string, date-time: Response timestamp
    - `provider` 'google-gemini' | 'openai': AI provider used for generation

## Other responses

- `400`: Invalid request (`VALIDATION_FAILED`, `INVALID_PROJECT_ID`, `INVALID_ARGUMENTS`), or, when zero data retention is enabled for AI requests, the model cannot run under it (`MODEL_NOT_ZDR_ELIGIBLE`).
- `401`: Authentication required or invalid API key
- `500`: Internal server error

---

[API](https://skmtc.dev/blink/apis/blink-apis.md) - [All operations](https://skmtc.dev/blink/apis/blink-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/blink/apis/blink-apis/revisions/4c59c706078e?raw)