devupai 1.0.0a1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,113 @@
1
+ """Health check: ``GET /health``, next to the versioned API path."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Mapping
6
+ from urllib.parse import urljoin
7
+
8
+ from devupai._response import APIResponse
9
+ from devupai.resources._base import AsyncAPIResource, SyncAPIResource, endpoint, options, with_data
10
+ from devupai.types import HealthResponse
11
+ from devupai.types._base import parse_model
12
+
13
+ __all__ = ["Health", "AsyncHealth", "HealthWithResponse", "AsyncHealthWithResponse"]
14
+
15
+ _PATH = "/health"
16
+
17
+
18
+ def _health_url(base_url: str) -> str:
19
+ """The health URL next to the versioned path of ``base_url``: ``https://host/v1`` → ``https://host/health``."""
20
+ return urljoin(base_url + "/", "../health")
21
+
22
+
23
+ class HealthWithResponse(SyncAPIResource):
24
+ """The methods of :class:`Health`, returning the whole :class:`~devupai.APIResponse`."""
25
+
26
+ @endpoint("GET", _PATH, billed=False, root=True)
27
+ def check(
28
+ self,
29
+ *,
30
+ extra_headers: Mapping[str, str] | None = None,
31
+ timeout: float | None = None,
32
+ max_retries: int | None = None,
33
+ ) -> APIResponse[HealthResponse]:
34
+ """Checks that the API is reachable; see :meth:`Health.check`."""
35
+ response = self._send(
36
+ "GET",
37
+ url=_health_url(self._client.base_url),
38
+ auth=False,
39
+ options=options(timeout=timeout, max_retries=max_retries, extra_headers=extra_headers),
40
+ )
41
+ return with_data(response, parse_model(HealthResponse, response.data))
42
+
43
+
44
+ class Health(SyncAPIResource):
45
+ """Health check: ``GET /health``, next to the versioned API path."""
46
+
47
+ @property
48
+ def with_response(self) -> HealthWithResponse:
49
+ """The same methods, returning the whole :class:`~devupai.APIResponse` (headers, request id, warnings)."""
50
+ return HealthWithResponse(self._client)
51
+
52
+ @endpoint("GET", _PATH, billed=False, root=True)
53
+ def check(
54
+ self,
55
+ *,
56
+ extra_headers: Mapping[str, str] | None = None,
57
+ timeout: float | None = None,
58
+ max_retries: int | None = None,
59
+ ) -> HealthResponse:
60
+ """Checks that the API is reachable. Sends no API key, and no ``Authorization`` header at all.
61
+
62
+ Example::
63
+
64
+ health = client.health.check()
65
+ """
66
+ return self.with_response.check(extra_headers=extra_headers, timeout=timeout, max_retries=max_retries).data
67
+
68
+
69
+ class AsyncHealthWithResponse(AsyncAPIResource):
70
+ """The methods of :class:`AsyncHealth`, returning the whole :class:`~devupai.APIResponse`."""
71
+
72
+ @endpoint("GET", _PATH, billed=False, root=True)
73
+ async def check(
74
+ self,
75
+ *,
76
+ extra_headers: Mapping[str, str] | None = None,
77
+ timeout: float | None = None,
78
+ max_retries: int | None = None,
79
+ ) -> APIResponse[HealthResponse]:
80
+ """Checks that the API is reachable; see :meth:`AsyncHealth.check`."""
81
+ response = await self._send(
82
+ "GET",
83
+ url=_health_url(self._client.base_url),
84
+ auth=False,
85
+ options=options(timeout=timeout, max_retries=max_retries, extra_headers=extra_headers),
86
+ )
87
+ return with_data(response, parse_model(HealthResponse, response.data))
88
+
89
+
90
+ class AsyncHealth(AsyncAPIResource):
91
+ """Health check: ``GET /health``, next to the versioned API path."""
92
+
93
+ @property
94
+ def with_response(self) -> AsyncHealthWithResponse:
95
+ """The same methods, returning the whole :class:`~devupai.APIResponse` (headers, request id, warnings)."""
96
+ return AsyncHealthWithResponse(self._client)
97
+
98
+ @endpoint("GET", _PATH, billed=False, root=True)
99
+ async def check(
100
+ self,
101
+ *,
102
+ extra_headers: Mapping[str, str] | None = None,
103
+ timeout: float | None = None,
104
+ max_retries: int | None = None,
105
+ ) -> HealthResponse:
106
+ """Checks that the API is reachable. Sends no API key, and no ``Authorization`` header at all.
107
+
108
+ Example::
109
+
110
+ health = await client.health.check()
111
+ """
112
+ response = await self.with_response.check(extra_headers=extra_headers, timeout=timeout, max_retries=max_retries)
113
+ return response.data
@@ -0,0 +1,503 @@
1
+ """Images: generation (``POST /images/generations``), editing (``POST /images/edits``) and generated files."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Awaitable, Callable, Mapping
6
+ from typing import TYPE_CHECKING, Unpack, cast, overload
7
+
8
+ import httpx
9
+
10
+ from devupai._errors import DevupAPIError
11
+ from devupai._response import APIResponse, AsyncBinaryResponse, BinaryResponse
12
+ from devupai.resources._base import (
13
+ AsyncAPIResource,
14
+ SyncAPIResource,
15
+ billed_post_retry,
16
+ endpoint,
17
+ json_body,
18
+ options,
19
+ with_data,
20
+ )
21
+ from devupai.resources.shared import MultipartValue, contains_file_input, image_edit_form
22
+ from devupai.types import ImageGenerateResponse
23
+ from devupai.types._base import parse_model
24
+
25
+ if TYPE_CHECKING:
26
+ from devupai.types import ImageEditJsonParams, ImageEditParams, ImageGenerateParams
27
+
28
+ __all__ = [
29
+ "Images",
30
+ "AsyncImages",
31
+ "ImagesWithResponse",
32
+ "AsyncImagesWithResponse",
33
+ ]
34
+
35
+ _GENERATE_PATH = "/images/generations"
36
+ _EDIT_PATH = "/images/edits"
37
+ # A generated file is fetched from the absolute URL the API returned, so the template is the whole URL.
38
+ _DOWNLOAD_PATH = "{url}"
39
+
40
+ #: The request fields of an image edit that carry input images (``images`` is the list form of ``image``).
41
+ _IMAGE_INPUT_FIELDS = ("image", "images", "mask", "markup")
42
+
43
+ #: The message of the error raised by ``images.download`` for a URL it does not fetch. It never contains the URL.
44
+ _INVALID_FILE_URL_MESSAGE = "images.download only fetches URLs returned by the API."
45
+
46
+ _DEFAULT_PORTS = {"http": 80, "https": 443}
47
+
48
+
49
+ def _edit_request(body: Mapping[str, object]) -> tuple[object, list[tuple[str, MultipartValue]] | None]:
50
+ """The JSON body or the form of an image edit: the form when an input image is a file, JSON otherwise."""
51
+ if any(contains_file_input(body.get(name)) for name in _IMAGE_INPUT_FIELDS):
52
+ return None, image_edit_form(body)
53
+ return body, None
54
+
55
+
56
+ def _origin(value: str) -> tuple[str, str, int] | None:
57
+ """The ``(scheme, host, port)`` of an absolute http or https URL without a user name or password, with the default
58
+ port filled in; ``None`` for any other value."""
59
+ try:
60
+ parsed = httpx.URL(value)
61
+ except (httpx.InvalidURL, ValueError, TypeError):
62
+ return None
63
+ if parsed.scheme not in _DEFAULT_PORTS or not parsed.host or parsed.userinfo:
64
+ return None
65
+ port = _DEFAULT_PORTS[parsed.scheme] if parsed.port is None else parsed.port
66
+ return parsed.scheme, parsed.host, port
67
+
68
+
69
+ def _download_url(base_url: str, url: object) -> str:
70
+ """``url`` when it is an absolute URL on the same origin as ``base_url`` (scheme, host and port), without a user
71
+ name or password. Otherwise a ``DevupAPIError`` (code ``invalid_url``) is raised before any request."""
72
+ if isinstance(url, str):
73
+ target = _origin(url)
74
+ if target is not None and target == _origin(base_url):
75
+ return url
76
+ # Raised outside any ``except`` block, so no error that shows the URL is chained to it.
77
+ raise DevupAPIError(0, _INVALID_FILE_URL_MESSAGE, code="invalid_url")
78
+
79
+
80
+ class ImagesWithResponse(SyncAPIResource):
81
+ """The methods of :class:`Images`, returning the whole :class:`~devupai.APIResponse`."""
82
+
83
+ @endpoint("POST", _GENERATE_PATH, billed=True)
84
+ def generate(
85
+ self,
86
+ *,
87
+ extra_headers: Mapping[str, str] | None = None,
88
+ timeout: float | None = None,
89
+ max_retries: int | None = None,
90
+ extra_body: Mapping[str, object] | None = None,
91
+ **params: Unpack[ImageGenerateParams],
92
+ ) -> APIResponse[ImageGenerateResponse]:
93
+ """Generates images from a prompt; see :meth:`Images.generate`."""
94
+ response = self._send(
95
+ "POST",
96
+ _GENERATE_PATH,
97
+ body=json_body(params, extra_body),
98
+ retry=billed_post_retry(),
99
+ options=options(timeout=timeout, max_retries=max_retries, extra_headers=extra_headers),
100
+ )
101
+ return with_data(response, parse_model(ImageGenerateResponse, response.data))
102
+
103
+ @overload
104
+ def edit(
105
+ self,
106
+ *,
107
+ extra_headers: Mapping[str, str] | None = None,
108
+ timeout: float | None = None,
109
+ max_retries: int | None = None,
110
+ extra_body: Mapping[str, object] | None = None,
111
+ **params: Unpack[ImageEditJsonParams],
112
+ ) -> APIResponse[ImageGenerateResponse]: ...
113
+
114
+ @overload
115
+ def edit(
116
+ self,
117
+ *,
118
+ extra_headers: Mapping[str, str] | None = None,
119
+ timeout: float | None = None,
120
+ max_retries: int | None = None,
121
+ extra_body: Mapping[str, object] | None = None,
122
+ **params: Unpack[ImageEditParams],
123
+ ) -> APIResponse[ImageGenerateResponse]: ...
124
+
125
+ @endpoint("POST", _EDIT_PATH, billed=True)
126
+ def edit(
127
+ self,
128
+ *,
129
+ extra_headers: Mapping[str, str] | None = None,
130
+ timeout: float | None = None,
131
+ max_retries: int | None = None,
132
+ extra_body: Mapping[str, object] | None = None,
133
+ **params: object,
134
+ ) -> APIResponse[ImageGenerateResponse]:
135
+ """Edits one or more images as the prompt describes; see :meth:`Images.edit`."""
136
+ body, form = _edit_request(json_body(params, extra_body))
137
+ response = self._send(
138
+ "POST",
139
+ _EDIT_PATH,
140
+ body=body,
141
+ multipart=form,
142
+ retry=billed_post_retry(),
143
+ options=options(timeout=timeout, max_retries=max_retries, extra_headers=extra_headers),
144
+ )
145
+ return with_data(response, parse_model(ImageGenerateResponse, response.data))
146
+
147
+ @endpoint("GET", _DOWNLOAD_PATH, billed=False)
148
+ def download(
149
+ self,
150
+ url: str,
151
+ *,
152
+ extra_headers: Mapping[str, str] | None = None,
153
+ timeout: float | None = None,
154
+ max_retries: int | None = None,
155
+ ) -> APIResponse[BinaryResponse]:
156
+ """Fetches a generated file; see :meth:`Images.download`."""
157
+ target = _download_url(self._client.base_url, url)
158
+ response = self._send(
159
+ "GET",
160
+ url=target,
161
+ auth=False,
162
+ kind="raw",
163
+ options=options(timeout=timeout, max_retries=max_retries, extra_headers=extra_headers),
164
+ )
165
+ return with_data(response, BinaryResponse(response.response))
166
+
167
+
168
+ class Images(SyncAPIResource):
169
+ """Images: generation, editing, and fetching generated files."""
170
+
171
+ @property
172
+ def with_response(self) -> ImagesWithResponse:
173
+ """The same methods, returning the whole :class:`~devupai.APIResponse` (headers, request id, warnings)."""
174
+ return ImagesWithResponse(self._client)
175
+
176
+ @endpoint("POST", _GENERATE_PATH, billed=True)
177
+ def generate(
178
+ self,
179
+ *,
180
+ extra_headers: Mapping[str, str] | None = None,
181
+ timeout: float | None = None,
182
+ max_retries: int | None = None,
183
+ extra_body: Mapping[str, object] | None = None,
184
+ **params: Unpack[ImageGenerateParams],
185
+ ) -> ImageGenerateResponse:
186
+ """Generates images from a prompt (``POST /images/generations``, JSON).
187
+
188
+ The body fields are passed as keyword arguments. ``extra_body`` adds fields to the JSON body (merged last),
189
+ ``extra_headers`` adds request headers, and ``timeout`` and ``max_retries`` apply to this call only.
190
+
191
+ Example::
192
+
193
+ result = client.images.generate(model="<model-id>", prompt="A red bicycle")
194
+ """
195
+ return self.with_response.generate(
196
+ extra_headers=extra_headers, timeout=timeout, max_retries=max_retries, extra_body=extra_body, **params
197
+ ).data
198
+
199
+ @overload
200
+ def edit(
201
+ self,
202
+ *,
203
+ extra_headers: Mapping[str, str] | None = None,
204
+ timeout: float | None = None,
205
+ max_retries: int | None = None,
206
+ extra_body: Mapping[str, object] | None = None,
207
+ **params: Unpack[ImageEditJsonParams],
208
+ ) -> ImageGenerateResponse: ...
209
+
210
+ @overload
211
+ def edit(
212
+ self,
213
+ *,
214
+ extra_headers: Mapping[str, str] | None = None,
215
+ timeout: float | None = None,
216
+ max_retries: int | None = None,
217
+ extra_body: Mapping[str, object] | None = None,
218
+ **params: Unpack[ImageEditParams],
219
+ ) -> ImageGenerateResponse: ...
220
+
221
+ @endpoint("POST", _EDIT_PATH, billed=True)
222
+ def edit(
223
+ self,
224
+ *,
225
+ extra_headers: Mapping[str, str] | None = None,
226
+ timeout: float | None = None,
227
+ max_retries: int | None = None,
228
+ extra_body: Mapping[str, object] | None = None,
229
+ **params: object,
230
+ ) -> ImageGenerateResponse:
231
+ """Edits one or more images as the prompt describes (``POST /images/edits``).
232
+
233
+ The request takes one of two forms, chosen from the input images (``image``, ``images``, ``mask``,
234
+ ``markup``):
235
+
236
+ - When every input is an HTTPS URL or a data URI (a string or ``{"image_url": ...}``), the params are sent as
237
+ JSON, exactly as given.
238
+ - When at least one input is a file (bytes, a path, an open binary file, or a ``(filename, content)`` /
239
+ ``(filename, content, content_type)`` tuple), the params are sent as ``multipart/form-data``: one ``image``
240
+ part per input image, in order; one ``mask`` and one ``markup`` part when given (a file, or a URL or data
241
+ URI as text); every other field as a text part (an object or a list as its JSON text). A path is opened and
242
+ closed by the SDK; an open file is read and left open.
243
+
244
+ The body fields are passed as keyword arguments. ``extra_body`` adds fields to the body (merged last),
245
+ ``extra_headers`` adds request headers, and ``timeout`` and ``max_retries`` apply to this call only.
246
+
247
+ Example::
248
+
249
+ result = client.images.edit(
250
+ model="<model-id>",
251
+ prompt="Replace the sky with a starry night",
252
+ images=["https://example.com/photo.png"],
253
+ mask={"image_url": "https://example.com/mask.png"},
254
+ )
255
+
256
+ result = client.images.edit(model="<model-id>", prompt="Add a hat", image=Path("photo.png"))
257
+ """
258
+ # The implementation behind the overloads takes any fields: the call goes through its plain signature.
259
+ edit = cast("Callable[..., APIResponse[ImageGenerateResponse]]", self.with_response.edit)
260
+ return edit(
261
+ extra_headers=extra_headers, timeout=timeout, max_retries=max_retries, extra_body=extra_body, **params
262
+ ).data
263
+
264
+ @endpoint("GET", _DOWNLOAD_PATH, billed=False)
265
+ def download(
266
+ self,
267
+ url: str,
268
+ *,
269
+ extra_headers: Mapping[str, str] | None = None,
270
+ timeout: float | None = None,
271
+ max_retries: int | None = None,
272
+ ) -> BinaryResponse:
273
+ """Fetches a generated image or video file from the URL returned by the API.
274
+
275
+ Pass the URL exactly as you received it (for example ``result.data[0].url``). Only URLs on the same origin as
276
+ the client's ``base_url`` (scheme, host and port), without a user name or password, are fetched; any other
277
+ value raises a :class:`~devupai.DevupAPIError` with the code ``invalid_url`` before any request is sent. No
278
+ API key is sent. Send a ``Range`` header in ``extra_headers`` to fetch part of the file.
279
+
280
+ The result is a :class:`~devupai.BinaryResponse` with the body unread: read it with ``read()``,
281
+ ``iter_bytes()`` or ``write_to_file()``, and close it (or use it in a ``with`` block).
282
+
283
+ Example::
284
+
285
+ with client.images.download(result.data[0].url) as file:
286
+ file.write_to_file("image.png")
287
+ """
288
+ return self.with_response.download(
289
+ url, extra_headers=extra_headers, timeout=timeout, max_retries=max_retries
290
+ ).data
291
+
292
+
293
+ class AsyncImagesWithResponse(AsyncAPIResource):
294
+ """The methods of :class:`AsyncImages`, returning the whole :class:`~devupai.APIResponse`."""
295
+
296
+ @endpoint("POST", _GENERATE_PATH, billed=True)
297
+ async def generate(
298
+ self,
299
+ *,
300
+ extra_headers: Mapping[str, str] | None = None,
301
+ timeout: float | None = None,
302
+ max_retries: int | None = None,
303
+ extra_body: Mapping[str, object] | None = None,
304
+ **params: Unpack[ImageGenerateParams],
305
+ ) -> APIResponse[ImageGenerateResponse]:
306
+ """Generates images from a prompt; see :meth:`AsyncImages.generate`."""
307
+ response = await self._send(
308
+ "POST",
309
+ _GENERATE_PATH,
310
+ body=json_body(params, extra_body),
311
+ retry=billed_post_retry(),
312
+ options=options(timeout=timeout, max_retries=max_retries, extra_headers=extra_headers),
313
+ )
314
+ return with_data(response, parse_model(ImageGenerateResponse, response.data))
315
+
316
+ @overload
317
+ async def edit(
318
+ self,
319
+ *,
320
+ extra_headers: Mapping[str, str] | None = None,
321
+ timeout: float | None = None,
322
+ max_retries: int | None = None,
323
+ extra_body: Mapping[str, object] | None = None,
324
+ **params: Unpack[ImageEditJsonParams],
325
+ ) -> APIResponse[ImageGenerateResponse]: ...
326
+
327
+ @overload
328
+ async def edit(
329
+ self,
330
+ *,
331
+ extra_headers: Mapping[str, str] | None = None,
332
+ timeout: float | None = None,
333
+ max_retries: int | None = None,
334
+ extra_body: Mapping[str, object] | None = None,
335
+ **params: Unpack[ImageEditParams],
336
+ ) -> APIResponse[ImageGenerateResponse]: ...
337
+
338
+ @endpoint("POST", _EDIT_PATH, billed=True)
339
+ async def edit(
340
+ self,
341
+ *,
342
+ extra_headers: Mapping[str, str] | None = None,
343
+ timeout: float | None = None,
344
+ max_retries: int | None = None,
345
+ extra_body: Mapping[str, object] | None = None,
346
+ **params: object,
347
+ ) -> APIResponse[ImageGenerateResponse]:
348
+ """Edits one or more images as the prompt describes; see :meth:`AsyncImages.edit`."""
349
+ body, form = _edit_request(json_body(params, extra_body))
350
+ response = await self._send(
351
+ "POST",
352
+ _EDIT_PATH,
353
+ body=body,
354
+ multipart=form,
355
+ retry=billed_post_retry(),
356
+ options=options(timeout=timeout, max_retries=max_retries, extra_headers=extra_headers),
357
+ )
358
+ return with_data(response, parse_model(ImageGenerateResponse, response.data))
359
+
360
+ @endpoint("GET", _DOWNLOAD_PATH, billed=False)
361
+ async def download(
362
+ self,
363
+ url: str,
364
+ *,
365
+ extra_headers: Mapping[str, str] | None = None,
366
+ timeout: float | None = None,
367
+ max_retries: int | None = None,
368
+ ) -> APIResponse[AsyncBinaryResponse]:
369
+ """Fetches a generated file; see :meth:`AsyncImages.download`."""
370
+ target = _download_url(self._client.base_url, url)
371
+ response = await self._send(
372
+ "GET",
373
+ url=target,
374
+ auth=False,
375
+ kind="raw",
376
+ options=options(timeout=timeout, max_retries=max_retries, extra_headers=extra_headers),
377
+ )
378
+ return with_data(response, AsyncBinaryResponse(response.response))
379
+
380
+
381
+ class AsyncImages(AsyncAPIResource):
382
+ """Images: generation, editing, and fetching generated files."""
383
+
384
+ @property
385
+ def with_response(self) -> AsyncImagesWithResponse:
386
+ """The same methods, returning the whole :class:`~devupai.APIResponse` (headers, request id, warnings)."""
387
+ return AsyncImagesWithResponse(self._client)
388
+
389
+ @endpoint("POST", _GENERATE_PATH, billed=True)
390
+ async def generate(
391
+ self,
392
+ *,
393
+ extra_headers: Mapping[str, str] | None = None,
394
+ timeout: float | None = None,
395
+ max_retries: int | None = None,
396
+ extra_body: Mapping[str, object] | None = None,
397
+ **params: Unpack[ImageGenerateParams],
398
+ ) -> ImageGenerateResponse:
399
+ """Generates images from a prompt (``POST /images/generations``, JSON).
400
+
401
+ The body fields are passed as keyword arguments. ``extra_body`` adds fields to the JSON body (merged last),
402
+ ``extra_headers`` adds request headers, and ``timeout`` and ``max_retries`` apply to this call only.
403
+
404
+ Example::
405
+
406
+ result = await client.images.generate(model="<model-id>", prompt="A red bicycle")
407
+ """
408
+ response = await self.with_response.generate(
409
+ extra_headers=extra_headers, timeout=timeout, max_retries=max_retries, extra_body=extra_body, **params
410
+ )
411
+ return response.data
412
+
413
+ @overload
414
+ async def edit(
415
+ self,
416
+ *,
417
+ extra_headers: Mapping[str, str] | None = None,
418
+ timeout: float | None = None,
419
+ max_retries: int | None = None,
420
+ extra_body: Mapping[str, object] | None = None,
421
+ **params: Unpack[ImageEditJsonParams],
422
+ ) -> ImageGenerateResponse: ...
423
+
424
+ @overload
425
+ async def edit(
426
+ self,
427
+ *,
428
+ extra_headers: Mapping[str, str] | None = None,
429
+ timeout: float | None = None,
430
+ max_retries: int | None = None,
431
+ extra_body: Mapping[str, object] | None = None,
432
+ **params: Unpack[ImageEditParams],
433
+ ) -> ImageGenerateResponse: ...
434
+
435
+ @endpoint("POST", _EDIT_PATH, billed=True)
436
+ async def edit(
437
+ self,
438
+ *,
439
+ extra_headers: Mapping[str, str] | None = None,
440
+ timeout: float | None = None,
441
+ max_retries: int | None = None,
442
+ extra_body: Mapping[str, object] | None = None,
443
+ **params: object,
444
+ ) -> ImageGenerateResponse:
445
+ """Edits one or more images as the prompt describes (``POST /images/edits``).
446
+
447
+ The request takes one of two forms, chosen from the input images (``image``, ``images``, ``mask``,
448
+ ``markup``):
449
+
450
+ - When every input is an HTTPS URL or a data URI (a string or ``{"image_url": ...}``), the params are sent as
451
+ JSON, exactly as given.
452
+ - When at least one input is a file (bytes, a path, an open binary file, or a ``(filename, content)`` /
453
+ ``(filename, content, content_type)`` tuple), the params are sent as ``multipart/form-data``: one ``image``
454
+ part per input image, in order; one ``mask`` and one ``markup`` part when given (a file, or a URL or data
455
+ URI as text); every other field as a text part (an object or a list as its JSON text). A path is opened and
456
+ closed by the SDK; an open file is read and left open.
457
+
458
+ The body fields are passed as keyword arguments. ``extra_body`` adds fields to the body (merged last),
459
+ ``extra_headers`` adds request headers, and ``timeout`` and ``max_retries`` apply to this call only.
460
+
461
+ Example::
462
+
463
+ result = await client.images.edit(
464
+ model="<model-id>",
465
+ prompt="Replace the sky with a starry night",
466
+ images=["https://example.com/photo.png"],
467
+ )
468
+ """
469
+ # The implementation behind the overloads takes any fields: the call goes through its plain signature.
470
+ edit = cast("Callable[..., Awaitable[APIResponse[ImageGenerateResponse]]]", self.with_response.edit)
471
+ response = await edit(
472
+ extra_headers=extra_headers, timeout=timeout, max_retries=max_retries, extra_body=extra_body, **params
473
+ )
474
+ return response.data
475
+
476
+ @endpoint("GET", _DOWNLOAD_PATH, billed=False)
477
+ async def download(
478
+ self,
479
+ url: str,
480
+ *,
481
+ extra_headers: Mapping[str, str] | None = None,
482
+ timeout: float | None = None,
483
+ max_retries: int | None = None,
484
+ ) -> AsyncBinaryResponse:
485
+ """Fetches a generated image or video file from the URL returned by the API.
486
+
487
+ Pass the URL exactly as you received it (for example ``result.data[0].url``). Only URLs on the same origin as
488
+ the client's ``base_url`` (scheme, host and port), without a user name or password, are fetched; any other
489
+ value raises a :class:`~devupai.DevupAPIError` with the code ``invalid_url`` before any request is sent. No
490
+ API key is sent. Send a ``Range`` header in ``extra_headers`` to fetch part of the file.
491
+
492
+ The result is an :class:`~devupai.AsyncBinaryResponse` with the body unread: read it with ``await read()``,
493
+ ``aiter_bytes()`` or ``await write_to_file()``, and close it (or use it in an ``async with`` block).
494
+
495
+ Example::
496
+
497
+ async with await client.images.download(result.data[0].url) as file:
498
+ await file.write_to_file("image.png")
499
+ """
500
+ response = await self.with_response.download(
501
+ url, extra_headers=extra_headers, timeout=timeout, max_retries=max_retries
502
+ )
503
+ return response.data