Shipping AI image generation in a native iOS app is a generate call that returns a hosted HTTPS URL, which you load into UIImageView or SwiftUI AsyncImage, while the API key stays on a server you control. The model is the easy part. The constraints that actually ship with the binary are asynchronous I/O off the main thread, an output address the image view can fetch without you running object storage, and authentication that survives an IPA unzip. A dedicated PicX Swift package is planned; today you call the REST API directly, and it already returns that URL in the generate response. A raw pxsk_ key in the app is a leak. Broker it.
The image view wants a URL, not a job id
UIKit and SwiftUI already know how to show a remote picture. UIImageView plus a loader, or AsyncImage(url:), take an HTTPS URL. They do not take a job identifier, a poll loop, or a base64 blob you decoded on the main actor.
That is the contract you want from the generator. POST a prompt. Get JSON. One field is a URL. Point the image view at it.
Most generation APIs were designed for Python scripts and GPU queues. They answer with a ticket. You store it. You poll. You eventually fetch a file, or a signed link that expires. On a laptop that is extra code. On a phone it is a spinner and a waiter that breaks when the user leaves the screen.
PicX image generation is synchronous. A simple generate call returns a hosted image URL in the response body. There is no poll on that path. The file already lives on PicX's own CDN. You do not configure a bucket. The string in the body is the asset the image view loads.
Same REST API at https://api.picxstudio.com. Same key type, pxsk_ prefix. Auth is one header:
Authorization: Bearer $PICX_API_KEYRoughly 33 image and video models sit behind that key. Billing is in credits per generation, never a currency amount on the meter. You can set a hard spend cap on the key.
Synchronous here is a protocol claim, not a speed claim. The GPU still runs. The difference is whether the app is allowed to await the generate and then assign imageURL, or whether it has to persist a job id, reconstruct a waiter after the view disappeared, and hope the file is still there.
Wait off the main thread
A generate call occupies a network connection for the whole render. That is fine. Occupying the main thread for the whole render is not. The UI freezes. The watchdog kills the app. It was a blocking HTTP call on the wrong queue.
Use async/await. URLSession already does. A Swift SDK should too. Kick the generate off the main actor. Show a progress view. Decode the URL. Hop back to assign it. That is the entire happy path for a still.
Cancel the in-flight Task when the view goes away. Users tap Generate, then swipe back. Task cancellation will not un-bill a generation that already started; treat it as "stop caring about the result," not "the GPU stopped." Fire generate on an explicit action, not on every keystroke.
Retries are the other way you double-pay. A timeout is not proof the work failed. If the connection dropped after the model ran, a second POST is a second file and a second credit deduction. Persist enough local state that a retry is a read of the previous URL, not a new generate, unless the user asked for another image. Do not invent a poll loop on a still that already returned a URL. The URL is the result.
Video and batch do not belong on this path. They are asynchronous. Delivery is by webhook. A phone has no public HTTPS endpoint. The mistake is treating every generation like a still, or treating every still like a video job.
Keep the API key off the device
A pxsk_ key is a bearer secret. Anyone who has it can generate, and generation deducts credits. In a backend or a CLI, the secret lives in an environment variable or a secret manager. In a public App Store app, anything you ship is extractable.
The IPA is a zip file. Strings, Info.plist, compiled-in constants — they all come out. Putting the key in the Keychain does not help if the app also contains the key. Keychain is for tokens the user earned, not a vault for your vendor credential.
A prototype on your phone can hold the key. A shipped App Store binary should not. The honest architecture is a broker.
The iOS app authenticates as your user. It POSTs a prompt to your backend. Your backend holds the pxsk_ key. Your backend calls https://api.picxstudio.com. Your backend returns the hosted image URL to the app. The image view loads the URL. The PicX secret never leaves the server.
struct GenerateBody: Encodable { let prompt: String }
struct GeneratePayload: Decodable { let url: URL }
func generateImage(prompt: String, session: URLSession = .shared) async throws -> URL {
var request = URLRequest(url: backendGenerateURL) // your server, not PicX
request.httpMethod = "POST"
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
// attach the user's session — not a pxsk_ key
request.httpBody = try JSONEncoder().encode(GenerateBody(prompt: prompt))
let (data, response) = try await session.data(for: request)
guard let http = response as? HTTPURLResponse, http.statusCode == 200 else {
throw URLError(.badServerResponse)
}
return try JSONDecoder().decode(GeneratePayload.self, from: data).url
}That extra hop is how you enforce product rules the API cannot know: this user is on the free tier, this prompt is disallowed, this device is generating too often. Spend caps on the PicX key are the last line, not the first. Cap the key your server uses so a bug in your broker cannot drain the account. A cap does not replace checking that the caller is a signed-in user.
Mint a dedicated key for the mobile backend. Do not reuse the playground key, or the key you pasted into Cursor. One REST API and one key type is the right auth shape. Separate key instances are the right blast radius.
A Swift SDK that accepts an API key is useful in DEBUG and behind the broker. It is not a reason to compile the production secret into the client.
Hosted output replaces a storage SDK
Native apps accumulate storage clients — S3, a Firebase bucket, a container "just for generated images." That is how a one-screen feature grows a second set of credentials.
You need storage when the generator returns bytes, or a temp URL that expires, or a local file in the app container. Bytes mean you upload. Temp URLs mean you copy before they 404. Local files mean the picture dies when the user deletes the app, and it was never shareable anyway.
A generate response that already contains a CDN URL removes that work. PicX hosts output on its own CDN. You do not bring a file-hosting service. You do not configure one. The URL is usable from AsyncImage, from a share sheet, from a server-rendered page, from the coding agent that asked for the same shot. Same string.
AsyncImage(url: generatedURL) { phase in
switch phase {
case .empty: ProgressView()
case .success(let image): image.resizable().scaledToFit()
case .failure: Text("Could not load image")
@unknown default: EmptyView()
}
}You give something up. The pixels live on PicX's network, not in a bucket you operate. If the files cannot leave your VPC, this shape is wrong: run your own model and your own store. If you already store user uploads, keep storing those. Generated output does not have to share that bucket.
Cache on device if you want snappy revisits. URLCache, or an image library sitting in front of the URL, is a loader. It is not a host. Do not download the file into Documents unless the user asked to save it. The CDN URL is the canonical copy.
Video completes on your backend
A still can occupy one HTTP request. A video cannot, not honestly. The request outlives mobile timeouts, background suspension, and the user's patience. PicX treats video and batch as asynchronous work delivered by webhook.
A webhook is an inbound POST to a public HTTPS URL. An iPhone does not have one. NAT, evolving IPs, outbound-only networking. Push notifications are not webhooks. If you poll from the app instead, you burn battery and invent the waiter the API was trying to spare you.
So the phone does not subscribe to video completion. Your backend does. The app submits "make this clip" to your server. Your server submits to PicX. PicX POSTs the result to your webhook. Your server stores the hosted URL against the user. The app fetches that row, or receives a push you sent, and then the player loads the URL. Same CDN. Different return shape.
Do not hold a spinner across that whole pipeline on the main thread. Persist a local pending record. Let the user leave. Come back to a URL.
Credits still deduct when the work runs. A webhook retry is not a second generation. A second submit is. Idempotency belongs on your backend, next to the key.
A Swift client is one more client of the same API
Most image-generation SDKs are Python or JavaScript. That matches how people prototype: a notebook, a Next route, an agent that writes picx-ai. A native app is a different runtime. You want Swift types, async/await, and something you can call from a view model without standing up a Node sidecar on the device.
That client is planned as a PicX Swift package. Until it ships, the URLSession call above is the whole integration, and it talks to the same REST API as the official picx-ai packages on npm and PyPI, the CLI, the interactive playground, and the MCP server. One key type. One billing unit. One hosted URL on the way out.
The rest of the agent-facing surface is for the other caller you probably have: the coding agent that generated the first product shots before you put them in the app. MCP with 19 tools, documented at https://picxstudio.com/developers/mcp. Agent Skills at https://picxstudio.com/skills. Live `llms.txt` and `llms-full.txt`. `/agent-setup/prompt.md`, an executable setup checklist a coding agent can run. Connection pages for Claude Desktop, Cursor, and ChatGPT (https://picxstudio.com/developers/mcp).
If the agent and the app hit different APIs, you will debug two auth stories and two URL formats. If they hit one API, your Swift client is the native adapter and the broker is the security boundary. Fetch llms.txt before you let an agent write the iOS integration. It will otherwise invent a polling loop and a bucket. The still path does not poll. The files are already hosted.
On-device generation is a different stack. Offline mode here is showing a cached URL, not running the model in Core ML. Keep the pxsk_ key on the server. Load the URL you got back.
FAQ
Can I put a PicX API key in my iOS app?
Not in a public App Store binary. A pxsk_ key is extractable from an IPA; have the app authenticate to your backend and let that server call https://api.picxstudio.com with the key.
Does a native iOS app have to poll for a generated image?
No. A simple PicX image generate is synchronous and returns a hosted CDN URL in the response body, which you load into UIImageView or AsyncImage. Video and batch are asynchronous and delivered by webhook to a server, not to the phone.
Where is the generated image file stored?
On PicX's own CDN. You do not bring or configure a separate file-hosting service; the generate response contains a URL you can pass straight to an image view.
Can the iOS app receive video webhooks directly?
No. A webhook needs a public HTTPS endpoint, which a phone does not have. Submit video from your backend, receive the webhook there, and hand the hosted URL to the app.
