{"openapi":"3.1.0","info":{"title":"嘿鲸 Agent Image API (GPT Image 2)","version":"0.3.0","description":"Agent pay-per-call image API for 嘿鲸 (Hey Whale). x402 / USDC, GPT Image 2, Images API–style (prompt + size). Humans use the 嘿鲸 web studio (鲸图·鲸笔·鲸漫·鲸仿·鲸影) with epay/quota."},"servers":[{"url":"https://hey.mrwhale.ai"}],"tags":[{"name":"Discovery","description":"Pricing and capability"},{"name":"Images","description":"Generate and poll"}],"paths":{"/api/agent/v1/pricing":{"get":{"tags":["Discovery"],"summary":"Pricing + GPT Image 2 capability","operationId":"getAgentPricing","responses":{"200":{"description":"Pricing and parameter capability","content":{"application/json":{"schema":{"type":"object"},"example":{"ok":true,"product":"hey-agent-image-1k","description":"Generate one 1K GPT Image 2 image via hey Agent API — x402 pay-per-call at $0.01 USDC","priceUsd":0.01,"price":"$0.01","currency":"USDC","unit":"image","model":"jingtu-image-1k","engine":"GPT Image 2","modelAliases":["gpt-image-2","GPT Image 2","jingtu-image-1k"],"sizes":["1024x1024","1024x1536","1536x1024","1024x1792","1792x1024"],"sizeNotes":{"1024x1024":"1:1 square","1024x1536":"3:4 portrait","1536x1024":"4:3 landscape","1024x1792":"9:16 tall / stories","1792x1024":"16:9 wide"},"capability":{"engine":"GPT Image 2","model":"jingtu-image-1k","modelAliases":["gpt-image-2","GPT Image 2","jingtu-image-1k"],"compatibility":"Same GPT Image 2 text-to-image behavior as OpenAI Images API style prompts/sizes. Upstream model id on our gateway is jingtu-image-1k.","mode":"text-to-image","async":true,"n":1,"quality":"auto","outputFormat":"png","sizes":["1024x1024","1024x1536","1536x1024","1024x1792","1792x1024"],"sizeNotes":{"1024x1024":"1:1 square","1024x1536":"3:4 portrait","1536x1024":"4:3 landscape","1024x1792":"9:16 tall / stories","1792x1024":"16:9 wide"},"unsupportedInMvp":["n > 1","image edits / image[] reference uploads","2K / 4K sizes","custom quality (forced auto)","response_format override (server returns hosted URLs)"],"requestFields":{"prompt":{"type":"string","required":true,"description":"English or Chinese text prompt. Same prompting style as GPT Image 2."},"size":{"type":"string","required":false,"default":"1024x1024","enum":["1024x1024","1024x1536","1536x1024","1024x1792","1792x1024"],"description":"Output pixel size WxH. Only 1K sizes in MVP."}},"headers":{"content-type":"application/json","accept":"application/json","PAYMENT-SIGNATURE":"Required on paid retry after HTTP 402 (x402 exact)."}},"network":"eip155:8453","networkAlias":"base","payTo":"0x68a361264F0c8e93242cD36A0C1992fC687d9B8a","scheme":"exact","paymentProtocol":"x402","endpoints":{"generate":"/api/agent/v1/images/generations","jobs":"/api/agent/v1/images/jobs/{id}","pricing":"/api/agent/v1/pricing","openapi":"/api/agent/openapi.json"},"notes":["China human users continue to use login + epay/quota at ~¥0.1/image.","Agent path is anonymous x402; platform upstream key pays new-api.","MVP: n=1 text-to-image, 1K sizes only, GPT Image 2 quality.","Integration details: GET /api/agent/openapi.json and /llms.txt"]}}}}}}},"/api/agent/v1/images/generations":{"post":{"tags":["Images"],"summary":"Generate one 1K GPT Image 2 image (x402)","description":"OpenAI Images–style body: `{ prompt, size? }`. Engine is GPT Image 2 (gateway model jingtu-image-1k). First call without payment returns 402; retry with PAYMENT-SIGNATURE. Then poll jobs/{id}.","operationId":"agentGenerateImage","parameters":[{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"description":"x402 payment signature from a prior 402 challenge","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt"],"additionalProperties":false,"properties":{"prompt":{"type":"string","minLength":1,"description":"English or Chinese text prompt. Same prompting style as GPT Image 2.","example":"a small cute red whale icon, flat vector, white background"},"size":{"type":"string","default":"1024x1024","enum":["1024x1024","1024x1536","1536x1024","1024x1792","1792x1024"],"description":"1K WxH only. Same aspect options as GPT Image 2 low-res tier.","example":"1024x1024"}}},"examples":{"square":{"summary":"1:1","value":{"prompt":"a small cute red whale icon, flat vector, white background","size":"1024x1024"}},"portrait":{"summary":"3:4","value":{"prompt":"a small cute red whale icon, flat vector, white background","size":"1024x1536"}},"landscape":{"summary":"16:9","value":{"prompt":"a small cute red whale icon, flat vector, white background","size":"1792x1024"}}}}}},"responses":{"202":{"description":"Job accepted — poll poll/jobId","content":{"application/json":{"example":{"ok":true,"status":"pending","jobId":"gen-xxxx","workId":"agent_xxxx","poll":"/api/agent/v1/images/jobs/gen-xxxx","pricing":{"ok":true,"product":"hey-agent-image-1k","description":"Generate one 1K GPT Image 2 image via hey Agent API — x402 pay-per-call at $0.01 USDC","priceUsd":0.01,"price":"$0.01","currency":"USDC","unit":"image","model":"jingtu-image-1k","engine":"GPT Image 2","modelAliases":["gpt-image-2","GPT Image 2","jingtu-image-1k"],"sizes":["1024x1024","1024x1536","1536x1024","1024x1792","1792x1024"],"sizeNotes":{"1024x1024":"1:1 square","1024x1536":"3:4 portrait","1536x1024":"4:3 landscape","1024x1792":"9:16 tall / stories","1792x1024":"16:9 wide"},"capability":{"engine":"GPT Image 2","model":"jingtu-image-1k","modelAliases":["gpt-image-2","GPT Image 2","jingtu-image-1k"],"compatibility":"Same GPT Image 2 text-to-image behavior as OpenAI Images API style prompts/sizes. Upstream model id on our gateway is jingtu-image-1k.","mode":"text-to-image","async":true,"n":1,"quality":"auto","outputFormat":"png","sizes":["1024x1024","1024x1536","1536x1024","1024x1792","1792x1024"],"sizeNotes":{"1024x1024":"1:1 square","1024x1536":"3:4 portrait","1536x1024":"4:3 landscape","1024x1792":"9:16 tall / stories","1792x1024":"16:9 wide"},"unsupportedInMvp":["n > 1","image edits / image[] reference uploads","2K / 4K sizes","custom quality (forced auto)","response_format override (server returns hosted URLs)"],"requestFields":{"prompt":{"type":"string","required":true,"description":"English or Chinese text prompt. Same prompting style as GPT Image 2."},"size":{"type":"string","required":false,"default":"1024x1024","enum":["1024x1024","1024x1536","1536x1024","1024x1792","1792x1024"],"description":"Output pixel size WxH. Only 1K sizes in MVP."}},"headers":{"content-type":"application/json","accept":"application/json","PAYMENT-SIGNATURE":"Required on paid retry after HTTP 402 (x402 exact)."}},"network":"eip155:8453","networkAlias":"base","payTo":"0x68a361264F0c8e93242cD36A0C1992fC687d9B8a","scheme":"exact","paymentProtocol":"x402","endpoints":{"generate":"/api/agent/v1/images/generations","jobs":"/api/agent/v1/images/jobs/{id}","pricing":"/api/agent/v1/pricing","openapi":"/api/agent/openapi.json"},"notes":["China human users continue to use login + epay/quota at ~¥0.1/image.","Agent path is anonymous x402; platform upstream key pays new-api.","MVP: n=1 text-to-image, 1K sizes only, GPT Image 2 quality.","Integration details: GET /api/agent/openapi.json and /llms.txt"]}}}}},"400":{"description":"Bad request (missing prompt or non-1K size)"},"402":{"description":"Payment required (x402). Read PAYMENT-REQUIRED header, pay, retry with PAYMENT-SIGNATURE."},"503":{"description":"Agent path not configured"}}}},"/api/agent/v1/images/jobs/{id}":{"get":{"tags":["Images"],"summary":"Poll agent image job","description":"Statuses: pending | running | done | error | cancelled. On done, use images[] or result.data[].url.","operationId":"getAgentImageJob","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Job status","content":{"application/json":{"examples":{"done":{"summary":"done","value":{"ok":true,"status":"done","id":"gen-xxxx","progress":{"total":1,"completed":1,"failed":0},"images":["https://img.hey.mrwhale.ai/jingtu/.../image.png"],"files":[{"url":"https://img.hey.mrwhale.ai/jingtu/.../image.png","width":1024,"height":1024}],"result":{"data":[{"url":"https://img.hey.mrwhale.ai/jingtu/.../image.png"}]}}},"pending":{"summary":"pending","value":{"ok":true,"status":"pending","id":"gen-xxxx","progress":{"total":1,"completed":0,"failed":0},"images":[]}}}}}},"404":{"description":"Not found"}}}}},"components":{"schemas":{"AgentCapability":{"type":"object","example":{"engine":"GPT Image 2","model":"jingtu-image-1k","modelAliases":["gpt-image-2","GPT Image 2","jingtu-image-1k"],"compatibility":"Same GPT Image 2 text-to-image behavior as OpenAI Images API style prompts/sizes. Upstream model id on our gateway is jingtu-image-1k.","mode":"text-to-image","async":true,"n":1,"quality":"auto","outputFormat":"png","sizes":["1024x1024","1024x1536","1536x1024","1024x1792","1792x1024"],"sizeNotes":{"1024x1024":"1:1 square","1024x1536":"3:4 portrait","1536x1024":"4:3 landscape","1024x1792":"9:16 tall / stories","1792x1024":"16:9 wide"},"unsupportedInMvp":["n > 1","image edits / image[] reference uploads","2K / 4K sizes","custom quality (forced auto)","response_format override (server returns hosted URLs)"],"requestFields":{"prompt":{"type":"string","required":true,"description":"English or Chinese text prompt. Same prompting style as GPT Image 2."},"size":{"type":"string","required":false,"default":"1024x1024","enum":["1024x1024","1024x1536","1536x1024","1024x1792","1792x1024"],"description":"Output pixel size WxH. Only 1K sizes in MVP."}},"headers":{"content-type":"application/json","accept":"application/json","PAYMENT-SIGNATURE":"Required on paid retry after HTTP 402 (x402 exact)."}}}}}}