OpenAI API

OpenAI API

This connector calls the OpenAI API (https://api.openai.com/v1) with the user's own API key: answers from OpenAI models through the Responses API (text, pictures by link, conversations, web search, structured output), image generation and editing with the GPT image models, embeddings, moderation, the model list, files and Batch API jobs.

Every model call is billed to the user's OpenAI account (moderation is free; the model, file and batch lists cost nothing). Prefer the cheap defaults unless the user asks for more.

Setup (about 3 minutes)

1. Sign in at https://platform.openai.com and add credit under Settings, Billing (the API is prepaid and separate from a ChatGPT subscription).
2. Open https://platform.openai.com/api-keys, click Create new secret key, pick the project, and copy the key (it starts with sk-; it is shown only once).
3. Paste it into OPENAI_API_KEY and install the connector. It is sent as Authorization: Bearer and only to OpenAI.
4. Optional: OPENAI_ORGANIZATION (org-...) and OPENAI_PROJECT (proj_...) when the user belongs to several organizations or wants usage counted on a specific project. Leave them empty otherwise; a value that does not match the key is refused with 401.
5. For the GPT image models OpenAI requires a verified organization: Settings, Organization, General, Verify Organization. Without it the image tools answer 403.

Defaults (cheap and fast)

• Text: gpt-6-luna (about $0.10 per million input tokens and $0.50 per million output tokens). gpt-6.1-sol and gpt-6-astra are stronger and 20 to 100 times the price.
• Images: gpt-image-1-mini at medium quality, 1024x1024, JPEG (about $0.01 per picture). gpt-image-2.5-flare and gpt-image-2.5-sunburst are the newest models.
• Embeddings: text-embedding-3-small with 256 dimensions. Moderation: omni-moderation-latest.
• Model ids change often: openai_list_models shows what the key can use.

Tools

• openai_create_response: one call of the Responses API. input is a prompt string or a list of items; pictures go in as {"type": "input_image", "image_url": "https://...", "detail": "auto"} inside a user message. instructions sets the behaviour, reasoning the effort of reasoning models ({"effort": "low"} is cheaper), text the output format (JSON schema), tools: [{"type": "web_search"}] adds web search (billed per search). Responses are not stored at OpenAI unless store is true; only stored responses can be continued with previous_response_id.
• openai_generate_image and openai_edit_image: pictures returned as images in the chat. Each picture costs money: confirm with the user before every call, and keep n at 1 unless they ask for more. A client that cannot show images still gets the text part with the size and type of each picture. Pictures over 4 MB are not returned; use JPEG or WebP, or a smaller size. Edits take pictures by public link or file id (images), plus an optional mask.
• openai_create_embeddings: vectors for one text or up to 20 texts.
• openai_moderate: content policy check of text and pictures.
• openai_list_models, openai_get_model: what the key can use.
• openai_list_files, openai_get_file, openai_delete_file: files in the account (no upload or download here). openai_delete_file is installed switched off.
• openai_list_batches, openai_get_batch: status of Batch API jobs started elsewhere.

Reading answers: output_text is the answer. status incomplete with incomplete_details.reason max_output_tokens means it was cut (raise max_output_tokens, which includes reasoning tokens). refusal holds the model's refusal text when it declined. An answer stopped by OpenAI's content filter comes back as an error: do not retry the same request.

Common errors

• 401: the key is wrong or revoked, or OPENAI_ORGANIZATION / OPENAI_PROJECT do not match it.
• 403: the organization is not verified (GPT image models), or the model or region is not available to it.
• 404 model_not_found: check openai_list_models.
• 429 insufficient_quota: no credit left or the spending limit is reached; add credit. 429 rate_limit_exceeded: wait and retry once. Do not retry in a loop.
• 400 moderation_blocked or content_policy_violation: the safety system refused the prompt.

Out of scope here: chat completions (the Responses API covers it), audio (speech, transcription), realtime, video, file upload and download, creating batches, fine-tuning, vector stores, assistants and the admin API.