AI Models API

Text and image generation over a single HTTP endpoint. No SDK, no keys to pass — just hit the URLs below.

\n\n

\n This API gives you two things: a chat endpoint that returns text from a language model,\n and an image endpoint that turns a text prompt into an image and hands you back a hosted URL.\n Everything speaks JSON. You can call it from a browser, curl, a phone app, or any backend.\n

\n\n

\n There's no auth on these routes — the server holds the model token internally, so you only\n deal with prompts and responses. If you're building a public app, put your own rate limiting in front of it.\n

\n\n

Base URL

All routes are relative to the deployment origin:

loading…

\n\n

Quick start

The fastest way to see it work — open this in your browser:

loading…

\n\n \n

Chat

Send a prompt, get text back. There are two ways to call it.

\n\n

\n GET\n /v1/chat?prompt=...\n

Good for quick tests and simple one-liners. Put your question in the prompt query parameter.

curl \"$BASE/v1/chat?prompt=What%20is%20the%20capital%20of%20France%3F\"

\n\n

\n POST\n /v1/chat\n

Use this when you want a system prompt, a full conversation, or generation settings. Send JSON.

\n\n

Body fields

\n \n \n \n \n \n \n \n \n

Field	Type	Notes
`prompt`	string	Shortcut for a single user message. Use this or `messages`.
`messages`	array	Full chat history. Each item is `{ \"role\": \"system\" \| \"user\" \| \"assistant\", \"content\": \"...\" }`.
`model`	string	optional · defaults to `openai/gpt-oss-120b:groq`
`temperature`	number	optional · 0–2, higher is more random
`max_tokens`	number	optional · cap on response length
`top_p`	number	optional · nucleus sampling

\n\n

Example — single prompt

curl -X POST \"$BASE/v1/chat\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"prompt\": \"Give me three names for a coffee shop.\"\n  }'

\n\n

Example — full conversation

curl -X POST \"$BASE/v1/chat\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"openai/gpt-oss-120b:groq\",\n    \"temperature\": 0.7,\n    \"messages\": [\n      { \"role\": \"system\", \"content\": \"You answer in one short sentence.\" },\n      { \"role\": \"user\", \"content\": \"Why is the sky blue?\" }\n    ]\n  }'

\n\n

Response

{\n  \"model\": \"openai/gpt-oss-120b\",\n  \"reply\": \"Sunlight scatters off air molecules, and blue light scatters most.\",\n  \"usage\": {\n    \"prompt_tokens\": 24,\n    \"completion_tokens\": 14,\n    \"total_tokens\": 38\n  }\n}

\n\n \n

Image

\n Describe an image, get back a hosted URL you can drop into an <img> tag.\n The server generates the image, uploads it for you, and returns the link.\n

\n\n

\n GET\n /v1/image?prompt=...\n

\n POST\n /v1/image\n

\n\n

Body / query fields

\n \n \n \n \n \n \n

Field	Type	Notes
`prompt`	string	What you want to see. Required.
`model`	string	optional · defaults to `Tongyi-MAI/Z-Image-Turbo`
`negative_prompt`	string	optional · things to avoid in the image
`raw`	boolean	optional · if true, returns the raw image bytes instead of a JSON URL

\n\n

Example

curl -X POST \"$BASE/v1/image\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"prompt\": \"An astronaut riding a horse, cinematic lighting\"\n  }'

\n\n

Response

{\n  \"prompt\": \"An astronaut riding a horse, cinematic lighting\",\n  \"model\": \"Tongyi-MAI/Z-Image-Turbo\",\n  \"url\": \"https://jerrycans-file.hf.space/files/gen-1717000000000.png\",\n  \"content_type\": \"image/png\"\n}

\n\n

Want the image bytes directly (e.g. to pipe into a file)? Add ?raw=true:

curl \"$BASE/v1/image?prompt=a%20red%20bicycle&raw=true\" --output bike.png

\n\n \n

Calling it from code

\n\n

JavaScript

const base = \"$BASE\";\n\n// chat\nconst chat = await fetch(`${base}/v1/chat`, {\n  method: \"POST\",\n  headers: { \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({ prompt: \"Write a haiku about the sea.\" }),\n}).then(r => r.json());\nconsole.log(chat.reply);\n\n// image\nconst img = await fetch(`${base}/v1/image`, {\n  method: \"POST\",\n  headers: { \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({ prompt: \"A lighthouse at dusk\" }),\n}).then(r => r.json());\nconsole.log(img.url);

\n\n

Python

import requests\n\nbase = \"$BASE\"\n\nchat = requests.post(f\"{base}/v1/chat\", json={\n    \"prompt\": \"Explain gravity to a five year old.\"\n}).json()\nprint(chat[\"reply\"])\n\nimg = requests.post(f\"{base}/v1/image\", json={\n    \"prompt\": \"A fox in a snowy forest\"\n}).json()\nprint(img[\"url\"])

\n\n \n

Errors

Failures come back as JSON with the matching HTTP status:

{\n  \"error\": \"Provide a 'prompt' describing the image\",\n  \"detail\": null\n}

\n \n \n \n \n \n \n \n

Status	Meaning
`400`	Bad input — missing prompt, malformed JSON, etc.
`404`	Route doesn't exist.
`405`	Wrong HTTP method for that route.
`429`	Rate limited upstream — slow down and retry.
`5xx`	Model or upload host had a problem. The `detail` field usually says what.

\n\n

Endpoints at a glance

\n \n \n \n \n \n \n

Route	Method	Does
`/`	GET	This page.
`/health`	GET	Liveness check.
`/v1/chat`	GET / POST	Text generation.
`/v1/image`	GET / POST	Image generation → hosted URL.

\n\n \n

\n\n\n\n\n\n","label",[18],"pulls","branches",1,"forks","envVars",{"_177":164,"_179":26},"connections",{"_177":26,"_178":26},"count","unfilledCount","emptyCount",{"_34":160,"_13":18,"_63":64,"_44":-5,"_36":37,"_161":82,"_162":101,"_38":212,"_40":164,"_66":21,"_165":166,"_67":24,"_167":-5,"_191":213,"_17":214},{"_34":204,"_13":205,"_63":206,"_44":-5,"_36":37,"_161":207,"_162":101,"_38":208,"_40":171,"_66":189,"_165":209,"_67":24,"_167":-5,"_191":210,"_17":211},{"_34":194,"_13":195,"_63":99,"_44":-5,"_36":37,"_161":196,"_162":101,"_38":197,"_40":198,"_66":199,"_165":200,"_67":24,"_167":201,"_191":202,"_17":203},{"_34":184,"_13":185,"_63":186,"_44":-5,"_36":37,"_161":187,"_162":101,"_38":188,"_40":171,"_66":189,"_165":190,"_67":24,"_167":-5,"_191":192,"_17":193},"bbc9dc2e-c701-4e6f-8a75-75af4d3ebb64","upload.ts","462a2df8-5f99-11f1-b814-1607ee4eb77e",13,["D",1780524869040],"script","// Pushes raw image bytes to the jerrycans file host and returns a public URL.\n\nconst UPLOAD_ENDPOINT = \"https://jerrycans-file.hf.space/upload\";\nconst PUBLIC_BASE = \"https://jerrycans-file.hf.space\";\n\nfunction extFromContentType(contentType: string): string {\n if (contentType.includes(\"jpeg\") || contentType.includes(\"jpg\")) return \"jpg\";\n if (contentType.includes(\"webp\")) return \"webp\";\n if (contentType.includes(\"gif\")) return \"gif\";\n return \"png\";\n}\n\nexport async function uploadImage(bytes: Uint8Array, contentType: string): Promise {\n const ext = extFromContentType(contentType);\n const filename = `gen-${Date.now()}.${ext}`;\n\n const form = new FormData();\n form.append(\"file\", new Blob([bytes], { type: \"application/octet-stream\" }), filename);\n form.append(\"originalExtension\", ext);\n\n const res = await fetch(UPLOAD_ENDPOINT, { method: \"POST\", body: form });\n if (!res.ok) {\n throw new Error(`upload failed (${res.status})`);\n }\n\n const result = await res.json();\n let url: string = result.url ?? \"\";\n if (url && !url.startsWith(\"http\")) {\n url = PUBLIC_BASE + url;\n }\n if (!url) throw new Error(\"upload host returned no url\");\n return url;\n}\n","children",[],[185],"2ffb3484-8923-48f8-8f4e-f99806252bf5","main.ts",15,["D",1780525038944],9,"http","import { chat, HfError, textToImage } from \"./hf.ts\";\nimport { uploadImage } from \"./upload.ts\";\nimport { parseVal, readFile } from \"https://esm.town/v/std/utils/index.ts\";\n\nconst JSON_HEADERS = { \"Content-Type\": \"application/json\" };\n\nfunction json(data: unknown, status = 200) {\n return new Response(JSON.stringify(data, null, 2), {\n status,\n headers: JSON_HEADERS,\n });\n}\n\nfunction errorJson(message: string, status = 400, detail?: unknown) {\n return json({ error: message, detail: detail ?? null }, status);\n}\n\n// Reads a JSON body, tolerating empty bodies.\nasync function readBody(req: Request): Promise> {\n const text = await req.text();\n if (!text.trim()) return {};\n try {\n return JSON.parse(text);\n } catch {\n throw new Error(\"Request body ifs not valid JSON\");\n }\n}\n\nexport default async function (req: Request): Promise {\n const url = new URL(req.url);\n const path = url.pathname.replace(/\\/+$/, \"\") || \"/\";\n\n // ---- Docs page ----\n if (path === \"/\" && req.method === \"GET\") {\n const html = await readFile(\"/docs.html\", import.meta.url);\n return new Response(html, {\n headers: { \"Content-Type\": \"text/html; charset=utf-8\" },\n });\n }\n\n // ---- View source ----\n if (path === \"/source\") {\n return new Response(null, {\n status: 302,\n headers: { Location: parseVal().links.self.val },\n });\n }\n\n // ---- Health check ----\n if (path === \"/health\") {\n return json({ ok: true, time: new Date().toISOString() });\n }\n\n // ---- Chat (text) ----\n if (path === \"/v1/chat\") {\n if (req.method === \"GET\") {\n const prompt = url.searchParams.get(\"prompt\") ||\n url.searchParams.get(\"q\");\n if (!prompt) {\n return errorJson(\"Pass a prompt: /v1/chat?prompt=hello\", 400);\n }\n return await handleChat({\n messages: [{ role: \"user\", content: prompt }],\n model: url.searchParams.get(\"model\") || undefined,\n });\n }\n\n if (req.method === \"POST\") {\n let body: Record;\n try {\n body = await readBody(req);\n } catch (e) {\n return errorJson((e as Error).message, 400);\n }\n\n // Accept either { prompt } or full { messages: [...] }.\n let messages = body.messages as any;\n if (!messages && typeof body.prompt === \"string\") {\n messages = [{ role: \"user\", content: body.prompt }];\n }\n if (!Array.isArray(messages) || messages.length === 0) {\n return errorJson(\n \"Provide 'prompt' (string) or 'messages' (array)\",\n 400,\n );\n }\n\n return await handleChat({\n messages,\n model: typeof body.model === \"string\" ? body.model : undefined,\n temperature: typeof body.temperature === \"number\"\n ? body.temperature\n : undefined,\n max_tokens: typeof body.max_tokens === \"number\"\n ? body.max_tokens\n : undefined,\n top_p: typeof body.top_p === \"number\" ? body.top_p : undefined,\n });\n }\n\n return errorJson(\"Use GET or POST on /v1/chat\", 405);\n }\n\n // ---- Image (text-to-image, uploaded to host) ----\n if (path === \"/v1/image\") {\n let prompt: string | null = null;\n let model: string | undefined;\n let provider: string | undefined;\n let negative_prompt: string | undefined;\n let raw = url.searchParams.get(\"raw\") === \"true\" ||\n url.searchParams.get(\"raw\") === \"1\";\n\n if (req.method === \"GET\") {\n prompt = url.searchParams.get(\"prompt\") || url.searchParams.get(\"q\");\n model = url.searchParams.get(\"model\") || undefined;\n provider = url.searchParams.get(\"provider\") || undefined;\n negative_prompt = url.searchParams.get(\"negative_prompt\") || undefined;\n } else if (req.method === \"POST\") {\n let body: Record;\n try {\n body = await readBody(req);\n } catch (e) {\n return errorJson((e as Error).message, 400);\n }\n prompt = typeof body.prompt === \"string\" ? body.prompt : null;\n model = typeof body.model === \"string\" ? body.model : undefined;\n provider = typeof body.provider === \"string\" ? body.provider : undefined;\n negative_prompt = typeof body.negative_prompt === \"string\"\n ? body.negative_prompt\n : undefined;\n if (body.raw === true) raw = true;\n } else {\n return errorJson(\"Use GET or POST on /v1/image\", 405);\n }\n\n if (!prompt) {\n return errorJson(\"Provide a 'prompt' describing the image\", 400);\n }\n\n try {\n const img = await textToImage({\n prompt,\n model,\n provider,\n negative_prompt,\n });\n\n // raw=true streams the bytes straight back instead of uploading.\n if (raw) {\n return new Response(img.bytes, {\n headers: { \"Content-Type\": img.contentType },\n });\n }\n\n const uploadedUrl = await uploadImage(img.bytes, img.contentType);\n return json({\n prompt,\n model: img.model,\n url: uploadedUrl,\n content_type: img.contentType,\n });\n } catch (e) {\n return handleError(e);\n }\n }\n\n return errorJson(`Unknown route: ${path}`, 404);\n}\n\nasync function handleChat(opts: Parameters[0]): Promise {\n try {\n const result = await chat(opts);\n return json({\n model: result.model,\n reply: result.reply,\n usage: result.usage,\n });\n } catch (e) {\n return handleError(e);\n }\n}\n\nfunction handleError(e: unknown): Response {\n if (e instanceof HfError) {\n return errorJson(\n e.message,\n e.status >= 400 && e.status < 600 ? e.status : 502,\n e.detail,\n );\n }\n return errorJson((e as Error).message || \"Something went wrong\", 500);\n}","aimodel",[],[195],"4144359c-8b24-4560-bd29-5db192a3e915","hf.ts","4373a594-5f99-11f1-9f91-1607ee4eb77e",11,["D",1780524842321],"// HuggingFace router calls. Every request bills to the org in ORG via X-HF-Bill-To.\n\nconst HF_TOKEN = Deno.env.get(\"HF_TOKEN\");\nconst BILL_TO = Deno.env.get(\"ORG\") || \"hugging-science\";\nconst ROUTER = \"https://router.huggingface.co/v1\";\n\nfunction billingHeaders(extra: Record = {}) {\n return {\n \"Authorization\": `Bearer ${HF_TOKEN}`,\n \"X-HF-Bill-To\": BILL_TO,\n ...extra,\n };\n}\n\nexport type ChatMessage = { role: \"system\" | \"user\" | \"assistant\"; content: string };\n\nexport interface ChatOptions {\n messages: ChatMessage[];\n model?: string;\n temperature?: number;\n max_tokens?: number;\n top_p?: number;\n}\n\n// Single-turn helper: pass a string prompt, get a string back.\nexport async function chat(opts: ChatOptions) {\n if (!HF_TOKEN) throw new Error(\"HF_TOKEN env var is not set\");\n\n const model = opts.model || \"openai/gpt-oss-120b:groq\";\n const body: Record = {\n model,\n messages: opts.messages,\n stream: false,\n };\n if (opts.temperature != null) body.temperature = opts.temperature;\n if (opts.max_tokens != null) body.max_tokens = opts.max_tokens;\n if (opts.top_p != null) body.top_p = opts.top_p;\n\n const res = await fetch(`${ROUTER}/chat/completions`, {\n method: \"POST\",\n headers: billingHeaders({ \"Content-Type\": \"application/json\" }),\n body: JSON.stringify(body),\n });\n\n const text = await res.text();\n if (!res.ok) {\n throw new HfError(`chat request failed (${res.status})`, res.status, text);\n }\n\n const data = JSON.parse(text);\n const message = data.choices?.[0]?.message?.content ?? \"\";\n return {\n model: data.model ?? model,\n reply: message,\n usage: data.usage ?? null,\n raw: data,\n };\n}\n\n// Text-to-image. Uses the official HF inference client so provider routing\n// (replicate/fal/etc.) is handled for us. Billing goes to the org via billTo.\n// Returns raw image bytes + the content type the provider gave us.\nexport async function textToImage(opts: {\n prompt: string;\n model?: string;\n provider?: string;\n negative_prompt?: string;\n}) {\n if (!HF_TOKEN) throw new Error(\"HF_TOKEN env var is not set\");\n\n const model = opts.model || \"Tongyi-MAI/Z-Image-Turbo\";\n const provider = (opts.provider || \"replicate\") as any;\n\n const { InferenceClient } = await import(\"npm:@huggingface/inference\");\n const client = new InferenceClient(HF_TOKEN, { billTo: BILL_TO });\n\n try {\n const result = await client.textToImage({\n provider,\n model,\n inputs: opts.prompt,\n parameters: opts.negative_prompt ? { negative_prompt: opts.negative_prompt } : undefined,\n });\n\n // The client returns a Blob.\n const blob = result as Blob;\n const contentType = blob.type || \"image/png\";\n const bytes = new Uint8Array(await blob.arrayBuffer());\n return { bytes, contentType, model, provider };\n } catch (e) {\n const msg = (e as Error)?.message || String(e);\n throw new HfError(`image request failed: ${msg}`, 502, msg);\n }\n}\n\nexport class HfError extends Error {\n status: number;\n detail: string;\n constructor(message: string, status: number, detail: string) {\n super(message);\n this.name = \"HfError\";\n this.status = status;\n this.detail = detail;\n }\n}\n",[],[205],["D",1780525070161],[],[18],["D",1780519334637],{"_11":12,"_138":70},{"_11":12,"_133":134,"_69":70,"_30":68,"_135":136,"_137":24},{"_40":124,"_13":16,"_34":37,"_125":88,"_126":-5,"_127":-5,"_128":-5,"_129":-5,"_130":-5,"_131":14,"_132":12},"ctx",{"_53":-5,"_157":252,"_253":254,"_255":256,"_257":24,"_258":24,"_259":24,"_260":101,"_261":-5,"_262":-7,"_263":-7,"_264":26,"_265":24,"_266":24,"_267":-5,"_268":24,"_269":24,"_270":24,"_271":-5},"ENV",{"_223":224,"_225":226,"_227":16,"_228":229,"_230":231,"_232":233,"_234":235,"_236":237,"_238":239,"_240":241,"_242":243,"_244":245,"_246":247,"_248":249,"_250":251},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","e87eb04e707cf64e7e532c8e8ec395f209e17f15","RENDER_GIT_BRANCH","POSTHOG_API_TOKEN","phc_nmoyuAkStEZuUp69rYlg1DZgrIt19Gx0Y4Hwf8tGgJP","POSTHOG_API_HOST","https://wart.val.town","WEB_API_TEMPLATE","https://{val}.web.val.run","APP_URL","https://www.val.town","MODULE_URL","https://esm.town","VANITY_WEB_API_TEMPLATE","https://{label}.val.run/","DENOLS_URL","https://lsp.val.town","NODE_ENV","production","CLOUDFLARE_TURNSTILE_SITE_KEY","0x4AAAAAACtaIZJH7s9rBMZ6","GOOGLE_CLIENT_ID","875989696899-jtsqkhlbdv5jrlsk8631p7ipjg3c6o62.apps.googleusercontent.com","STRIPE_PUBLISHABLE_KEY","pk_live_51N2zvWEpZTTLipIkVEwXrUG9AT0yeOOEYxszarZT1jpsZV58Ly6wlg3SltZpHN26CUalOBmUSY7adQRQiSkCZz2500qSXNkf8Y","API_URL","https://api.val.town",[],"preferencesKeybindings","default","preferencesTheme","light","preferencesFixers","preferencesCopilot","preferencesSelectionAi","preferencesCloseBrackets","preferencesChatPanelState","preferencesDprint","preferencesDenofmt","notificationCount","flagDenols","isBusinessOrgMember","businessOrgHandle","isBusinessOrgAdmin","isHigherTownieTier","navCollapsed","currentOrgId"]

History · docs.html