Help agents with Response shapes

[alexanderatallah]

This pull request updates documentation for the OpenRouter skills, focusing on clarifying API response formats, improving usage examples, and adding helpful references. The main changes enhance developer understanding of API shapes, usage patterns, and available documentation resources.

API Response and Output Format Documentation:

• Added a new "API Response Shapes" section to skills/openrouter-images/SKILL.md, detailing the structure of image generation responses, including the image_generation_call output item type and its usage alongside standard message outputs.
• Expanded the "API Response Shapes" section in skills/openrouter-models/SKILL.md to explain the structure and fields returned by the models API, provide tips for working with the response, and clarify the differences between raw API fields and script output formats.

Code Example and Usage Improvements:

• Updated the example API call in skills/openrouter-oauth/SKILL.md to use the correct endpoint (/api/v1/responses) and payload shape (using input instead of messages) for chat completions, ensuring consistency with the latest API.

Documentation Resource Additions:

• Added a link to the API authentication guide in the resources section of skills/openrouter-oauth/SKILL.md for easier access to API key and Bearer token setup documentation.

[perry-the-pr-reviewer]

Perry's Review

Adds API response shape documentation to the images, models, and oauth skills — the images section documents the wrong endpoint and output format, and the oauth example uses an incorrect input array shape for the Responses API.

Verdict: 🔁 Needs changes

Details

CI: no CI configured on this branch

Findings (see inline comments for full context):

• 🔴 skills/openrouter-images/SKILL.md:100 — Documents /api/v1/responses + image_generation_call but actual scripts use /api/v1/chat/completions + message.images
• 🔴 skills/openrouter-oauth/SKILL.md:200 — Changed example to /api/v1/responses but the endpoint has a different input array schema than what's shown
• 🔴 skills/openrouter-oauth/SKILL.md:208 — input: [{ role, content }] is the Chat Completions messages shape; Responses API requires type:"message" + content:[{type:"input_text",text:...}]

Codex (openai/gpt-5.4): confirmed the images endpoint/shape mismatch; also surfaced pre-existing issues in compare-models and list-models (outside this PR's scope — separate concerns)

Research:

• Confirmed via OpenRouter Responses API Basic Usage: input array requires {type:"message", role, content:[{type:"input_text",text:...}]}, not bare {role, content}
• Confirmed via skills/openrouter-images/scripts/lib.ts and generate.ts: actual image generation calls go to /api/v1/chat/completions and read choices[0].message.images[], not output[].type==image_generation_call
• image_generation_call is an OpenAI Responses API item type; OpenRouter images use the Chat Completions message.images extension
• links.details field confirmed valid in OpenRouter OpenAPI spec
• model.architecture.input_modalities / output_modalities field names confirmed via scripts (search-models.ts uses these)

Test coverage: docs-only PR, no tests

Unresolved threads: none

Superseded by updated Perry review

[perry-the-pr-reviewer]

Perry's Review

Adds API response shape documentation to the images, models, and OAuth skills.

Verdict: 🔁 Needs changes

Details

CI: no checks configured on this branch

Findings (see inline comments for full context):

• 🔴 skills/openrouter-images/SKILL.md:100 — Documents /api/v1/responses + image_generation_call but actual scripts use /api/v1/chat/completions + choices[0].message.images
• 🔴 skills/openrouter-oauth/SKILL.md:200 — Switched to /api/v1/responses but uses incorrect input array format (missing type: "message", content must be [{type: "input_text", text}] not a string)

Codex (openai/gpt-5.4): confirmed the images endpoint/shape mismatch; also surfaced several pre-existing issues outside the PR diff (compare-models sort labelling, OAuth key-validation, replaceState hash stripping) — not blocking this PR but worth filing separately

Research:

• Confirmed via OpenRouter Responses API Basic Usage docs: structured array input requires {type: "message", role, content: [{type: "input_text", text}]} — bare {role, content} object is not a valid item type
• Confirmed via skills/openrouter-images/scripts/lib.ts:47 and generate.ts: images use POST /api/v1/chat/completions and parse choices[0].message.images[], not output[].image_generation_call
• OpenRouter docs confirm image generation works on both Chat Completions and Responses APIs — image_generation_call is valid for the Responses API path, but the bundled scripts only use Chat Completions
• { data: Model[] } wrapper, query params table, links.details → /models/{author}/{slug}/endpoints → { data: { id, name, endpoints } }, and endpoint status 0 = operational all confirmed accurate via OpenAPI spec and scripts

Test coverage: documentation-only PR; no runnable tests possible

Unresolved threads: none

Superseded by updated Perry review

[perry-the-pr-reviewer]

Perry's Review

Adds API response shape documentation to the images, models, and OAuth skills — good direction for helping agents understand the API surfaces they're calling.

Verdict: 🔁 Needs changes

Details

CI: no checks configured on this branch

Findings (see inline comments for full context):

• 🔴 skills/openrouter-images/SKILL.md:100 — Section documents /api/v1/responses + image_generation_call but the bundled scripts use /api/v1/chat/completions and parse choices[0].message.images[]
• 🟡 skills/openrouter-oauth/SKILL.md:208 — content: "Hello!" is a bare string; Responses API structured array format expects content as a typed-parts array

Codex (openai/gpt-5.4): no output (sandbox restriction)

Research:

• Confirmed via skills/openrouter-images/scripts/lib.ts:47: image scripts POST to /api/v1/chat/completions via postChatCompletion(), not /api/v1/responses
• Confirmed via generate.ts:34–43: response parsed as json.choices[0].message.images[] — image_generation_call does not appear here; that shape is from OpenAI's Responses API for GPT Image models
• OpenRouter docs + web search confirm images via Chat Completions return message.images[].image_url.url (data URL), not an output[] array
• Responses API Basic Usage docs: structured array input requires {type: "message", role, content: [{type: "input_text", text}]}; bare string content may work via server leniency but is not the documented contract
• Models SKILL additions ({ data: Model[] } wrapper, query params, tips, endpoints shape) all verified accurate against OpenAPI spec and scripts

Test coverage: documentation-only PR; no runnable tests applicable

Unresolved threads from prior review: the type: "message" thread (from commit beb8667) was addressed in 3f43be6 ✅ — residual: content string vs typed-parts array (see inline)

[perry-the-pr-reviewer]

Perry's Review

Adds { data: Model[] } and { data: { id, name, endpoints: Endpoint[] } } response shape documentation to the models skill, clarifies formatModel() drop list, and updates the OAuth skill example to use the Responses API with type: "message" — all accurate and helpful for agent callers.

Verdict: 🔁 Needs changes

Details

CI: no checks configured on this branch

Findings (see inline comments for full context):

• 🟡 skills/openrouter-oauth/SKILL.md:208 — content: "Hello!" is a bare string; Responses API structured array format requires a typed-parts array per spec

Codex (openai/gpt-5.4): 8 findings surfaced — 7 are pre-existing (not introduced by this PR's diff): localStorage key storage security, --sort throughput sorting by max_completion_tokens vs actual throughput, compare-models.ts partial-match fallback undocumented, handleOAuthCallback verifier deletion before exchange confirmation, history.replaceState dropping deep-link params, missing URL cleanup after exchange, default callbackUrl losing search/hash. None of these are in the diff; noting for awareness only.

Research: OpenRouter Responses API Basic Usage — structured array format requires content: [{ type: "input_text", text: "..." }], not a bare string. Simple input: "Hello!" top-level string also valid. The { data: Model[] } wrapper and GET /api/v1/models/{author}/{slug}/endpoints → { data: { id, name, endpoints: Endpoint[] } } shapes verified against list-endpoints API reference.

Test coverage: documentation-only PR; no runnable tests applicable.

Unresolved threads: both prior threads resolved ✅ — type: "message" was addressed; residual content string issue noted as inline comment below.

Nits (batched): The description of --sort throughput as "highest throughput models" / "most output capacity" is technically about max_completion_tokens not live throughput speed — pre-existing, but worth clarifying in a follow-up. The compare-models.ts docs say "exact ID matching" but the script silently falls back to partial match with a stderr warning — also pre-existing.

[perry-the-pr-reviewer]

[suggestion] content: "Hello!" — bare string in structured array input; Responses API spec requires a typed-parts array here

Details

Why: The PR correctly adds type: "message" to the input item, but content is still a bare string. The Responses API structured array format (per Basic Usage docs) requires content as a typed-parts array:

content: [{ type: "input_text", text: "Hello!" }]

A bare string in content may work today via server-side leniency, but it contradicts the documented contract and will mislead developers building against the spec. The type: "message" field signals "this is a structured message item" — mixing it with unstructured string content is inconsistent.

Fix: Either use the simple top-level string shorthand (avoids the inconsistency entirely):

body: JSON.stringify({
  model: "openai/gpt-4o-mini",
  input: "Hello!",
})

Or use the fully-structured form per spec:

body: JSON.stringify({
  model: "openai/gpt-4o-mini",
  input: [{ type: "message", role: "user", content: [{ type: "input_text", text: "Hello!" }] }],
})

Ref: OpenRouter Responses API Basic Usage